@marianmeres/design-tokens 1.3.0 → 1.4.0

package/AGENTS.md

@@ -1,10 +1,12 @@
 # @marianmeres/design-tokens — Agent Guide
 
 ## Quick Reference
+
 - **Stack**: Deno / TypeScript
 - **Run**: `deno task test` | **Watch**: `deno task test:watch`
 - **Build (npm)**: `deno task npm:build`
-- **Build (CSS)**: `deno task css:build` (generates pre-built CSS files + updates deno.json exports)
+- **Build (CSS)**: `deno task css:build` (generates pre-built CSS files; accepts `CSS_PREFIX` env var, default `"stuic-"`)
+- **Build (themes barrel)**: `deno task themes:build` (regenerates `src/themes/mod.ts`)
 - **Build (preview)**: `deno task preview:build`
 - **Publish**: `deno task publish` (JSR + npm)
 - **Format**: `deno fmt` (tabs, 90 chars, indent 4)
@@ -16,10 +18,11 @@ CSS custom property generator for design token systems. Takes a structured
 declarations with automatic hover/active state derivation via `color-mix()`.
 
 Entry points:
+
 - `.` — core generation functions, types, color palette
 - `./reboot` — Bootstrap Reboot `--bs-*` variable bridge
-- `./themes` — 42 pre-built theme definitions
-- `./css/*.css` — pre-built CSS files with `stuic-` prefix (npm only, not on JSR)
+- `./themes` — 43 pre-built theme definitions + `themeNames` constant + `bundledThemes` / `bundledThemeNames` / `getBundledTheme` runtime helpers
+- `./css/*.css` — pre-built CSS files (**npm only** — JSR does not support directory exports)
 
 ## Project Structure
 
@@ -29,64 +32,85 @@ Entry points:
   types.ts            — core type definitions (ThemeSchema, TokenSchema, etc.)
   generate.ts         — token generation + CSS output (generateCssTokens, toCssString, generateThemeCss)
   utils.ts            — hex color parsing (hexToRgb, hexToRgbTriplet)
-  colors.ts           — Tailwind color palette (v3 + v4.2 additions: taupe, mauve, mist, olive)
+  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            — re-exports all theme definitions
+    mod.ts            — auto-generated barrel + runtime registry (via scripts/build-themes-mod.ts)
     *.ts              — individual theme files (default export: ThemeSchema)
-/css                  — pre-built CSS files (generated by scripts/build-css.ts)
+/css                  — pre-built CSS files (generated by scripts/build-css.ts; filenames = kebab-case theme names)
 /tests                — test files (deno test --allow-read)
 /scripts
   build-npm.ts        — npm package build (also copies css/ into dist)
