@marianmeres/design-tokens 1.11.0 → 1.13.0

package/AGENTS.md

@@ -15,7 +15,9 @@
 
 CSS custom property generator for design token systems. Takes a structured
 `ThemeSchema` (light + optional dark mode) and produces CSS `--custom-property`
-declarations with automatic hover/active state derivation via `color-mix()`.
+declarations with automatic hover/active state derivation via `color-mix()`, plus a
+precomputed `@supports` fallback so the output still renders on engines that predate
+`color-mix()` (Chrome/Edge < 111, Safari < 16.2, Firefox < 113).
 
 Entry points:
 
@@ -30,13 +32,14 @@ Entry points:
 /src
   mod.ts              — main entry: re-exports functions, types, colors
   types.ts            — core type definitions (ThemeSchema, TokenSchema, etc.)
-  generate.ts         — token generation + CSS output (generateCssTokens, toCssString, generateThemeCss)
+  generate.ts         — token generation + CSS output (generateCssTokens, toCssString, generateThemeCss) + static fallback resolution
+  color.ts            — color parsing, sRGB<->OKLab, spec-accurate color-mix() evaluation, rgba() authoring helper
   utils.ts            — hex color parsing (hexToRgb, hexToRgbTriplet)
   colors.ts           — Tailwind color palette (v3 + v4.2 additions: taupe, mauve, mist, olive), as const
   reboot-bridge.ts    — Bootstrap Reboot --bs-* variable mapping
   /themes
     mod.ts            — auto-generated barrel + runtime registry (via scripts/build-themes-mod.ts)
-    *.ts              — individual theme files (default export: ThemeSchema)
+    *.ts              — individual theme files (default export: ThemeSchema; `ring` uses rgba(), never color-mix)
 /css                  — pre-built CSS files (generated by scripts/build-css.ts; filenames = kebab-case theme names)
 /tests                — test files (deno test --allow-read)
 /scripts
@@ -51,13 +54,20 @@ Entry points:
 
 ### Functions (from `./src/mod.ts`)
 
-| Function                                      | Purpose                                                                                             |
-| --------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `generateCssTokens(schema, prefix, options?)` | Generate token key-value pairs. Third arg: `GenerateOptions` object or `"light"`/`"dark"` shorthand |
-| `toCssString(tokens, selector?)`              | Convert tokens to a CSS declaration block (groups by base color name)                               |
-| `generateThemeCss(schema, prefix, options?)`  | Generate complete CSS for light + optional dark mode; supports `cssLayer` wrapping and `prettierIgnore` pragma       |
-| `hexToRgb(hex)`                               | Parse hex to `[r, g, b]` tuple                                                                      |
-| `hexToRgbTriplet(hex)`                        | Convert hex to `"r, g, b"` string                                                                   |
+| Function                                      | Purpose                                                                                                                    |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `generateCssTokens(schema, prefix, options?)` | Generate token key-value pairs. Third arg: `GenerateOptions` object or `"light"`/`"dark"` shorthand                        |
+| `toCssString(tokens, selector?)`              | Convert tokens to a CSS declaration block (groups by base color name)                                                      |
+| `generateThemeCss(schema, prefix, options?)`  | Generate complete CSS for light + optional dark mode; supports `fallback`, `cssLayer` wrapping and `prettierIgnore` pragma |
+| `resolveStaticTokens(tokens)`                 | Evaluate every `color-mix()` in a record to a literal color                                                                |
+| `resolveStaticOverrides(tokens)`              | Only the tokens that carried a `color-mix()`, precomputed — use to audit legacy exposure                                   |
+| `staticFallbackCss(entries)`                  | Build the `@supports not (...)` block backing up a set of `{selector, tokens}` blocks                                      |
+| `rgba(color, alpha)`                          | `color-mix()`-free translucent tint; use this in theme schemas                                                             |
+| `parseColor(value)` / `formatColor(color)`    | CSS color ↔ `Rgba` (hex, rgb, hsl, oklab, oklch, keywords)                                                                 |
+| `mixColors(space, c1, p1, c2, p2)`            | Spec-accurate `color-mix()` math (premultiplied, CSS Color 5 percentages)                                                  |
+| `evaluateColorExpression(expr, lookup?)`      | Resolve a `var()`/`color-mix()` expression to a literal; `null` when not statically resolvable                             |
+| `hexToRgb(hex)`                               | Parse hex to `[r, g, b]` tuple                                                                                             |
+| `hexToRgbTriplet(hex)`                        | Convert hex to `"r, g, b"` string                                                                                          |
 
 ### Functions (from `./reboot`)
 
@@ -74,18 +84,22 @@ Entry points:
 
 ### Key Types
 
