--- 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; inside a portal (a modal or any other overlay), where the scope escapes the themed subtree, use PortalAccentScope. Load when applying colors, accents or dark mode, or when shipping a custom palette. type: core library: alouette library_version: "22.6.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/PortalAccentScope.tsx" - "christophehurpeau/alouette:packages/alouette/src/ui/containers/PortalAccentScope.web.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} /> ; ``` ### Theme a portalled subtree A portal renders outside the themed DOM subtree, so on web the theme className of its ancestors no longer applies and the accent has to be rebuilt from the base mode. `PortalAccentScope` does that — it is what `Modal` uses internally, so `Modal`'s own `accent` prop already works. Reach for it directly only when you portal something yourself: ```tsx import { PortalAccentScope } from "alouette"; {overlay} ; ``` Web nests two scopes — the outer one re-declares the full `light`/`dark` token set the portal escaped, the inner one layers the accent on top — and both stay mounted, so toggling `accent` never remounts the subtree. Native has no portal problem (`ScopedTheme` pushes merged variables through React context, which crosses wherever the host renders the tree), so there it is a single `StableAccentScope`. ### 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, type ThemeVariablesMap } from "alouette"; import { themeVariables } from "./themeVariables"; {/* app */}; ``` `ThemeVariablesMap` is exported for code that passes the map around (a theme switcher, a test helper). The `themeVariables.ts` that `writeTheme` emits already imports it from `alouette` and annotates the map with it. `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.