# `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.