-| Type                    | Purpose                                                                         |
-| ----------------------- | ------------------------------------------------------------------------------- |
-| `ThemeSchema`           | `{ light: TokenSchema; dark?: TokenSchema }`                                    |
-| `TokenSchema`           | Intent colors, role paired/single colors                                        |
-| `ColorPair`             | `{ DEFAULT, foreground, hover?, active?, foregroundHover?, foregroundActive? }` |
-| `ColorValue`            | `{ DEFAULT, hover?, active? }`                                                  |
-| `SingleColor`           | `string \| ColorValue`                                                          |
-| `GeneratedTokens`       | `Record<string, string>`                                                        |
-| `GenerateOptions`       | `{ mode?, deriveStates?, surfaceForegroundContrast? }`                          |
-| `GenerateThemeOptions`  | `Omit<GenerateOptions, "mode"> & { cssLayer?, prettierIgnore? }`                |
-| `RolePairedKey`         | Required: `"background" \| "muted" \| "surface"`                                |
-| `RolePairedOptionalKey` | Optional: `"surface-1"` (all bundled themes ship it)                            |
+| Type                    | Purpose                                                                                   |
+| ----------------------- | ----------------------------------------------------------------------------------------- |
+| `ThemeSchema`           | `{ light: TokenSchema; dark?: TokenSchema }`                                              |
+| `TokenSchema`           | Intent colors, role paired/single colors                                                  |
+| `ColorPair`             | `{ DEFAULT, foreground, hover?, active?, foregroundHover?, foregroundActive? }`           |
+| `ColorValue`            | `{ DEFAULT, hover?, active? }`                                                            |
+| `SingleColor`           | `string \| ColorValue`                                                                    |
+| `GeneratedTokens`       | `Record<string, string>`                                                                  |
+| `GenerateOptions`       | `{ mode?, deriveStates?, fallback?, surfaceForegroundContrast? }`                         |
+| `GenerateThemeOptions`  | `Omit<GenerateOptions, "mode" \| "fallback"> & { fallback?, cssLayer?, prettierIgnore? }` |
+| `TokenFallback`         | `"none" \| "static"` — record-level legacy strategy                                       |
+| `ThemeFallback`         | `TokenFallback \| "supports"` — stylesheet-level, default `"supports"`                    |
+| `Rgba`                  | `{ r, g, b, a }`, all `0..1`                                                              |
+| `MixSpace`              | `"srgb" \| "srgb-linear" \| "oklab"`                                                      |
+| `RolePairedKey`         | Required: `"background" \| "muted" \| "surface"`                                          |
+| `RolePairedOptionalKey` | Optional: `"surface-1"` (all bundled themes ship it)                                      |
 
 ### Constants
 
@@ -102,11 +116,14 @@ Entry points:
 2. Token naming: `--{prefix}color-{key}`, `--{prefix}color-{key}-hover`, etc.
 3. Prefix is auto-normalized — `"my"` and `"my-"` both produce `--my-color-*`. Empty string produces unprefixed.
 4. Hover/active auto-derived via `color-mix(in oklab, ...)` with a per-bucket strategy: **intent** colors (saturated brand) mix toward `black` / `white` 10%/20% (mode-aware); **role** colors (paired + single) mix toward `var(--{prefix}color-foreground)` 10%/20% for a softer, theme-tinted shift. `oklab` (rectangular) is used rather than `oklch` (polar) because polar hue interpolation collapses to a powerless hue on low-chroma colors mixed toward black/white, painting as a red/mauve shift on near-neutral themes. Disable with `deriveStates: false`.
-5. Surface-intent tokens derived via `color-mix(in srgb, ...)` from intent + background. Foreground contrast defaults to 50% — tune via `surfaceForegroundContrast`. Note `surface-{intent}-border` mixes the intent color 30% **toward `background`** — it is the *outer* edge of an intent-tinted surface seen against the page, **not** an inner divider drawn on top of a surface.
+5. Surface-intent tokens derived via `color-mix(in srgb, ...)` from intent + background. Foreground contrast defaults to 50% — tune via `surfaceForegroundContrast`. Note `surface-{intent}-border` mixes the intent color 30% **toward `background`** — it is the _outer_ edge of an intent-tinted surface seen against the page, **not** an inner divider drawn on top of a surface.
 6. Theme files use `export default` with `ThemeSchema` type annotation. All bundled themes include an optional `surface-1` paired role (extra elevation).
 7. Formatting: tabs, 90-char line width, 4-space indent width (`deno fmt`)
 8. MCP handlers must return `Promise<string>` — framework contract from `jsr:@marianmeres/mcp-server/types`.
