Initial Commit

packages/ui/react/react-ui/src/theme/themes/light.md

@@ -0,0 +1,78 @@
+# `lightTheme` — chassis-default light theme
+
+## Purpose
+
+The default `ThemePlugin` instance shipped with `@suaveplan/react-ui`.
+`lightTheme` matches the shadcn `nova` token preset: neutral OKLCH
+greyscale anchored on a near-white background and a near-black
+foreground. The chassis registers it as the first theme handed to
+`<ThemeProvider>` so apps that do not override the theme registry get
+a sensible visual default.
+
+## Features
+
+- 20 CSS-variable tokens covering background / foreground, card,
+  popover, primary, secondary, muted, accent, destructive plus the
+  border / input / ring / radius palette
+- Motion tokens (`durationFast` 120ms, `durationBase` 200ms,
+  `durationSlow` 320ms) with `respectReducedMotion: 'strict'` so users
+  who set `prefers-reduced-motion: reduce` see instant transitions
+- `labelKey: 'react-ui.themeToggle.light'` resolves through the active
+  i18n instance — `<ThemeSwitcher>` never renders a literal
+- `colorScheme: 'light'` paired with the chassis `<ThemeProvider>`'s
+  inline FOUC-prevention script so pre-hydration `<html>` already
+  carries `data-theme="light"`
+
+## Usage: Basic example
+
+```tsx
+import { ReactUiProvider } from "@suaveplan/react-ui/provider";
+import { lightTheme } from "@suaveplan/react-ui/theme/themes/light";
+
+export function App() {
+    return (
+        <ReactUiProvider i18n={i18n} themes={[lightTheme]} defaultTheme="light">
+            <YourApp />
+        </ReactUiProvider>
+    );
+}
+```
+
+## Usage: Advanced example
+
+```tsx
+import {
+    darkTheme,
+    highContrastTheme,
+    lightTheme,
+} from "@suaveplan/react-ui/theme";
+
+const themes = [lightTheme, darkTheme, highContrastTheme];
+
+<ReactUiProvider
+    i18n={i18n}
+    themes={themes}
+    defaultTheme="light"
+>
+    <YourApp />
+</ReactUiProvider>;
+```
+
+## API Reference
+
+- `lightTheme: ThemePlugin<'light'>` — the named export.
+- `lightTheme.name === 'light'` — literal-typed so narrowed
+  `useThemedVariants<'light', 'Button'>('Button')` calls compile.
+- `lightTheme.cssVariables` — the 20 OKLCH tokens.
+- `lightTheme.motionTokens` — six motion tokens + the policy.
+
+## Implementation notes
+
+The OKLCH expressions are forwarded to consumers' Tailwind v4 layers
+via the chassis `<ThemeProvider>`'s inline `style.setProperty()` calls.
+Consumers wiring their own Tailwind layer mirror the token names in
+their `@theme inline` block (`--background`, `--foreground`, etc.).
+The `radius` token is intentionally a single shared anchor (`0.5rem`)
+that downstream cva configs scale via Tailwind's `calc()` arithmetic;
+themes that want a different rounding per variant override at the cva
+config level rather than emitting per-variant tokens here.