-  build-css.ts        — generates css/*.css from all themes with "stuic-" prefix
+  build-css.ts        — generates css/*.css from all themes; honors CSS_PREFIX env var
+  build-themes-mod.ts — auto-generates src/themes/mod.ts + inline registry helpers
 /theme-preview-builder — HTML preview tool
+/mcp.ts               — MCP tool definitions (generate-theme-css, preview-bundled-theme)
 ```
 
 ## Public API Surface
 
 ### Functions (from `./src/mod.ts`)
-| Function | Purpose |
-|----------|---------|
-| `generateCssTokens(schema, prefix, mode?)` | Generate token key-value pairs from a TokenSchema |
-| `toCssString(tokens, selector?)` | Convert tokens to a CSS declaration block |
-| `generateThemeCss(schema, prefix)` | Generate complete CSS for light + optional dark mode |
-| `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 `cssLayer` wrapping                  |
+| `hexToRgb(hex)`                               | Parse hex to `[r, g, b]` tuple                                                                      |
+| `hexToRgbTriplet(hex)`                        | Convert hex to `"r, g, b"` string                                                                   |
 
 ### Functions (from `./reboot`)
-| Function | Purpose |
-|----------|---------|
-| `generateRebootBridge(tokens, prefix)` | Map tokens to `--bs-*` variables |
-| `generateThemedCss(schema, prefix)` | Combined tokens + reboot bridge CSS |
+
+| Function                                      | Purpose                                                                                                                                             |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `generateRebootBridge(tokens, prefix)`        | Map tokens to `--bs-*` variables. `-rgb` companions only emitted for literal hex values — auto-derived `color-mix()` values cannot produce triplets |
+| `generateThemedCss(schema, prefix, options?)` | Combined tokens + reboot bridge CSS                                                                                                                 |
+
+### Functions (from `./themes`)
+
+| Function                | Purpose                                                                     |
+| ----------------------- | --------------------------------------------------------------------------- |
+| `getBundledTheme(name)` | Look up bundled theme by camelCase name; returns `ThemeSchema \| undefined` |
 
 ### Key Types
-| Type | Purpose |
-|------|---------|
-| `ThemeSchema` | `{ light: TokenSchema; dark?: TokenSchema }` |
-| `TokenSchema` | Intent colors, role paired/single colors |
-| `ColorPair` | `{ DEFAULT, foreground, hover?, active? }` |
-| `ColorValue` | `{ DEFAULT, hover?, active? }` |
-| `SingleColor` | `string \| ColorValue` |
-| `GeneratedTokens` | `Record<string, string>` |
+
+| 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? }`                                 |
+| `RolePairedKey`         | Required: `"background" \| "muted" \| "surface"`                                |
+| `RolePairedOptionalKey` | Optional: `"surface-1"` (all bundled themes ship it)                            |
 
 ### Constants
-| Export | Purpose |
-|--------|---------|
-| `colors` | Tailwind hex palette including v4.2 additions (`colors.blue[600]`, `colors.mauve[500]`) |
+
+| Export              | Purpose                                                          |
+| ------------------- | ---------------------------------------------------------------- |
+| `colors`            | Tailwind hex palette (with `as const`, full literal types)       |
+| `themeNames`        | Kebab-case theme names (readonly tuple)                          |
+| `bundledThemes`     | Map of camelCase name → ThemeSchema (no leaky non-theme exports) |
+| `bundledThemeNames` | Array of camelCase theme names                                   |
 
 ## Critical Conventions
 
 1. All public functions must have JSDoc and explicit return types (Deno/JSR requirement)
 2. Token naming: `--{prefix}color-{key}`, `--{prefix}color-{key}-hover`, etc.
-3. Hover/active auto-derived via `color-mix(in oklch, ...)` — light darkens with black, dark lightens with white
-4. Surface-intent tokens derived via `color-mix(in srgb, ...)` from intent + background
-5. Theme files use `export default` with `ThemeSchema` type annotation
-6. Formatting: tabs, 90-char line width, 4-space indent width (`deno fmt`)
+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 oklch, ...)` — light darkens with black, dark lightens with white. 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`.
+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`.
 
 ## Adding a New Theme
 
 1. Create `src/themes/{name}.ts` with `export default` of `ThemeSchema`
-2. Run `deno task themes:build` to regenerate `src/themes/mod.ts`
+2. Run `deno task themes:build` to regenerate `src/themes/mod.ts` (barrel + registry)
 3. Run `deno task css:build` to regenerate CSS files
 4. Run `deno task preview:build` to rebuild the preview tool
 5. If the theme uses new color families, update `COLOR_FAMILIES` in `theme-preview-builder/index.html`
@@ -95,5 +119,12 @@ Entry points:
 
 - [ ] Read existing patterns in similar files
 - [ ] Run `deno task test` — all tests must pass
+- [ ] `deno check src/mod.ts src/themes/mod.ts src/reboot-bridge.ts mcp.ts scripts/*.ts` — typecheck
 - [ ] Follow `deno fmt` conventions
 - [ ] Ensure new exports have JSDoc + explicit return types
+- [ ] If changing generator output (CSS text), note as potential BC change
+
+## 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.

package/API.md

@@ -2,38 +2,53 @@
 
 ## Functions
 
-### `generateCssTokens(schema, prefix, mode?)`
+### `generateCssTokens(schema, prefix, options?)`
 
 Generate CSS token key-value pairs from a single-mode token schema.
 
 **Parameters:**
+
 - `schema` (`TokenSchema`) — Color definitions for intent, role paired, and role single colors
-- `prefix` (`string`) — CSS variable prefix (e.g. `"my-"` produces `--my-color-primary`)
-- `mode` (`"light" | "dark"`, optional) — Affects auto-derivation direction. Light darkens with black, dark lightens with white. Default: `"light"`
+- `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) — Affects auto-derivation direction. Light darkens with black, dark lightens with white. 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`
+  - `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)
 
 **Example:**
+
 ```typescript
 import { generateCssTokens } from "@marianmeres/design-tokens";
 
-const tokens = generateCssTokens(schema.light, "app-", "light");
-// { "app-color-primary": "#2563eb", "app-color-primary-hover": "color-mix(...)", ... }
+// Shorthand mode string
+const tokens = generateCssTokens(schema.light, "app-", "dark");
+
+// Full options object
+const flat = generateCssTokens(schema.light, "app", {
+	mode: "light",
+	deriveStates: false,
+	surfaceForegroundContrast: 70,
+});
+// { "app-color-primary": "#2563eb", "app-color-primary-hover": "#2563eb", ... }
 ```
 
 ---
 
 ### `toCssString(tokens, selector?)`
 
-Convert a tokens record to a formatted CSS declaration block, grouped by base color name.
+Convert a tokens record to a formatted CSS declaration block, grouped by base color name (e.g. all `surface-*` tokens cluster together).
 
 **Parameters:**
+
 - `tokens` (`GeneratedTokens`) — Key-value token pairs (from `generateCssTokens`)
 - `selector` (`string`, optional) — CSS selector for the block. Default: `":root"`
 
 **Returns:** `string` — Formatted CSS string
 
 **Example:**
+
 ```typescript
 import { generateCssTokens, toCssString } from "@marianmeres/design-tokens";
 
@@ -46,22 +61,30 @@ const css = toCssString(tokens, ":root.dark");
 
 ---
 
-### `generateThemeCss(schema, prefix)`
+### `generateThemeCss(schema, prefix, options?)`
 
 Generate complete CSS for a theme with light mode and optional dark mode.
 
 **Parameters:**
+
 - `schema` (`ThemeSchema`) — Theme with required `light` and optional `dark` token schemas
-- `prefix` (`string`) — CSS variable prefix
+- `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.
 
-**Returns:** `string` — Complete CSS with `:root` for light and `:root.dark` for dark mode
+**Returns:** `string` — Complete CSS with `:root` for light and `:root.dark` for dark mode, optionally wrapped in `@layer`.
 
 **Example:**
+
 ```typescript
 import { generateThemeCss } from "@marianmeres/design-tokens";
 import { zinc } from "@marianmeres/design-tokens/themes";
 
-const css = generateThemeCss(zinc, "app-");
+const css = generateThemeCss(zinc, "app-", { cssLayer: "tokens" });
+// @layer tokens {
+//     :root { ... }
+//     :root.dark { ... }
+// }
 ```
 
 ---
@@ -71,17 +94,19 @@ const css = generateThemeCss(zinc, "app-");
 Parse a hex color string to RGB components. Supports 3-digit (`#abc`) and 6-digit (`#aabbcc`) formats, with or without `#` prefix.
 
 **Parameters:**
+
 - `hex` (`string`) — Hex color string
 
 **Returns:** `[number, number, number] | null` — RGB tuple, or `null` if invalid
 
 **Example:**
+
 ```typescript
 import { hexToRgb } from "@marianmeres/design-tokens";
 
 hexToRgb("#2563eb"); // → [37, 99, 235]
-hexToRgb("fff");     // → [255, 255, 255]
-hexToRgb("nope");    // → null
+hexToRgb("fff"); // → [255, 255, 255]
+hexToRgb("nope"); // → null
 ```
 
 ---
@@ -91,11 +116,13 @@ hexToRgb("nope");    // → null
 Convert a hex color to an `"r, g, b"` triplet string suitable for CSS `rgb()` usage.
 
 **Parameters:**
+
 - `hex` (`string`) — Hex color string
 
 **Returns:** `string | null` — Comma-separated RGB triplet, or `null` if invalid
 
 **Example:**
+
 ```typescript
 import { hexToRgbTriplet } from "@marianmeres/design-tokens";
 
@@ -106,31 +133,37 @@ hexToRgbTriplet("#2563eb"); // → "37, 99, 235"
 
 ### `generateRebootBridge(tokens, prefix)`
 
-*Import from `@marianmeres/design-tokens/reboot`*
+_Import from `@marianmeres/design-tokens/reboot`_
 
 Map design tokens to Bootstrap Reboot `--bs-*` CSS variables. Automatically generates `-rgb` triplet companions for hex color values.
 
 **Parameters:**
+
 - `tokens` (`GeneratedTokens`) — Generated token pairs (from `generateCssTokens`)
-- `prefix` (`string`) — The same prefix used in `generateCssTokens`
+- `prefix` (`string`) — The same prefix used in `generateCssTokens` (trailing dash optional)
 
 **Returns:** `GeneratedTokens` — Bootstrap bridge variables (`bs-body-bg`, `bs-link-color`, etc.)
 
+**Note on `-rgb` companions:** Bootstrap's alpha-blended rules (e.g. `rgba(var(--bs-link-color-rgb), 0.5)`) require raw RGB triplets. This bridge emits `--bs-*-rgb` only when the underlying token resolves to a literal hex color. Auto-derived hover/active tokens are `color-mix()` expressions and cannot produce triplets — the companions are omitted, and Reboot rules that rely on them fall back to defaults. Provide explicit hex `hover` / `active` values on your `ColorPair`s if you need full alpha-blend support.
+
 ---
 
-### `generateThemedCss(schema, prefix)`
+### `generateThemedCss(schema, prefix, options?)`
 
-*Import from `@marianmeres/design-tokens/reboot`*
+_Import from `@marianmeres/design-tokens/reboot`_
 
 Generate complete themed CSS including both design tokens AND the Bootstrap Reboot bridge.
 
 **Parameters:**
+
 - `schema` (`ThemeSchema`) — Theme schema with light and optional dark modes
-- `prefix` (`string`) — CSS variable prefix
+- `prefix` (`string`) — CSS variable prefix (trailing dash optional)
+- `options` (`Omit<GenerateThemeOptions, "cssLayer">`, optional) — Forwarded to `generateCssTokens` for each mode (see `generateCssTokens`)
 
 **Returns:** `string` — Combined CSS with token variables and `--bs-*` bridge variables
 
 **Example:**
+
 ```typescript
 import { generateThemedCss } from "@marianmeres/design-tokens/reboot";
 import { zinc } from "@marianmeres/design-tokens/themes";
@@ -141,14 +174,37 @@ const css = generateThemedCss(zinc, "app-");
 
 ---
 
+### `getBundledTheme(name)`
+
+_Import from `@marianmeres/design-tokens/themes`_
+
+Look up a bundled theme by its camelCase name. Returns `undefined` if the name is not a known theme.
+
+**Parameters:**
+
+- `name` (`string`) — Theme name (camelCase, e.g. `"blueOrange"`)
+
+**Returns:** `ThemeSchema | undefined`
+
+**Example:**
+
+```typescript
+import { getBundledTheme } from "@marianmeres/design-tokens/themes";
+
+const theme = getBundledTheme("mauveTeal");
+if (theme) { /* use theme */ }
+```
+
+---
+
 ## Types
 
 ### `ThemeSchema`
 
 ```typescript
 type ThemeSchema = {
-    light: TokenSchema;
-    dark?: TokenSchema;
+	light: TokenSchema;
+	dark?: TokenSchema;
 };
 ```
 
@@ -160,17 +216,17 @@ Complete theme definition with required light mode and optional dark mode.
 
 ```typescript
 type TokenSchema = {
-    colors: {
-        intent: WithRequired<IntentColorKey, ColorPair>;
-        role: {
-            paired: WithRequired<RolePairedKey, ColorPair>;
-            single: WithRequired<RoleSingleKey, SingleColor>;
-        };
-    };
+	colors: {
+		intent: WithRequired<IntentColorKey, ColorPair>;
+		role: {
+			paired: WithKnown<RolePairedKey, RolePairedOptionalKey, ColorPair>;
+			single: WithRequired<RoleSingleKey, SingleColor>;
+		};
+	};
 };
 ```
 
-Single-mode token schema. Intent colors define primary UI actions; role colors define structural UI elements.
+Single-mode token schema. Intent colors define primary UI actions; role colors define structural UI elements. Arbitrary string keys are allowed on every collection (for custom additions).
 
 ---
 
@@ -178,14 +234,16 @@ Single-mode token schema. Intent colors define primary UI actions; role colors d
 
 ```typescript
 type ColorPair = {
-    DEFAULT: string;
-    foreground: string;
-    hover?: string;
-    active?: string;
+	DEFAULT: string;
+	foreground: string;
+	hover?: string;
+	active?: string;
+	foregroundHover?: string;
+	foregroundActive?: string;
 };
 ```
 
-Color with a foreground companion. Hover/active are auto-derived when omitted.
+Color with a foreground companion. Hover/active are auto-derived when omitted. `foregroundHover` and `foregroundActive` default to `foreground` — provide them if your foreground should change on interaction.
 
 ---
 
@@ -193,9 +251,9 @@ Color with a foreground companion. Hover/active are auto-derived when omitted.
 
 ```typescript
 type ColorValue = {
-    DEFAULT: string;
-    hover?: string;
-    active?: string;
+	DEFAULT: string;
+	hover?: string;
+	active?: string;
 };
 ```
 
@@ -213,6 +271,32 @@ Either a plain CSS color string or an object with optional hover/active states.
 
 ---
 
+### `GenerateOptions`
+
+```typescript
+type GenerateOptions = {
+	mode?: "light" | "dark";
+	deriveStates?: boolean;
+	surfaceForegroundContrast?: number;
+};
+```
+
+Options passed to `generateCssTokens`. See the function docs above for field meanings.
+
+---
+
+### `GenerateThemeOptions`
+
+```typescript
+type GenerateThemeOptions = Omit<GenerateOptions, "mode"> & {
+	cssLayer?: string;
+};
+```
+
+Options passed to `generateThemeCss`. Omits `mode` (set automatically per section) and adds `cssLayer` for optional `@layer` wrapping.
+
+---
+
 ### `GeneratedTokens`
 
 ```typescript
