# `theme-context` — React context plumbing for the active theme

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
  - [theme-provider](./theme-provider/theme-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_  - [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [dark](./themes/dark.md) — The dark counterpart of `lightTheme`. Same variant surface, same token names, lightness anchors inverted so foreground…
- [high-contrast](./themes/high-contrast.md) — Accessibility-first theme that meets WCAG AAA contrast for normal and large text alike. Pure-white foreground (`#FFFFFF…
- [light](./themes/light.md) — The default `ThemePlugin` instance shipped with `@suaveplan/react-ui`. `lightTheme` matches the shadcn `nova` token pre…
- [use-resolved-theme-tokens](./use-resolved-theme-tokens/use-resolved-theme-tokens.md) — `useResolvedThemeTokens()` is the read-side counterpart to `useThemeMutator()`. It returns the live merged token state…
  - [use-resolved-theme-tokens](./use-resolved-theme-tokens/use-resolved-theme-tokens.md) — `useResolvedThemeTokens()` is the read-side counterpart to `useThemeMutator()`. It returns the live merged token state…
- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_  - [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-mutator](./use-theme-mutator/use-theme-mutator.md) — `useThemeMutator()` is the public surface a consumer reaches for when it wants to push CSS custom properties onto the a…
  - [use-theme-mutator](./use-theme-mutator/use-theme-mutator.md) — `useThemeMutator()` is the public surface a consumer reaches for when it wants to push CSS custom properties onto the a…
- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_  - [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_  - [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-context](./theme-context.md) — <!-- begin:auto-docs --> _(no submodules)_- theme-provider — <!-- begin:auto-docs --> _(no submo…
- [theme-provider](./theme-provider/theme-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [dark](./themes/dark.md) — The dark counterpart of `lightTheme`. Same variant surface, same token names, lightness anchors inverted so foreground…
- [high-contrast](./themes/high-contrast.md) — Accessibility-first theme that meets WCAG AAA contrast for normal and large text alike. Pure-white foreground (`#FFFFFF…
- [light](./themes/light.md) — The default `ThemePlugin` instance shipped with `@suaveplan/react-ui`. `lightTheme` matches the shadcn `nova` token pre…
- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-context](./theme-context.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-provider](./theme-provider/theme-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [dark](./themes/dark.md) — The dark counterpart of `lightTheme`. Same variant surface, same token names, lightness anchors inverted so foreground…
- [high-contrast](./themes/high-contrast.md) — Accessibility-first theme that meets WCAG AAA contrast for normal and large text alike. Pure-white foreground (`#FFFFFF…
- [light](./themes/light.md) — The default `ThemePlugin` instance shipped with `@suaveplan/react-ui`. `lightTheme` matches the shadcn `nova` token pre…
- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-context](./theme-context.md) — <!-- begin:auto-docs --> _(no submodules)_- theme-provider — <!-- begin:…
- [theme-provider](./theme-provider/theme-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [dark](./themes/dark.md) — The dark counterpart of `lightTheme`. Same variant surface, same token names, lightness anchors inverted so foreground…
- [high-contrast](./themes/high-contrast.md) — Accessibility-first theme that meets WCAG AAA contrast for normal and large text alike. Pure-white foreground (`#FFFFFF…
- [light](./themes/light.md) — The default `ThemePlugin` instance shipped with `@suaveplan/react-ui`. `lightTheme` matches the shadcn `nova` token pre…
- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-context](./theme-context.md) — <!-- begin:auto-docs --> _(no submodules)_- theme-provider — <!-- begin:auto-docs --> _(no subm…
- [theme-provider](./theme-provider/theme-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_  - [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [dark](./themes/dark.md) — The dark counterpart of `lightTheme`. Same variant surface, same token names, lightness anchors inverted so foreground…
- [high-contrast](./themes/high-contrast.md) — Accessibility-first theme that meets WCAG AAA contrast for normal and large text alike. Pure-white foreground (`#FFFFFF…
- [light](./themes/light.md) — The default `ThemePlugin` instance shipped with `@suaveplan/react-ui`. `lightTheme` matches the shadcn `nova` token pre…
- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_  - [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_  - [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_  - [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-context](./theme-context.md) — <!-- begin:auto-docs --> _(no submodules)_
## Purpose

Owns the React `Context` `<ThemeProvider>` writes into and every theme
hook (`useTheme`, `useThemeTokens`, `useThemedVariants`,
`<ThemeSwitcher>`) reads from. The context is intentionally typed as
`ThemeContextValue | null` — `null` carries "no Provider mounted" so
hooks can throw a structured `ReactUiError(REACT_UI.NO_PROVIDER)` in
dev mode rather than silently rendering a broken UI.

## Features

- Single source-of-truth context for the chassis theme system
- `null` discriminator drives provider-missing detection in every
  consumer hook
- `displayName` set so React DevTools shows `ReactUiThemeContext`
  rather than the unhelpful `Context.Provider` default
- Exposes `reducedMotionActive` so motion-aware components can read
  the resolved `prefers-reduced-motion` policy without re-querying
  `matchMedia` themselves

## Usage: Basic example

```ts
import { useContext } from "react";
import { ThemeContext } from "@suaveplan/react-ui/theme/theme-context";

function CustomThemeAware() {
    const ctx = useContext(ThemeContext);
    if (!ctx) return null;
    return <div data-theme={ctx.theme.name}>…</div>;
}
```

## Usage: Advanced example

```ts
import { useContext } from "react";
import { ThemeContext, type ThemeContextValue } from "@suaveplan/react-ui/theme/theme-context";

function useThemeOrThrow(): ThemeContextValue {
    const ctx = useContext(ThemeContext);
    if (ctx === null) {
        throw new Error("useThemeOrThrow requires <ThemeProvider>");
    }
    return ctx;
}
```

## API Reference

- `ThemeContext: React.Context<ThemeContextValue | null>` — initial
  value `null` so unwrapped reads can be detected
- `interface ThemeContextValue` — `{ theme, themes, setTheme, isPending,
  reducedMotionActive }`

## Implementation notes

The `setTheme` callback is typed as `(name: string) => Promise<void>`
so the Provider can wrap the underlying state update in
`useTransition()` and consumers that `await setTheme('dark')` get the
DOM in its post-commit state. The `reducedMotionActive` field is
recomputed inside the Provider on `prefers-reduced-motion` media query
changes; consumers that need finer control over the motion policy
should read `theme.motionTokens.respectReducedMotion` directly via
`useTheme()`.