first commit

docs/ui/react/react-ui/src/theme/use-theme-tokens/use-theme-tokens.md

@@ -0,0 +1,77 @@
+# `useThemeTokens()` — read the active theme's CSS-variable tokens
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Returns the live `ThemeTokenSet` for the active theme. Components
+needing direct token access (recharts colour palettes, canvas-rendered
+visualisations, third-party libraries that do not consume CSS
+variables) read this hook rather than pulling
+`useTheme().theme.cssVariables` so the dependency on the wider
+`<ThemeProvider>` context remains explicit and the React compiler can
+scope re-renders to the token slice.
+
+## Features
+
+- Returns the 20-key `ThemeTokenSet` shape defined in
+  `theme.types.ts`
+- Throws `ReactUiError(REACT_UI.NO_PROVIDER)` outside of a
+  `<ThemeProvider>`
+- Updates whenever the active theme changes — consumers always read
+  the current values
+
+## Usage: Basic example
+
+```tsx
+import { useThemeTokens } from "@suaveplan/react-ui/theme/use-theme-tokens";
+
+function ChartLegend() {
+    const tokens = useThemeTokens();
+    return <div style={{ color: tokens.foreground }}>Legend</div>;
+}
+```
+
+## Usage: Advanced example
+
+```tsx
+import { useThemeTokens } from "@suaveplan/react-ui/theme/use-theme-tokens";
+
+function PaletteRing() {
+    const t = useThemeTokens();
+    return (
+        <svg viewBox="0 0 200 200">
+            <circle cx={100} cy={100} r={80} fill={t.primary} />
+            <circle
+                cx={100}
+                cy={100}
+                r={60}
+                fill="none"
+                stroke={t.ring}
+                strokeWidth={4}
+            />
+        </svg>
+    );
+}
+```
+
+## API Reference
+
+- `useThemeTokens(): ThemeTokenSet` — the active theme's token bag.
+- Throws `ReactUiError(REACT_UI.NO_PROVIDER)` outside the Provider.
+
+## Implementation notes
+
+The hook returns the same `cssVariables` reference that
+`useTheme().theme.cssVariables` returns; the dedicated wrapper exists
+only so call sites can express their narrower dependency. A future
+optimisation could `useSyncExternalStore` on a token-only snapshot to
+make a reader unaffected by `setTheme` calls that swap the active
+theme to a different theme with identical tokens (rare, but possible
+for white-label scenarios). v1 keeps the simple reader because the
+chassis ships only three themes whose token sets all differ. Future
+themes that DO want to swap personality without changing tokens (a
+brand re-skin that only changes motion or icon library) should still
+work transparently with this hook, since the returned reference IS
+the theme's `cssVariables` field — no copy, no merge.