@@ -237,6 +321,18 @@ type IntentColorKey = "primary" | "accent" | "destructive" | "warning" | "succes
 type RolePairedKey = "background" | "muted" | "surface";
 ```
 
+Required paired role keys.
+
+---
+
+### `RolePairedOptionalKey`
+
+```typescript
+type RolePairedOptionalKey = "surface-1";
+```
+
+Optional paired role keys. Conventional but not required — all bundled themes define `surface-1` as an additional elevation layer. Additional arbitrary string keys are also allowed.
+
 ---
 
 ### `RoleSingleKey`
@@ -247,6 +343,27 @@ type RoleSingleKey = "foreground" | "border" | "input" | "ring";
 
 ---
 
+### `WithRequired` / `WithOptional` / `WithKnown`
+
+Helper types for schema collections:
+
+```typescript
+type WithRequired<K extends string, V> =
+	& Record<K, V>
+	& Record<string, V>;
+
+type WithOptional<K extends string, V> =
+	& Partial<Record<K, V>>
+	& Record<string, V>;
+
+type WithKnown<Req extends string, Opt extends string, V> =
+	& Record<Req, V>
+	& Partial<Record<Opt, V>>
+	& Record<string, V>;
+```
+
+---
+
 ## Constants
 
 ### `colors`
@@ -262,31 +379,75 @@ Tailwind CSS color palette as hex values. Contains `black`, `white`, and 26 colo
 ```typescript
 import { colors } from "@marianmeres/design-tokens";
 