-9. **Layering semantics for dividers/hairlines**: `border` is calibrated against the **page background / muted** layer (≈ background + one step) and is hand-authored per theme — it may deliberately equal a `surface` step (e.g. dark themes where `border` == `surface` == the same neutral), so it is **not** a safe divider drawn *on top of* a `surface`. For an on-surface hairline/divider use `surface-1` (one curated step from `surface` in both modes). There is intentionally no dedicated `surface-border` token — `surface-1` covers the case, and the name would collide with the outer-edge meaning of `surface-{intent}-border` (see #5).
+9. **`color-mix()` is a browser requirement, and as a token value it has no consumer-side remedy.** `color-mix()` needs Chrome/Edge 111+, Safari 16.2+, Firefox 113+. In a normal declaration that's harmless (parse-time rejection → earlier declaration wins). As a _custom property value_ the declaration parses everywhere and fails only at substitution, making the using declaration invalid at computed-value time → `unset` (transparent background / inherited text). Neither an earlier declaration nor `var(--token, #fallback)` helps, because the property is defined; its value is just unusable. Hence `generateThemeCss` defaults to `fallback: "supports"`, emitting precomputed literals in a trailing `@supports not (color: color-mix(in oklab, red, blue))` block. **The guard must stay a negated declaration test** — a bare `@supports (color-mix(...))` is the `<general-enclosed>` production, which the spec requires to evaluate to false everywhere, silently handing the fallback to modern engines too.
+10. **`deriveStates` is a design knob, not a compatibility one.** It flattens hover/active; it does NOT remove `color-mix()` (surface-`{intent}` is derived regardless, and author-supplied values pass through). Use `fallback: "static"` for `color-mix()`-free output.
+11. **Theme schemas must not contain `color-mix()`.** Use `rgba(color, alpha)` — exactly equivalent to `color-mix(in srgb, <color> <α>%, transparent)` because mixing with `transparent` is premultiplied, but with no browser requirement. A `color-mix()` in a schema propagates into that token's derived states too.
+12. **Layering semantics for dividers/hairlines**: `border` is calibrated against the **page background / muted** layer (≈ background + one step) and is hand-authored per theme — it may deliberately equal a `surface` step (e.g. dark themes where `border` == `surface` == the same neutral), so it is **not** a safe divider drawn _on top of_ a `surface`. For an on-surface hairline/divider use `surface-1` (one curated step from `surface` in both modes). There is intentionally no dedicated `surface-border` token — `surface-1` covers the case, and the name would collide with the outer-edge meaning of `surface-{intent}-border` (see #5).
 
 ## Adding a New Theme
 
@@ -124,8 +141,12 @@ Entry points:
 - [ ] Follow `deno fmt` conventions
 - [ ] Ensure new exports have JSDoc + explicit return types
 - [ ] If changing generator output (CSS text), note as potential BC change
+- [ ] If changing derivation or color math, run `deno task css:build` and confirm the diff is what you expect
+- [ ] Never emit `color-mix()` without a fallback path — tests assert the `@supports` block covers every `color-mix()` token exactly
 
 ## Known Limitations
 
 - **JSR does not support directory exports** → pre-built CSS is npm-only.
-- **Reboot `-rgb` companions** are omitted for tokens whose values are `color-mix()` expressions (auto-derived hovers). Provide explicit hex `hover` / `active` if you need full alpha-blend support through Reboot's `rgba(var(--bs-…-rgb), α)` rules.
+- **Reboot `-rgb` companions** are omitted for tokens whose values are `color-mix()` expressions (auto-derived hovers). Pass `fallback: "static"` (or provide explicit hex `hover` / `active`) if you need full alpha-blend support through Reboot's `rgba(var(--bs-…-rgb), α)` rules.
+- **Static fallback coverage is not total.** `evaluateColorExpression` handles `srgb` / `srgb-linear` / `oklab` interpolation over hex, `rgb()`, `hsl()`, `oklab()`, `oklch()` and the basic keywords. Author-supplied `color-mix(in oklch/hsl/lab, …)`, `currentColor`, and undefined variables are deliberately left unevaluated rather than approximated — those tokens are simply absent from the `@supports` block.
+- **`cssLayer` has its own baseline**: `@layer` needs Chrome 99+, Safari 15.4+, Firefox 97+. Older engines drop the whole block, leaving tokens _undefined_ — which at least makes consumer-side `var(--token, #fallback)` fire.

package/API.md

@@ -12,7 +12,8 @@ Generate CSS token key-value pairs from a single-mode token schema.
 - `prefix` (`string`) — CSS variable prefix. Auto-normalized: `"my"` and `"my-"` are equivalent. `""` produces unprefixed tokens.
 - `options` (`GenerateOptions | "light" | "dark"`, optional) — A mode string for quick switching, or an options object. Default: `{}`
   - `mode` (`"light" | "dark"`, optional) — Controls two things: (a) the `surface-{intent}-foreground` contrast mix (toward `black` in light, `white` in dark), and (b) the direction of **intent** hover/active derivation (toward `black` in light, `white` in dark). **Role** hover/active is mode-independent — it always mixes toward `--{prefix}color-foreground`, which itself flips per mode. Default: `"light"`
-  - `deriveStates` (`boolean`, optional) — When `false`, missing hover/active fall back to DEFAULT instead of being derived via `color-mix()`. Useful for environments without `color-mix()` support. Default: `true`
+  - `deriveStates` (`boolean`, optional) — When `false`, missing hover/active fall back to DEFAULT instead of being derived via `color-mix()` — i.e. flat tokens with no visual state change. This is a _design_ knob, **not** a compatibility one: it does not remove `color-mix()` from the output, because `surface-{intent}` tokens are derived regardless and author-supplied `color-mix()` values pass through verbatim. Use `fallback` for that. Default: `true`
+  - `fallback` (`TokenFallback`, optional) — `"static"` evaluates every `color-mix()` at build time so the output contains none; `"none"` emits them as-is. Default: `"none"`
   - `surfaceForegroundContrast` (`number`, optional) — Mix percentage (0–100) used to derive the `surface-{intent}-foreground` token. Higher values increase contrast against the tinted surface background. Default: `50`
 
 **Returns:** `GeneratedTokens` — Key-value record of token names to CSS values (keys without the `--` prefix)
@@ -70,10 +71,11 @@ Generate complete CSS for a theme with light mode and optional dark mode.
 - `schema` (`ThemeSchema`) — Theme with required `light` and optional `dark` token schemas
 - `prefix` (`string`) — CSS variable prefix (trailing dash optional)
 - `options` (`GenerateThemeOptions`, optional) — Accepts all `GenerateOptions` (except `mode`, which is set per section) plus:
-  - `cssLayer` (`string`, optional) — Wrap the output in `@layer {name} { ... }`. Useful for CSS cascade control.
+  - `fallback` (`ThemeFallback`, optional) — How to serve engines without `color-mix()` (Chrome/Edge < 111, Safari < 16.2, Firefox < 113). `"supports"` emits normal output plus a trailing `@supports not (color: color-mix(in oklab, red, blue))` block holding precomputed literals; `"static"` precomputes everything and emits no `color-mix()` at all; `"none"` is the raw output. Default: `"supports"`
+  - `cssLayer` (`string`, optional) — Wrap the output in `@layer {name} { ... }`. Useful for CSS cascade control. Note `@layer` itself needs Chrome 99+, Safari 15.4+, Firefox 97+.
   - `prettierIgnore` (`boolean`, optional) — Prepend a `/* prettier-ignore */` comment so Prettier preserves the generated whitespace alignment when the output is written to a file that later gets formatted. Default: `false`.
 
-**Returns:** `string` — Complete CSS with `:root` for light and `:root.dark` for dark mode, optionally wrapped in `@layer`.
+**Returns:** `string` — Complete CSS with `:root` for light and `:root.dark` for dark mode, a trailing `@supports not (...)` fallback block unless disabled, optionally wrapped in `@layer`.
 
 **Example:**
 
@@ -132,12 +134,141 @@ hexToRgbTriplet("#2563eb"); // → "37, 99, 235"
 
 ---
 
+### `rgba(color, alpha)`
+
+Build an `rgba()` string from a color and an alpha value — the `color-mix()`-free way to write a translucent tint in a schema.
+
+Exactly equivalent to `color-mix(in srgb, <color> <alpha*100>%, transparent)`: mixing with `transparent` interpolates premultiplied, so only alpha changes. Unlike the `color-mix()` form it carries no browser requirement.
+
+**Parameters:**
+
+- `color` (`string`) — Any color `parseColor` understands
+- `alpha` (`number`) — Alpha in `0..1`
+
+**Returns:** `string` — `rgba(r, g, b, a)`, or `#rrggbb` when the result is opaque
+
+**Throws:** `TypeError` if `color` cannot be parsed
+
+**Example:**
+
+```typescript
+import { colors, rgba } from "@marianmeres/design-tokens";
+
+rgba(colors.blue[600], 0.25); // → "rgba(37, 99, 235, 0.25)"
+```
+
+---
+
+### `parseColor(value)`
+
+Parse a CSS color into an `Rgba`. Supports hex (3/4/6/8 digit), `rgb()`/`rgba()`, `hsl()`/`hsla()`, `oklab()`, `oklch()`, and the basic color keywords, in both legacy comma and modern space/slash syntax.
+
+Values that depend on inherited or computed state (`currentColor`, `var()`, system colors) return `null` — they are not statically resolvable.
+
+**Returns:** `Rgba | null`
+
+---
+
+### `formatColor(color)`
+
+Serialize an `Rgba` to the most compatible CSS form: `#rrggbb` when opaque, legacy `rgba(r, g, b, a)` otherwise. Out-of-gamut components are clamped.
+
+**Returns:** `string`
+
+---
+
+### `mixColors(space, c1, p1, c2, p2)`
+
+Mix two colors the way `color-mix()` does, following CSS Color 5 percentage normalization (an omitted percentage is `100 - other`; both omitted is 50/50; a sum below 100 scales the result alpha) and premultiplied-alpha interpolation.
+
+**Parameters:**
+
+- `space` (`MixSpace`) — `"srgb"`, `"srgb-linear"`, or `"oklab"`
+- `c1`, `c2` (`Rgba`) — The colors
+- `p1`, `p2` (`number | null`) — Percentages `0..100`, or `null` when omitted
+
+**Returns:** `Rgba | null` — `null` when both percentages are zero (invalid per spec)
+
+---
+
+### `evaluateColorExpression(expr, lookup?)`
+
+Evaluate a CSS color expression to a literal color, resolving `var()` references through `lookup` and computing nested `color-mix()` calls.
+
+Returns `null` when any operand is not statically resolvable — an undefined variable with no fallback, an unsupported interpolation space (`oklch`, `hsl`, `lab`, …), `currentColor`, or a reference cycle. Treat `null` as "leave the original expression alone": approximating a mix that isn't modelled exactly would be worse than omitting the fallback.
+
+**Parameters:**
+
+- `expr` (`string`) — e.g. `color-mix(in oklab, var(--x), black 10%)`
+- `lookup` (`VarLookup`, optional) — Resolves custom property names (without `--`) to their declared values
+
+**Returns:** `Rgba | null`
+
+**Example:**
+
+```typescript
+import { evaluateColorExpression, formatColor } from "@marianmeres/design-tokens";
+
+const tokens: Record<string, string> = { "app-color-primary": "#27272a" };
+const c = evaluateColorExpression(
+	"color-mix(in oklab, var(--app-color-primary), black 10%)",
+	(name) => tokens[name],
+);
+formatColor(c!); // → "#202023"
+```
+
+---
+
+### `resolveStaticTokens(tokens)`
+
+Evaluate every `color-mix()` expression in a token record at build time, returning a record of the same shape with literal colors in their place.
+
+Only values containing `color-mix()` are rewritten — plain `var()` indirection is preserved, since it needs no fallback and flattening it would defeat the Reboot bridge. Values whose operands cannot be resolved statically pass through unchanged.
+
+**Returns:** `GeneratedTokens`
+
+---
+
+### `resolveStaticOverrides(tokens)`
+
+The subset of `tokens` whose `color-mix()` values could be precomputed, mapped to their literal equivalents. Tokens without `color-mix()`, and those whose operands are not statically resolvable, are absent.
+
+Useful on its own to audit which tokens carry a `color-mix()` browser requirement, and which of those the generator can cover.
+
+**Returns:** `GeneratedTokens`
+
+**Example:**
+
+```typescript
+import { generateCssTokens, resolveStaticOverrides } from "@marianmeres/design-tokens";
+import { zinc } from "@marianmeres/design-tokens/themes";
+
+const tokens = generateCssTokens(zinc.light, "app-");
+Object.keys(resolveStaticOverrides(tokens)); // every token needing color-mix support
+```
+
+---
+
+### `staticFallbackCss(entries)`
+
+Build the `@supports not (color: color-mix(in oklab, red, blue))` block holding precomputed literals for every `color-mix()`-valued token in `entries`. Emit it _after_ the blocks it backs up — `@supports` adds no specificity, so source order is what makes it win.
+
+**Parameters:**
+
+- `entries` (`{ selector: string; tokens: GeneratedTokens }[]`) — Selector / token-record pairs, in the order they are emitted
+
+**Returns:** `string | null` — The CSS block, or `null` when nothing needs a fallback
+
+---
+
 ### `generateRebootBridge(tokens, prefix)`
 
 _Import from `@marianmeres/design-tokens/reboot`_
 
 Map design tokens to Bootstrap Reboot `--bs-*` CSS variables. Automatically generates `-rgb` triplet companions for hex color values.
 
+Bootstrap derives alpha variants via `rgba(var(--bs-foo-rgb), α)`, which needs a raw `r, g, b` triplet rather than a `var()` reference — so companions are omitted for tokens whose value is a `color-mix()` expression. Generating the tokens with `fallback: "static"` makes every value a literal and closes that gap.
+
 **Parameters:**
 
 - `tokens` (`GeneratedTokens`) — Generated token pairs (from `generateCssTokens`)
@@ -159,9 +290,9 @@ Generate complete themed CSS including both design tokens AND the Bootstrap Rebo
 
 - `schema` (`ThemeSchema`) — Theme schema with light and optional dark modes
 - `prefix` (`string`) — CSS variable prefix (trailing dash optional)
-- `options` (`Omit<GenerateThemeOptions, "cssLayer">`, optional) — Forwarded to `generateCssTokens` for each mode (see `generateCssTokens`)
+- `options` (`Omit<GenerateThemeOptions, "cssLayer">`, optional) — Forwarded to `generateCssTokens` for each mode (see `generateCssTokens`). `fallback` defaults to `"supports"`, as in `generateThemeCss`; `"static"` additionally completes the `--bs-*-rgb` companions.
 
-**Returns:** `string` — Combined CSS with token variables and `--bs-*` bridge variables
+**Returns:** `string` — Combined CSS with token variables and `--bs-*` bridge variables, plus a trailing `@supports not (...)` fallback block unless disabled
 
 **Example:**
 
@@ -278,6 +409,7 @@ Either a plain CSS color string or an object with optional hover/active states.
 type GenerateOptions = {
 	mode?: "light" | "dark";
 	deriveStates?: boolean;
+	fallback?: TokenFallback;
 	surfaceForegroundContrast?: number;
 };
 ```
@@ -289,13 +421,66 @@ Options passed to `generateCssTokens`. See the function docs above for field mea
 ### `GenerateThemeOptions`
 
 ```typescript
-type GenerateThemeOptions = Omit<GenerateOptions, "mode"> & {
+type GenerateThemeOptions = Omit<GenerateOptions, "mode" | "fallback"> & {
+	fallback?: ThemeFallback;
 	cssLayer?: string;
 	prettierIgnore?: boolean;
 };
 ```
 
-Options passed to `generateThemeCss`. Omits `mode` (set automatically per section) and adds `cssLayer` for optional `@layer` wrapping plus `prettierIgnore` to prepend a `/* prettier-ignore */` pragma for build pipelines that pass the output through Prettier.
+Options passed to `generateThemeCss`. Omits `mode` (set automatically per section), widens `fallback` to include `"supports"`, and adds `cssLayer` for optional `@layer` wrapping plus `prettierIgnore` to prepend a `/* prettier-ignore */` pragma for build pipelines that pass the output through Prettier.
+
+---
+
+### `TokenFallback`
+
+```typescript
+type TokenFallback = "none" | "static";
+```
+
+Legacy-engine strategy for a token _record_. `"none"` emits `color-mix()` expressions as-is; `"static"` evaluates them at build time so the record contains only literal colors.
+
+---
+
+### `ThemeFallback`
+
+```typescript
+type ThemeFallback = TokenFallback | "supports";
+```
+
+Legacy-engine strategy for a _stylesheet_. Adds `"supports"`: emit the `color-mix()` values normally, then repeat the affected tokens as precomputed literals inside `@supports not (color: color-mix(in oklab, red, blue))`. Modern engines are unaffected — the base block is byte-for-byte identical to `"none"` — while older ones get working colors.
+
+The guard is a _negated declaration test_ on purpose. A bare `@supports (color-mix(...))` is the `<general-enclosed>` production, which the spec requires to evaluate to false in every browser, so it would hand the fallback to modern engines too.
+
+---
+
+### `Rgba`
+
+```typescript
+type Rgba = { r: number; g: number; b: number; a: number };
+```
+
+A color with red/green/blue components in `0..1` (gamma-encoded sRGB) and alpha in `0..1`.
+
+---
+
+### `MixSpace`
+
+```typescript
+type MixSpace = "srgb" | "srgb-linear" | "oklab";
+```
+
+Interpolation color spaces understood by `mixColors`. Deliberately narrow — these are the spaces the generator emits. Author-supplied `color-mix()` in any other space (`oklch`, `hsl`, `lab`, …) is left unevaluated rather than approximated.
+
+---
+
+### `VarLookup`
+
+```typescript
+type VarLookup = (name: string) => string | undefined;
+```
+
+Resolves a custom property name (without the leading `--`) to its declared value.
 
 ---
 

package/README.md

@@ -10,6 +10,15 @@ bridge that maps tokens to `--bs-*` variables. Same mental model as
 [@marianmeres/stuic](https://github.com/marianmeres/stuic)'s token system, but
 framework-agnostic — no Tailwind dependency.
 
+## Browser support
+
+Generated themes work everywhere. Derived tokens use `color-mix()`, which needs
+**Chrome/Edge 111+, Safari 16.2+, Firefox 113+** (all early-to-mid 2023) — so
+`generateThemeCss` also emits a precomputed fallback for older engines by default. See
+[Legacy browsers](#legacy-browsers) if you want to change that, and
+[Why the fallback matters](#why-the-fallback-matters) for why it is not something a
+consumer could patch downstream.
+
 ## Install
 
 ```sh
@@ -52,7 +61,7 @@ const theme: ThemeSchema = {
 					// *on* a surface. Use `surface-1` for on-surface dividers.
 					border: { DEFAULT: "#d4d4d4" },
 					input: { DEFAULT: "#ffffff" },
-					ring: "color-mix(in srgb, #2563eb 25%, transparent)",
+					ring: "rgba(37, 99, 235, 0.25)",
 				},
 			},
 		},
@@ -72,6 +81,9 @@ All bundled themes are available as pre-built CSS files with the `stuic-` prefix
 <link rel="stylesheet" href="node_modules/@marianmeres/design-tokens/css/mauve-teal.css">
 ```
 
+These are built with the default `fallback: "supports"`, so they render correctly on
+pre-2023 engines without any work on your side.
+
 Or via bundler import:
 
 ```ts
@@ -83,7 +95,7 @@ import "@marianmeres/design-tokens/css/mauve-teal.css";
 Use the bundled `colors` map (Tailwind palette including v4.2 additions) to avoid looking up hex values:
 
 ```ts
-import { colors, generateThemeCss } from "@marianmeres/design-tokens";
+import { colors, generateThemeCss, rgba } from "@marianmeres/design-tokens";
 import type { ThemeSchema } from "@marianmeres/design-tokens";
 
 const myTheme: ThemeSchema = {
@@ -119,7 +131,7 @@ const myTheme: ThemeSchema = {
 					foreground: colors.slate[900],
 					border: { DEFAULT: colors.slate[300] },
 					input: { DEFAULT: colors.slate[50], hover: colors.slate[100] },
-					ring: `color-mix(in srgb, ${colors.blue[600]} 25%, transparent)`,
+					ring: rgba(colors.blue[600], 0.25),
 				},
 			},
 		},
@@ -133,6 +145,11 @@ const css = generateThemeCss(myTheme, "my-");
 Hover/active states are auto-derived via `color-mix(in oklab, ...)` when omitted. You can
 provide explicit values to override the derivation.
 
+The `rgba()` helper is the `color-mix()`-free way to write a translucent tint. It is
+exactly equivalent to `color-mix(in srgb, <color> 25%, transparent)` — mixing with
+`transparent` is premultiplied, so only alpha changes — but it needs no modern-browser
+support and it keeps your schema free of expressions the generator has to work around.
+
 ## Bundled themes
 
 ```ts
@@ -159,12 +176,69 @@ if (theme) {
 
 ```ts
 generateThemeCss(zinc, "app-", {
-	deriveStates: false, // disable color-mix hover/active derivation
+	fallback: "supports", // legacy-browser strategy (default) — see below
+	deriveStates: false, // flat hover/active instead of derived states
 	surfaceForegroundContrast: 70, // stronger contrast on surface-{intent}-foreground
 	cssLayer: "tokens", // wrap output in @layer tokens { ... }
 });
 ```
 
+Note that `deriveStates: false` is a _design_ knob — it makes hover/active flat, but does
+not remove `color-mix()` from the output (`surface-{intent}` tokens are derived regardless,
+and author-supplied `color-mix()` values pass through). Use `fallback` for that.
+
+## Legacy browsers
+
+`color-mix()` needs Chrome/Edge 111+, Safari 16.2+, Firefox 113+. The `fallback` option
+controls what older engines get:
+
+| `fallback`            | Output                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------ |
+| `"supports"`(default) | Normal output, plus a trailing `@supports not (...)` block with precomputed literals |
+| `"static"`            | Every `color-mix()` evaluated at build time — the output contains none at all        |
+| `"none"`              | `color-mix()` only; breaks on older engines                                          |
+
+```css
+/* fallback: "supports" */
+:root {
+	--app-color-primary: #27272a;
+	--app-color-primary-hover: color-mix(in oklab, var(--app-color-primary), black 10%);
+}
+@supports not (color: color-mix(in oklab, red, blue)) {
+	:root {
+		--app-color-primary-hover: #202023;
+	}
+}
+```
+
+`"supports"` is the default because it is purely additive — the `:root` block is
+byte-for-byte what `"none"` produces, so modern rendering cannot shift — at a cost of
+roughly +28% output size (about +0.6 KB gzipped per theme).
+
+Pick `"static"` if you want the smallest output (it is ~35% _smaller_ than `"none"`, since
+hex literals are shorter than mix expressions) and you don't need derived tokens to track
+runtime overrides of their base color. It also completes the Reboot bridge's `--bs-*-rgb`
+companions, which can't exist while token values are expressions.
+
+Values the generator cannot evaluate at build time — an author-supplied `oklch`/`hsl`
+interpolation space, `currentColor`, an undefined variable — are left as-is rather than
+approximated, so they are simply absent from the fallback block.
+
+### Why the fallback matters
+
+`color-mix()` in an ordinary declaration is harmless on old browsers: the declaration is
+rejected at parse time and an earlier one wins, which is the standard progressive-
+enhancement pattern. As a **token value** it behaves differently. Custom properties accept
+almost any token sequence, so the declaration parses everywhere and only fails at
+substitution — making the _using_ declaration invalid at computed-value time, which
+resolves the property to `unset`: transparent for a background, inherited for `color`.
+
+That failure is unreachable from consumer CSS. It happens after the cascade has picked a
+winner, so an earlier declaration is not a fallback, and `var(--token, #333)` doesn't fire
+either — the property is defined, its value is just unusable. The result is a control that
+keeps its size, position, and hit area and simply stops being visible. Hence the fix lives
+here rather than in consumer stylesheets.
+
 ## Reboot bridge
 
 Maps design tokens to Bootstrap Reboot's `--bs-*` CSS variables:
@@ -177,6 +251,11 @@ const css = generateThemedCss(zinc, "app-");
 // → :root { --app-color-primary: ...; --bs-body-bg: ...; --bs-link-color: ...; }
 ```
 
+Takes the same `fallback` option, defaulting to `"supports"`. Bootstrap derives alpha
+variants via `rgba(var(--bs-foo-rgb), α)`, which needs a raw `r, g, b` triplet — so
+`--bs-*-rgb` companions are only emitted for tokens that resolve to a literal color. Pass
+`fallback: "static"` if you need them all.
+
 ## API
 
 See [API.md](API.md) for the complete API documentation.

package/dist/color.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Color parsing and mixing math.
+ *
+ * Exists so the generator can evaluate its own `color-mix()` expressions at
+ * build time and emit literal colors for engines that predate `color-mix()`
+ * (Chrome/Edge < 111, Safari < 16.2, Firefox < 113). See the `fallback` option
+ * in {@link ./generate.ts}.
+ *
+ * Everything here mirrors CSS Color 4/5 semantics: premultiplied-alpha
+ * interpolation, the `color-mix()` percentage normalization rules, and the
+ * OKLab transfer functions.
+ *
+ * @module
+ */
+/**
+ * A color with red/green/blue components in `0..1` (gamma-encoded sRGB) and
+ * alpha in `0..1`.
+ */
+export type Rgba = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+/**
+ * Interpolation color spaces understood by {@link mixColors}.
+ *
+ * Deliberately narrow — these are the spaces the generator emits. Author-
+ * supplied `color-mix()` in any other space (`oklch`, `hsl`, `lab`, …) is left
+ * unevaluated rather than approximated; see {@link evaluateColorExpression}.
+ */
+export type MixSpace = "srgb" | "srgb-linear" | "oklab";
+/**
+ * Parse a CSS color into {@link Rgba}. Returns null for anything not
+ * statically resolvable.
+ *
+ * Supported: hex (3/4/6/8 digit), `rgb()`/`rgba()`, `hsl()`/`hsla()`,
+ * `oklab()`, `oklch()`, and the basic color keywords. Values that depend on
+ * inherited or computed state (`currentColor`, `var()`, system colors) are
+ * intentionally NOT supported here — see {@link evaluateColorExpression} for
+ * `var()` resolution.
+ */
+export declare function parseColor(value: string): Rgba | null;
+/**
+ * Serialize to the most compatible CSS form: `#rrggbb` when fully opaque,
+ * legacy `rgba(r, g, b, a)` otherwise. Legacy `rgba()` is deliberate — the
+ * whole point of the static fallback is reaching engines that predate the
+ * modern space-separated syntax.
+ */
+export declare function formatColor(color: Rgba): string;
+/**
+ * Mix two colors the way `color-mix()` does.
+ *
+ * Percentages follow CSS Color 5 normalization: an omitted percentage is
+ * `100 - other`, both omitted is 50/50, and when the two sum to less than 100
+ * the result's alpha is scaled by that sum. Interpolation is premultiplied by
+ * alpha, which is why mixing an opaque color with `transparent` preserves the
+ * color and only lowers alpha.
+ *
+ * @param space - Interpolation space
+ * @param c1 - First color
+ * @param p1 - First percentage (0-100), or null when omitted
+ * @param c2 - Second color
+ * @param p2 - Second percentage (0-100), or null when omitted
+ * @returns The mixed color, or null if both percentages are zero (invalid)
+ */
+export declare function mixColors(space: MixSpace, c1: Rgba, p1: number | null, c2: Rgba, p2: number | null): Rgba | null;
+/** Look up the value of a custom property by its name, without the leading `--`. */
+export type VarLookup = (name: string) => string | undefined;
+/**
+ * Evaluate a CSS color expression to a literal color, resolving `var()`
+ * references through `lookup` and computing nested `color-mix()` calls.
+ *
+ * Returns null when any operand is not statically resolvable — an undefined
+ * variable with no fallback, an unsupported interpolation space (`oklch`,
+ * `hsl`, `lab`, …), `currentColor`, a reference cycle, and so on. Callers
+ * should treat null as "leave the original expression alone" rather than as an
+ * error; approximating a mix we don't model exactly would be worse than
+ * omitting the fallback.
+ *
+ * @param expr - The expression, e.g. `color-mix(in oklab, var(--x), black 10%)`
+ * @param lookup - Resolves custom property names to their declared values
+ */
+export declare function evaluateColorExpression(expr: string, lookup?: VarLookup): Rgba | null;
+/**
+ * Build an `rgba()` string from an opaque color and an alpha value.
+ *
+ * Provided for theme authors: `rgba(colors.blue[600], 0.25)` is exactly
+ * equivalent to `color-mix(in srgb, <blue-600> 25%, transparent)` (mixing with
+ * `transparent` is premultiplied, so only alpha changes) but carries no
+ * `color-mix()` browser requirement.
+ *
+ * @param color - Any color {@link parseColor} understands
+ * @param alpha - Alpha in `0..1`
+ * @throws If `color` cannot be parsed
+ */
+export declare function rgba(color: string, alpha: number): string;