--- name: alouette-theming description: > Re-theme a subtree with accents (brand, danger, info, success, warning) and light/dark modes. Use the accent prop, AccentScope, or ScopedTheme; children always consume base tokens (bg-surface, text-accent, text-sharp, text-muted, border-muted). Tokens are className-only: alouette exports no JS token-read hook. Read the current mode with useCurrentMode. For an accent that toggles at runtime (e.g. on hover) without remounting the subtree, use StableAccentScope instead of AccentScope. Load when applying colors, accents or dark mode, or when shipping a custom palette. type: core library: alouette library_version: "22.0.0" sources: - "christophehurpeau/alouette:packages/alouette/src/ui/containers/AccentScope.tsx" - "christophehurpeau/alouette:packages/alouette/src/ui/containers/StableAccentScope.tsx" - "christophehurpeau/alouette:packages/alouette/src/ui/containers/ScopedTheme.tsx" - "christophehurpeau/alouette:packages/alouette/src/ui/containers/ScopedTheme.web.tsx" - "christophehurpeau/alouette:packages/alouette/src/core/AlouetteConfig.ts" - "christophehurpeau/alouette:packages/alouette/src/core/AlouetteProvider.tsx" - "christophehurpeau/alouette:packages/alouette/src/core/NativeThemeVariablesContext.ts" - "christophehurpeau/alouette:packages/alouette/src/theme-generator/generateTheme.ts" - "christophehurpeau/alouette:packages/alouette/src/theme-generator/writeTheme.ts" - "christophehurpeau/alouette:CLAUDE.md" --- # alouette — Theming with modes and accents alouette colors come from theme tokens, not the raw Tailwind palette. A theme is a light/dark mode optionally combined with an accent. Tokens cascade down the tree: components use **base tokens** (`bg-surface`, `text-accent`, `text-sharp`, `text-muted`, `border-muted`) and inherit the resolved value from the nearest scope. Setting an accent re-themes a whole subtree. `Accent` = `"brand" | "danger" | "info" | "success" | "warning"`. ## Setup Most alouette components — `Text`, `Surface`, `Box`, `Button`, `Message`, … — take an `accent` prop that re-themes their subtree. Prefer the prop: ```tsx import { Surface, Text } from "alouette"; Something went wrong Brand-accented text; ``` Use `AccentScope` only to re-theme a group of children at once, or children that don't accept an `accent` prop: ```tsx import { AccentScope } from "alouette";
; ``` ## Core Patterns ### Tokens are className-only alouette exports **no** hook to read a token value in JS. Apply every color through a className (`bg-surface`, `text-accent`, `border-muted`) — that is the only path that works on both platforms, because the two resolve a theme differently: - **web** — `ScopedTheme` renders a `display: contents` element carrying the theme name as a className; the palette CSS resolves the variables. The `themeVariables` map is not consulted at all. - **native** — `ScopedTheme` pushes the theme's variables through NativeWind's `VariableContextProvider`, from the `themeVariables` map given to `AlouetteProvider`. The handful of props that cannot take a className (native `Switch` colors, `placeholderTextColor`, SVG tint, the Expo browser chrome) are handled inside alouette itself, on native only; web styles them with CSS. ### Force a mode on a subtree ```tsx import { AccentScope } from "alouette"; {children} ; ``` ### Read the active mode / theme ```tsx import { useCurrentMode, useCurrentTheme } from "alouette"; const mode = useCurrentMode(); // "light" | "dark" const theme = useCurrentTheme(); // e.g. "dark_brand" ``` ### Toggle an accent without remounting the subtree ```tsx import { StableAccentScope } from "alouette"; const [pendingRemoval, setPendingRemoval] = useState(false); setPendingRemoval(true)} onHoverOut={() => setPendingRemoval(false)} onPress={onRemove} /> ; ``` ### Ship a custom palette for the existing accents An app can re-color the existing accents (`brand`, `danger`, `info`, `success`, `warning`, plus `grayscale`) on alouette's OKLCH ramp and ship only its own palette — no default CSS. A theme has two coupled outputs: the palette **CSS** and the runtime **`themeVariables`** map. The app generates them the way alouette generates its own default palette — a build script calling `alouette/theme-generator`. `writeTheme` writes both files; override only the accents you want to change (the rest inherit the defaults): ```ts // scripts/build-theme.ts — run via a package.json script: // "build:theme": "node --experimental-strip-types scripts/build-theme.ts" import { writeTheme } from "alouette/theme-generator"; writeTheme({ outDir: "src", overrides: { brand: { type: "accent", hue: 300 } }, }); ``` That writes `src/palette.css` + `src/themeVariables.ts` (sRGB hex, complete on their own) and `src/palette-oklch.css` (the OKLCH / display-p3 overlay) — names configurable via `cssFileName` / `themeVariablesFileName`, headed `DO NOT EDIT` and already formatter-stable. Commit them and re-run the script when the params change. `srgbOnly: true` skips the OKLCH file. `generateTheme(overrides)` returns the same content in memory (`{ css, oklchCss, themeVariables, oklchThemeVariables }`) for an app that writes the files itself. Both are node-only build-time APIs: never import `alouette/theme-generator` from app code. The OKLCH half is opt-in, web-only and CSS-only: `@import "./palette-oklch.css"` after `./palette.css` enables it. The `themeVariables` map has no OKLCH counterpart — web resolves every token from the CSS, and only native reads the map. See "Color format" below. Then import `alouette/core.css` + the generated palette (instead of `alouette/global.css`) and pass the map to `AlouetteProvider` so native token reads (gradients, `Switch`, `placeholderTextColor`, SVG tint) match the palette CSS: ```css /* global.css */ @import "alouette/core.css"; @import "./palette.css"; @import "./palette-oklch.css"; /* optional wide-gamut half */ ``` ```tsx import { AlouetteProvider } from "alouette"; import { themeVariables } from "./themeVariables"; {/* app */}; ``` `PaletteSpec` per accent: `type` (`"accent"` | `"brightAccent"` | `"grayscale"`), `hue` (0–360), optional `hueHi` / `hueLo` (hue ramp across lightness) and `intensity` (chroma multiplier). The accent set is fixed — this re-colors the existing accents, it does not add new ones. The palette CSS and the map are two halves of one theme: `themeVariables` is a required `AlouetteProvider` prop, so shipping custom CSS while still passing `alouette/defaultThemeVariables` type-checks but leaves every **native** token read on the default colors (web is unaffected — it never reads the map). ### Color format: OKLCH on web, hex on native Every palette is computed in OKLCH and emitted twice — sRGB hex (what native renders; React Native's color parser takes hex/rgb/hsl/hwb only) and OKLCH with display-p3 chroma headroom (what web renders: same lightness and hue ramp, more vivid accents on wide-gamut screens). Hex is the baseline; OKLCH is a separate opt-in stylesheet, imported after the hex palette: | | palette CSS | `themeVariables` map | | --- | --- | --- | | web | `palette-oklch.css` / `alouette/default-palette-oklch.css`, if imported | not read — web theming is CSS only | | native | `palette.css` (plain hex) | `themeVariables.ts` (hex) | The OKLCH CSS is additive — it re-declares the same variables behind `@supports (color: oklch(0 0 0))`, and the native compiler drops the feature query and keeps the hex. The palette CSS uses the same trick for the twelve `.` blocks, which are a web-only mechanism (native themes through `VariableContextProvider`, not classNames): they sit behind `@supports (display: contents)` and never reach the native bundle — which is why native needs the `themeVariables` map at all. The map has no OKLCH variant: the web build of `AlouetteProvider` ignores `themeVariables` entirely, so `writeTheme` emits the hex map only — the one native consumes. The default is `alouette/defaultThemeVariables` (hex, every platform). ## Common Mistakes ### HIGH Hardcoding raw Tailwind colors instead of tokens Wrong: ```tsx Hi ``` Correct: ```tsx Hi ``` Raw palette classes (`bg-blue-500`, `text-gray-600`) ignore the alouette theme, so they do not adapt to mode or accent and break dark mode. Source: CLAUDE.md (Theming and semantic roles); src/ui/containers/AccentScope.tsx ### MEDIUM Setting color manually instead of an accent Wrong: ```tsx Error ``` Correct: ```tsx Error ``` Setting `accent` re-themes the subtree so children resolve base tokens against the accent + current mode; a hardcoded color duplicates theme logic and skips mode adaptation. Source: packages/alouette/src/ui/containers/Box.tsx, AccentScope.tsx ### MEDIUM Wrapping an accent-capable component in AccentScope Wrong: ```tsx Title ``` Correct: ```tsx Title ``` `Text`, `Surface`, `Box`, `Button`, `Message` and others accept `accent` directly. Reserve `AccentScope` for grouping several children or wrapping ones that don't take the prop. Source: packages/alouette/src/ui/primitives/Text.tsx, ui/containers/AccentScope.tsx ### HIGH Reading a token value in JS instead of applying a className Wrong: ```tsx import { useUnstableNativeVariable } from "nativewind"; const color = useUnstableNativeVariable("--color-accent"); Hi; ``` Correct: ```tsx Hi ``` alouette exports no token-read hook (`useThemeToken` was removed in 21.0.0). Reaching into NativeWind's variable context directly is a native-only path: on web the theme is a className resolved by the palette CSS and nothing populates that context, so the read comes back `undefined` and the text falls back to an unthemed color. Style with the token className on both platforms. Source: packages/alouette/src/ui/containers/ScopedTheme.web.tsx, core/AlouetteProvider.web.tsx ### MEDIUM Custom palette CSS paired with the default themeVariables Wrong — importing a generated palette CSS but leaving `AlouetteProvider` on the default map: ```tsx // global.css imports core.css + ./palette.css, but: import { themeVariables } from "alouette/defaultThemeVariables"; {/* app */}; ``` Correct: ```tsx import { themeVariables } from "./themeVariables"; // writeTheme output {/* app */}; ``` A theme has two coupled outputs: the palette CSS (className tokens, the only thing web uses) and the `themeVariables` map (native token reads — gradients, `Switch`, `placeholderTextColor`, SVG tint). The prop is required, so this fails silently rather than loudly, and **only on device**: the default map type-checks fine, classNames use the custom palette, and the few native reads resolve to the default colors — so native gradients and controls mismatch the rest of the UI while web looks correct. Both must come from the same `writeTheme` call — that is why it writes the pair. Source: packages/alouette/src/core/NativeThemeVariablesContext.ts, theme-generator/writeTheme.ts ### MEDIUM Expecting var() chains to resolve on native Wrong: ```css --color-accent: var(--color-brand); ``` Correct: ```css --color-accent: #2563eb; ``` On native, NativeWind resolves CSS variables from a lookup table and cannot follow a `var()` that points at another `var()`. alouette sub-themes use concrete hex values per mode+accent for this reason. Source: CLAUDE.md (Native constraint: no CSS variable chains) ### MEDIUM Using AccentScope for an accent that toggles at runtime Wrong: ```tsx ``` Correct: ```tsx ``` `AccentScope` only renders its `ScopedTheme` wrapper when `accent` is set — it returns `children` unwrapped otherwise. Toggling `accent` therefore mounts or unmounts that wrapper in either direction, remounting the subtree and dropping focus from any input inside. `StableAccentScope` always keeps `ScopedTheme` mounted, falling back to the inherited theme when `accent` is unset, so toggling only changes the theme prop. Prefer `AccentScope` when the accent is fixed; reach for `StableAccentScope` only when it toggles. Source: packages/alouette/src/ui/containers/StableAccentScope.tsx ## References - [Token catalog](references/tokens.md) — color, spacing, radius and shadow token names. See also: alouette-typography/SKILL.md — color tokens are applied through Text.