`useThemeTokens()` — read the active theme's CSS-variable tokens

(no submodules)

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

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

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.

2.5 KiB Raw Blame History

useThemeTokens() — read the active theme's CSS-variable tokens