# Theming Guide
@fpkit/acss ships a small theming runtime — `ThemeProvider`, `useTheme`, `ThemeToggle`, and `getThemeFoucScript` — for shipping light/dark themes without a flash of the wrong colors on first paint.
This guide covers:
- [How it works](#how-it-works)
- [Quick start](#quick-start)
- [`ThemeProvider`](#themeprovider)
- [`useTheme`](#usetheme)
- [`ThemeToggle`](#themetoggle)
- [Preventing theme flash (SSR)](#preventing-theme-flash-ssr)
- [Creating a custom theme](#creating-a-custom-theme)
- [API reference](#api-reference)
- [Accessibility notes](#accessibility-notes)
---
## How it works
The runtime is built on a single DOM contract: a `data-theme="light|dark"` attribute on ``. All theme-dependent CSS variables are re-declared under `[data-theme="dark"]` selectors in [packages/fpkit/src/styles/tokens/](../../src/sass/tokens/), so toggling the attribute switches every token-driven component at once — no re-render required.
Responsibilities split three ways:
- **`ThemeProvider`** owns the user's *preference* (`"light"`, `"dark"`, or `"system"`), resolves `"system"` against `prefers-color-scheme`, and writes `data-theme` on every change.
- **`useTheme`** reads/writes preference from React components.
- **`getThemeFoucScript()`** returns a tiny inline script (<500 bytes) for SSR consumers to apply the stored preference *before* React hydrates — otherwise you see a flash of the server-rendered default.
The preference is persisted to `localStorage` under the key `"fpkit-theme-preference"` (configurable via `ThemeProvider`'s `storageKey` prop).
---
## Quick start
Wrap your app:
```tsx
import { ThemeProvider, ThemeToggle } from '@fpkit/acss';
function App() {
return (
{/* your app */}
);
}
```
That's enough for a client-only app. For SSR, see [Preventing theme flash (SSR)](#preventing-theme-flash-ssr).
---
## `ThemeProvider`
Context provider that owns theme state. Place it once, as high in the tree as possible.
```tsx
import { ThemeProvider } from '@fpkit/acss';
{children}
```
| Prop | Type | Default | Purpose |
|---|---|---|---|
| `children` | `ReactNode` | — | Subtree that can read theme via `useTheme` |
| `defaultPreference` | `"light" \| "dark" \| "system"` | `"system"` | Initial preference before the stored value loads |
| `storageKey` | `string` | `"fpkit-theme-preference"` | Where the preference persists in `localStorage` |
**What it does on mount:**
1. Reads `localStorage[storageKey]` — falls back to `defaultPreference` if missing.
2. Resolves `"system"` against `window.matchMedia('(prefers-color-scheme: dark)')`.
3. Sets `data-theme` on ``.
4. Subscribes to `prefers-color-scheme` change events so "system" mode stays in sync when the OS theme changes at runtime.
---
## `useTheme`
Hook that exposes the current state and setters. **Must be called inside a `ThemeProvider`** — it throws otherwise, intentionally, to prevent the silent desync bugs that default-to-light fallbacks cause.
```tsx
import { useTheme } from '@fpkit/acss';
function ProfileMenu() {
const { theme, preference, setPreference, toggleTheme } = useTheme();
return (
Current: {theme}
{/* "light" | "dark" — never "system" */}
Preference: {preference}
{/* "light" | "dark" | "system" */}
);
}
```
| Field | Type | Notes |
|---|---|---|
| `preference` | `"light" \| "dark" \| "system"` | What the user asked for |
| `theme` | `"light" \| "dark"` | What's actually applied right now |
| `setPreference` | `(next) => void` | Persists to `localStorage` and updates DOM |
| `toggleTheme` | `() => void` | Cycles light → dark → system → light |
Use `setPreference` when you're building a picker (three explicit buttons). Use `toggleTheme` for the single-button cycler pattern — that's what `ThemeToggle` does internally.
---
## `ThemeToggle`
Drop-in button that cycles through light → dark → system. Rendered as a `