-colors.blue[600]   // → "#2563eb"
-colors.mauve[500]  // → "#79697b"
-colors.white       // → "#ffffff"
+colors.blue[600]; // → "#2563eb"
+colors.mauve[500]; // → "#79697b"
+colors.white; // → "#ffffff"
+```
+
+---
+
+### `bundledThemes`
+
+_Import from `@marianmeres/design-tokens/themes`_
+
+Map of all bundled themes keyed by their camelCase name. Safe to iterate — the non-theme exports (`themeNames`, `ThemeSchema`) are filtered out.
+
+```typescript
+import { bundledThemes } from "@marianmeres/design-tokens/themes";
+
+Object.keys(bundledThemes); // → ["amberOliveSafari", "blueOrange", ...]
+```
+
+---
+
+### `bundledThemeNames`
+
+_Import from `@marianmeres/design-tokens/themes`_
+
+Array of all bundled theme names (camelCase), discovered at runtime from `bundledThemes`.
+
+---
+
+### `themeNames`
+
+_Import from `@marianmeres/design-tokens/themes`_
+
+Kebab-case theme name strings matching the generated CSS filenames (without extension). Typed as a `readonly` tuple.
+
+```typescript
+import { themeNames } from "@marianmeres/design-tokens/themes";
+
+themeNames; // → ["amber-olive-safari", "blue-orange", ..., "zinc"]
 ```
 
 ---
 
 ## Bundled Themes
 
-*Import from `@marianmeres/design-tokens/themes`*
+_Import from `@marianmeres/design-tokens/themes`_
+
+43 pre-built `ThemeSchema` definitions, each with light + dark mode:
 
-42 pre-built `ThemeSchema` definitions, each with light + dark mode:
+`amberOliveSafari`, `blueOrange`, `cyanRed`, `cyanSlate`, `emeraldAmberForest`, `emeraldPink`, `fuchsiaEmerald`, `gray`, `indigoAmber`, `limeFuchsiaNeon`, `mauve`, `mauveLimeElectric`, `mauveTeal`, `mist`, `mistIndigoFjord`, `mistVioletAurora`, `monokaiCyan`, `monokaiGreen`, `monokaiPink`, `olive`, `oliveAmberSafari`, `orangePinkSunset`, `pinkEmerald`, `pinkTeal`, `purpleYellow`, `rainbow`, `redBlue`, `redCyan`, `redSky`, `redSkySlate`, `roseTeal`, `skyAmber`, `slateCyan`, `slateTealOcean`, `stone`, `stoneOrangeEarth`, `taupe`, `taupeOliveClay`, `taupeRoseBlush`, `tealRose`, `violetLime`, `violetRoseDusk`, `zinc`
 
-`blueOrange`, `cyanRed`, `cyanSlate`, `emeraldAmberForest`, `emeraldPink`, `fuchsiaEmerald`, `gray`, `indigoAmber`, `limeFuchsiaNeon`, `mauve`, `mauveLimeElectric`, `mauveTeal`, `mist`, `mistIndigoFjord`, `mistVioletAurora`, `monokaiCyan`, `monokaiGreen`, `monokaiPink`, `olive`, `oliveAmberSafari`, `orangePinkSunset`, `pinkEmerald`, `pinkTeal`, `purpleYellow`, `rainbow`, `redBlue`, `redCyan`, `redSky`, `redSkySlate`, `roseTeal`, `skyAmber`, `slateCyan`, `slateTealOcean`, `stone`, `taupe`, `taupeOliveClay`, `taupeRoseBlush`, `stoneOrangeEarth`, `tealRose`, `violetLime`, `violetRoseDusk`, `zinc`
+All bundled themes include a `surface-1` paired role (on top of the required `background`, `muted`, `surface`) as a conventional extra elevation.
 
 ---
 
 ## Pre-built CSS
 
-*npm only — not available on JSR*
+_npm only — JSR does not support directory exports, so the pre-built CSS files are not available via JSR._
 
-All bundled themes are also distributed as pre-built CSS files using the `stuic-` prefix. Import via `@marianmeres/design-tokens/css/{theme-name}.css`.
+All bundled themes are also distributed as pre-built CSS files. Import via `@marianmeres/design-tokens/css/{theme-name}.css`.
 
 ```typescript
 import "@marianmeres/design-tokens/css/mauve-teal.css";
 ```
 
-Available files: `blue-orange.css`, `cyan-red.css`, `mauve-teal.css`, `mist-indigo-fjord.css`, `taupe-rose-blush.css`, etc. (one per bundled theme)
+The default prefix on the published files is `stuic-` (i.e. tokens are named `--stuic-color-primary`, etc.). To regenerate the CSS files locally with a different prefix, set the `CSS_PREFIX` environment variable before running the build:
+
+```bash
+CSS_PREFIX=app- deno task css:build
+```
+
+Available files: `amber-olive-safari.css`, `blue-orange.css`, `cyan-red.css`, `mauve-teal.css`, `mist-indigo-fjord.css`, `taupe-rose-blush.css`, etc. (one per bundled theme).

package/README.md

@@ -37,6 +37,8 @@ const theme: ThemeSchema = {
 					background: { DEFAULT: "#ffffff", foreground: "#171717" },
 					muted: { DEFAULT: "#f5f5f5", foreground: "#737373" },
 					surface: { DEFAULT: "#e5e5e5", foreground: "#171717" },
+					// Optional extra elevation (all bundled themes include it):
+					"surface-1": { DEFAULT: "#d4d4d4", foreground: "#171717" },
 				},
 				single: {
 					foreground: "#171717",
@@ -49,6 +51,7 @@ const theme: ThemeSchema = {
 	},
 };
 
+// The prefix's trailing dash is optional — "my" and "my-" are equivalent.
 const css = generateThemeCss(theme, "my-");
 // → :root { --my-color-primary: #2563eb; ... }
 ```
@@ -62,6 +65,7 @@ All bundled themes are available as pre-built CSS files with the `stuic-` prefix
 ```
 
 Or via bundler import:
+
 ```ts
 import "@marianmeres/design-tokens/css/mauve-teal.css";
 ```
@@ -98,6 +102,10 @@ const myTheme: ThemeSchema = {
 						DEFAULT: colors.slate[200],
 						foreground: colors.slate[900],
 					},
+					"surface-1": {
+						DEFAULT: colors.slate[300],
+						foreground: colors.slate[900],
+					},
 				},
 				single: {
 					foreground: colors.slate[900],
@@ -126,6 +134,29 @@ import { generateThemeCss } from "@marianmeres/design-tokens";
 const css = generateThemeCss(zinc, "app-");
 ```
 
+Dynamic lookup via the registry (useful when the theme name comes from config):
+
+```ts
+import { bundledThemeNames, getBundledTheme } from "@marianmeres/design-tokens/themes";
+
+const theme = getBundledTheme("mauveTeal");
+if (theme) {
+	const css = generateThemeCss(theme, "app-");
+}
+```
+
+### Options
+
+`generateThemeCss` and `generateCssTokens` accept an options object:
+
+```ts
+generateThemeCss(zinc, "app-", {
+	deriveStates: false, // disable color-mix hover/active derivation
+	surfaceForegroundContrast: 70, // stronger contrast on surface-{intent}-foreground
+	cssLayer: "tokens", // wrap output in @layer tokens { ... }
+});
+```
+
 ## Reboot bridge
 
 Maps design tokens to Bootstrap Reboot's `--bs-*` CSS variables: