@marianmeres/design-tokens 1.14.0 → 1.16.0

package/AGENTS.md

@@ -59,6 +59,7 @@ Entry points:
 | `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 |
+| `mergeThemeSchema(base, overrides)`           | Merge sparse `ThemeSchemaOverrides` over a complete base theme; replaces whole entries, never mints keys the base lacks    |
 | `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                                      |
@@ -87,7 +88,9 @@ Entry points:
 | Type                    | Purpose                                                                                   |
 | ----------------------- | ----------------------------------------------------------------------------------------- |
 | `ThemeSchema`           | `{ light: TokenSchema; dark?: TokenSchema }`                                              |
-| `TokenSchema`           | Intent colors, role paired/single colors                                                  |
+| `TokenSchema`           | Intent colors, role paired/single colors — **complete** by contract (see convention 13)   |
+| `ThemeSchemaOverrides`  | `{ light?, dark? }` sparse overrides for `mergeThemeSchema`; never passed to generators   |
+| `TokenSchemaOverrides`  | Single-mode sparse overrides; no index signatures, so typo'd keys are compile errors      |
 | `ColorPair`             | `{ DEFAULT, foreground, hover?, active?, foregroundHover?, foregroundActive? }`           |
 | `ColorValue`            | `{ DEFAULT, hover?, active? }`                                                            |
 | `SingleColor`           | `string \| ColorValue`                                                                    |
@@ -124,6 +127,7 @@ Entry points:
 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).
+13. **Complete schema in, self-standing stylesheet out.** The generator rejects — with an error naming the schema path — any schema whose output would reference a token it does not declare: the five containers, non-string `DEFAULT`/`foreground` leaves, and the two derived operands (`colors.role.paired.background` when intent colors are present; `colors.role.single.foreground` when role hover/active derivation fires). Key-completeness beyond that stays the type's job — a self-consistent minimal schema still generates. Sparse "override" schemas are rejected by design: layering a sparse generated stylesheet over a base un-repairs the base's `@supports` legacy fallback (the override's `color-mix()` re-declaration wins the cascade, and the override's own fallback block cannot resolve operands it does not carry — see #9 for why there is no consumer-side remedy). The supported override path is `mergeThemeSchema(base, overrides)` → generate one stylesheet.
 
 ## Adding a New Theme
 
@@ -143,6 +147,7 @@ Entry points:
 - [ ] 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
+- [ ] Never emit a `var()` reference to a token the same stylesheet does not declare — the generator enforces this for the two derived operands (convention 13); tests audit the full declared-vs-referenced set
 
 ## Known Limitations
 

package/API.md

@@ -4,7 +4,9 @@
 
 ### `generateCssTokens(schema, prefix, options?)`
 
-Generate CSS token key-value pairs from a single-mode token schema.
+Generate CSS token key-value pairs from a complete single-mode token schema.
+
+The schema must be complete — the generator throws an error naming the offending schema path when a container or required value is missing, or when the output would reference a token it never declares (`colors.role.paired.background` when intent colors are present; `colors.role.single.foreground` when role hover/active states are derived). To override parts of an existing theme, use [`mergeThemeSchema`](#mergethemeschemabase-overrides) instead of passing a partial schema.
 
 **Parameters:**
 
@@ -13,7 +15,7 @@ Generate CSS token key-value pairs from a single-mode token schema.
 - `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()` — 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"`
+  - `fallback` (`TokenFallback`, optional) — `"static"` evaluates statically resolvable `color-mix()` expressions at build time and emits literal colors; expressions whose operands cannot be resolved at build time (e.g. author-supplied `var()` refs to variables declared elsewhere) pass through unchanged. `"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)
@@ -92,6 +94,37 @@ const css = generateThemeCss(zinc, "app-", { cssLayer: "tokens" });
 
 ---
 
+### `mergeThemeSchema(base, overrides)`
+
+Merge sparse overrides over a complete base theme, returning a new complete `ThemeSchema` — the supported way to express "bundled theme X, but primary is indigo". The base is never mutated; an absent or empty override mode yields the base mode unchanged.
+
+The merge recurses through the containers (`light`/`dark` → `colors` → `intent`/`role` → `paired`/`single`) and **replaces whole entries** — an overridden `ColorPair` or `SingleColor` supersedes the base entry entirely, never merges into it, so a changed `DEFAULT` cannot silently inherit a stale explicit `hover` or a `foreground` that no longer contrasts. To keep parts of a base entry, spread it yourself: `{ ...base.light.colors.intent.primary, DEFAULT: "#4f46e5" }`.
+
+**Parameters:**
+
+- `base` (`ThemeSchema`) — A complete theme, e.g. a bundled theme from `./themes`
+- `overrides` (`ThemeSchemaOverrides`) — Sparse overrides. Keys must already exist in the base (typo protection — a key the base does not have throws instead of minting junk tokens); non-empty `dark` overrides require the base to have a dark mode (an empty `dark: {}` is a no-op against any base). To change the key set, author it on the base schema object.
+
+**Returns:** `ThemeSchema` — A new complete theme, ready for `generateThemeCss`
+
+**Example:**
+
+```typescript
+import { generateThemeCss, mergeThemeSchema } from "@marianmeres/design-tokens";
+import { amberOliveSafari } from "@marianmeres/design-tokens/themes";
+
+const theme = mergeThemeSchema(amberOliveSafari, {
+	light: {
+		colors: {
+			intent: { primary: { DEFAULT: "#4f46e5", foreground: "#ffffff" } },
+		},
+	},
+});
+const css = generateThemeCss(theme, "app-");
+```
+
+---
+
 ### `hexToRgb(hex)`
 
 Parse a hex color string to RGB components. Supports 3-digit (`#abc`) and 6-digit (`#aabbcc`) formats, with or without `#` prefix.
@@ -358,7 +391,40 @@ type TokenSchema = {
 };
 ```
 
-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).
+Complete 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).
+
+Completeness is load-bearing, not ceremonial: the generator derives tokens whose values reference `--{prefix}color-background` (every `surface-{intent}` token) and `--{prefix}color-foreground` (role hover/active derivation), and only `role.paired.background` / `role.single.foreground` declare those. A sparse schema would generate a stylesheet that references tokens it never declares, so the generator rejects it. To override parts of an existing theme, use [`mergeThemeSchema`](#mergethemeschemabase-overrides) with a `ThemeSchemaOverrides`.
+
+---
+
+### `ThemeSchemaOverrides`
+
+```typescript
+type ThemeSchemaOverrides = {
+	light?: TokenSchemaOverrides;
+	dark?: TokenSchemaOverrides;
+};
+```
+
+Sparse theme overrides for `mergeThemeSchema` — **not** accepted by `generateThemeCss`; merge it over a complete `ThemeSchema` first. An absent or empty mode leaves the base mode unchanged.
+
+---
+
+### `TokenSchemaOverrides`
+
+```typescript
+type TokenSchemaOverrides = {
+	colors?: {
+		intent?: Partial<Record<IntentColorKey, ColorPair>>;
+		role?: {
+			paired?: Partial<Record<RolePairedKey | RolePairedOptionalKey, ColorPair>>;
+			single?: Partial<Record<RoleSingleKey, SingleColor>>;
+		};
+	};
+};
+```
+
+Sparse single-mode overrides for `mergeThemeSchema` — **not** accepted by `generateCssTokens`. Deliberately carries no index signatures (unlike `TokenSchema`), so a typo'd key in an override literal is a compile error instead of a silently minted junk token. To introduce a genuinely new key, author it on the base schema object (e.g. `{ ...base.light.colors.intent, info: … }`).
 
 ---
 
@@ -438,7 +504,7 @@ Options passed to `generateThemeCss`. Omits `mode` (set automatically per sectio
 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.
+Legacy-engine strategy for a token _record_. `"none"` emits `color-mix()` expressions as-is; `"static"` evaluates statically resolvable ones at build time so the record contains literal colors — expressions whose operands cannot be resolved at build time pass through unchanged.
 
 ---
 

package/README.md

@@ -150,6 +150,49 @@ exactly equivalent to `color-mix(in srgb, <color> 25%, transparent)` — mixing
 `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.
 
+## Overriding a bundled theme
+
+To tweak an existing theme rather than author a full schema — "amber-olive-safari,
+but primary is indigo" — merge sparse overrides over the bundled base with
+`mergeThemeSchema` and generate from the merged result:
+
+```ts
+import { generateThemeCss, mergeThemeSchema } from "@marianmeres/design-tokens";
+import { amberOliveSafari } from "@marianmeres/design-tokens/themes";
+
+const theme = mergeThemeSchema(amberOliveSafari, {
+	light: {
+		colors: {
+			intent: { primary: { DEFAULT: "#4f46e5", foreground: "#ffffff" } },
+		},
+	},
+});
+
+const css = generateThemeCss(theme, "app-");
+```
+
+An override replaces the whole entry — the base's explicit `hover`/`active`/`foreground`
+for that entry are gone, not inherited (they would no longer match your new `DEFAULT`;
+omitted states are auto-derived from it instead). To keep parts of the base entry,
+spread it yourself: `{ ...amberOliveSafari.light.colors.intent.primary, DEFAULT: "#4f46e5" }`.
+An absent or empty mode (`dark: {}`) leaves the base mode untouched, and a key the
+base does not have is an error — both in the `ThemeSchemaOverrides` type and at runtime.
+
+Prefer literal color values (hex, or `colors.indigo[600]` from the bundled palette) over
+`var()` references in overrides: a value like `var(--color-indigo-600)` cannot be
+resolved at build time, so those tokens lose their precomputed legacy-browser fallback.
+
+Do **not** try to override by layering a second generated stylesheet over a base theme's
+CSS — the generator rejects sparse schemas whose output would reference tokens they never
+declare (the common override shapes), and even a sparse schema that does generate breaks
+subtly when layered, on engines without `color-mix()` support, while looking fine on
+modern ones. Merge the schemas, generate one stylesheet.
+
+Since the merged output is derived from the installed base, run the generate step as
+part of your build (e.g. a `prebuild` hook) rather than committing its output — that
+way upstream theme improvements flow in with every dependency update. If you prefer
+committing it, add a CI check that regenerating leaves the file unchanged.
+
 ## Bundled themes
 
 ```ts
@@ -192,11 +235,11 @@ and author-supplied `color-mix()` values pass through). Use `fallback` for that.
 `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                                          |
+| `fallback`            | Output                                                                                                      |
+| --------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `"supports"`(default) | Normal output, plus a trailing `@supports not (...)` block with precomputed literals                        |
+| `"static"`            | Statically resolvable `color-mix()` evaluated at build time to literals; unresolvable operands pass through |
+| `"none"`              | `color-mix()` only; breaks on older engines                                                                 |
 
 ```css
 /* fallback: "supports" */

package/dist/css/amber-olive-safari.css

@@ -96,7 +96,7 @@
 
 /* prettier-ignore */
 :root.dark {
-	--stuic-color-primary:                        #f59e0b;
+	--stuic-color-primary:                        #d97706;
 	--stuic-color-primary-hover:                  color-mix(in oklab, var(--stuic-color-primary), white 10%);
 	--stuic-color-primary-active:                 color-mix(in oklab, var(--stuic-color-primary), white 20%);
 	--stuic-color-primary-foreground:             #000000;
@@ -238,8 +238,8 @@
 	}
 
 	:root.dark {
-		--stuic-color-primary-hover:                  #f7a83f;
-		--stuic-color-primary-active:                 #f9b35b;
+		--stuic-color-primary-hover:                  #de8537;
+		--stuic-color-primary-active:                 #e39352;
 
 		--stuic-color-accent-hover:                   #b3b3a6;
 		--stuic-color-accent-active:                  #bbbbaf;
@@ -253,9 +253,9 @@
 		--stuic-color-success-hover:                  #43c08d;
 		--stuic-color-success-active:                 #5fc899;
 
-		--stuic-color-surface-primary:                #3d3014;
-		--stuic-color-surface-primary-foreground:     #facf85;
-		--stuic-color-surface-primary-border:         #5e4413;
+		--stuic-color-surface-primary:                #392b14;
+		--stuic-color-surface-primary-foreground:     #ecbb83;
+		--stuic-color-surface-primary-border:         #553811;
 		--stuic-color-surface-accent:                 #32322a;
 		--stuic-color-surface-accent-foreground:      #d5d5ce;
 		--stuic-color-surface-accent-border:          #48483e;

package/dist/generate.d.ts

@@ -5,7 +5,10 @@ import type { GeneratedTokens, ThemeSchema, TokenSchema } from "./types.js";
  *
  * - `"none"` — emit `color-mix()` expressions as-is.
  * - `"static"` — evaluate every `color-mix()` at build time and emit literal
- *   colors instead. The output contains no `color-mix()` at all.
+ *   colors instead. The output contains no `color-mix()` for statically
+ *   resolvable values; expressions whose operands cannot be resolved at build
+ *   time (e.g. author-supplied `var()` refs to variables declared elsewhere)
+ *   pass through unchanged.
  */
 export type TokenFallback = "none" | "static";
 /**

package/dist/generate.js

@@ -70,6 +70,95 @@ function normalizePrefix(prefix) {
         return "";
     return prefix.endsWith("-") ? prefix : prefix + "-";
 }
+/**
+ * Thrown when a schema would generate broken output. Internal — the message
+ * (which always names the offending schema path) is the public contract.
+ */
+class TokenSchemaError extends Error {
+    name = "TokenSchemaError";
+}
+const MERGE_HINT = "To override parts of an existing theme, merge your overrides over a " +
+    "complete base first: mergeThemeSchema(base, overrides).";
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Guard the five container objects the generator dereferences, with an error
+ * naming the missing path instead of `Cannot read properties of undefined`.
+ */
+function assertSchemaContainers(schema) {
+    const bad = (path, got) => {
+        throw new TokenSchemaError(`Invalid TokenSchema: "${path}" is ${got === undefined ? "missing" : "not an object"} — a complete schema has the shape ` +
+            `{ colors: { intent, role: { paired, single } } }. ${MERGE_HINT}`);
+    };
+    if (!isPlainObject(schema))
+        bad("(schema)", schema);
+    if (!isPlainObject(schema.colors))
+        bad("colors", schema.colors);
+    if (!isPlainObject(schema.colors.intent))
+        bad("colors.intent", schema.colors.intent);
+    if (!isPlainObject(schema.colors.role))
+        bad("colors.role", schema.colors.role);
+    if (!isPlainObject(schema.colors.role.paired)) {
+        bad("colors.role.paired", schema.colors.role.paired);
+    }
+    if (!isPlainObject(schema.colors.role.single)) {
+        bad("colors.role.single", schema.colors.role.single);
+    }
+}
+/**
+ * A `ColorPair` entry must carry string `DEFAULT` and `foreground` — anything
+ * else would be written into the token record verbatim (`--x: undefined;`,
+ * `--x: 5;`) and only fail at CSS substitution time, far from the mistake.
+ */
+function assertColorPair(value, path) {
+    if (!isPlainObject(value)) {
+        throw new TokenSchemaError(`Invalid TokenSchema: "${path}" must be an object with string ` +
+            `"DEFAULT" and "foreground" (got ${describe(value)}). ${MERGE_HINT}`);
+    }
+    for (const key of ["DEFAULT", "foreground"]) {
+        if (typeof value[key] !== "string") {
+            throw new TokenSchemaError(`Invalid TokenSchema: "${path}" must declare a string "${key}" ` +
+                `(got ${describe(value[key])}). ${MERGE_HINT}`);
+        }
+    }
+    assertOptionalStates(value, ["hover", "active", "foregroundHover", "foregroundActive"], path);
+}
+/**
+ * Optional state fields must be strings when carried — a non-string value
+ * would flow verbatim into the token record (`--x: 5;`, `--x: [object
+ * Object];`) or crash the static resolver three frames from the mistake.
+ * `null` is exempt: every consumer of these fields degrades it via `??`.
+ */
+function assertOptionalStates(value, keys, path) {
+    for (const key of keys) {
+        const v = value[key];
+        if (v !== undefined && v !== null && typeof v !== "string") {
+            throw new TokenSchemaError(`Invalid TokenSchema: "${path}.${key}" must be a string when ` +
+                `present (got ${describe(v)}). ${MERGE_HINT}`);
+        }
+    }
+}
+/** A `SingleColor` entry must be a string or an object with a string `DEFAULT`. */
+function assertSingleColor(value, path) {
+    if (typeof value === "string")
+        return;
+    if (!isPlainObject(value) || typeof value.DEFAULT !== "string") {
+        throw new TokenSchemaError(`Invalid TokenSchema: "${path}" must be a string or an object with ` +
+            `a string "DEFAULT" (got ${describe(value)}). ${MERGE_HINT}`);
+    }
+    assertOptionalStates(value, ["hover", "active"], path);
+}
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    if (typeof value === "object") {
+        return `an object with keys [${Object.keys(value).join(", ")}]`;
+    }
+    return typeof value === "string" ? JSON.stringify(value) : String(value);
+}
 /** Check if a single color is an object with states or a plain string */
 function isSingleColorObject(value) {
     return (value !== null &&
@@ -151,13 +240,18 @@ export function generateCssTokens(schema, prefix, options = {}) {
     const deriveStates = opts.deriveStates ?? true;
     const surfaceContrast = opts.surfaceForegroundContrast ?? 50;
     const fallback = opts.fallback ?? "none";
+    assertSchemaContainers(schema);
     const p = normalizePrefix(prefix);
     const tokens = {};
+    // Set when a role hover/active derivation actually fires — those derived
+    // values reference `--{p}color-foreground`, which the output must declare.
+    let referencesForeground = false;
     // Intent colors (auto-derive hover/active via color-mix when enabled).
     // Saturated brand colors mix toward black/white (mode-aware) — neutral
     // darken/lighten keeps the hue clean.
     const intentStrategy = { kind: "contrast", mode };
     for (const [key, pair] of Object.entries(schema.colors.intent)) {
+        assertColorPair(pair, `colors.intent.${key}`);
         const filled = deriveStates ? fillPairStates(pair, p, key, intentStrategy) : pair;
         generatePairedColorTokens(tokens, key, filled, p);
     }
@@ -179,20 +273,45 @@ export function generateCssTokens(schema, prefix, options = {}) {
     };
     // Role colors (paired) — auto-derive except "background"
     for (const [key, pair] of Object.entries(schema.colors.role.paired)) {
-        const filled = key === "background" || !deriveStates
-            ? pair
-            : fillPairStates(pair, p, key, roleStrategy);
+        assertColorPair(pair, `colors.role.paired.${key}`);
+        const derive = key !== "background" && deriveStates;
+        if (derive && (pair.hover === undefined || pair.active === undefined)) {
+            referencesForeground = true;
+        }
+        const filled = derive ? fillPairStates(pair, p, key, roleStrategy) : pair;
         generatePairedColorTokens(tokens, key, filled, p);
     }
     // Role colors (single)
     for (const [key, color] of Object.entries(schema.colors.role.single)) {
+        assertSingleColor(color, `colors.role.single.${key}`);
         if (isSingleColorObject(color) && deriveStates) {
+            if (color.hover === undefined || color.active === undefined) {
+                referencesForeground = true;
+            }
             generateSingleColorTokens(tokens, key, fillColorValueStates(color, p, key, roleStrategy), p);
         }
         else {
             generateSingleColorTokens(tokens, key, color, p);
         }
     }
+    // The two derived operands: reject a schema whose output would reference a
+    // token it never declares. Everything else — including a schema with fewer
+    // keys than TokenSchema requires — generates a stylesheet that stands
+    // alone, so it is not the generator's business to refuse it.
+    if (Object.keys(schema.colors.intent).length > 0 &&
+        tokens[`${p}color-background`] === undefined) {
+        throw new TokenSchemaError(`Invalid TokenSchema: "colors.role.paired.background" is required ` +
+            `when intent colors are present — every surface-{intent} token ` +
+            `references var(--${p}color-background), which this schema's ` +
+            `output would never declare. ${MERGE_HINT}`);
+    }
+    if (referencesForeground && tokens[`${p}color-foreground`] === undefined) {
+        throw new TokenSchemaError(`Invalid TokenSchema: "colors.role.single.foreground" is required ` +
+            `when role hover/active states are derived — derived values ` +
+            `reference var(--${p}color-foreground), which this schema's ` +
+            `output would never declare. Declare it, or pass ` +
+            `deriveStates: false. ${MERGE_HINT}`);
+    }
     return fallback === "static" ? resolveStaticTokens(tokens) : tokens;
 }
 /**
@@ -277,25 +396,32 @@ export function staticFallbackCss(entries) {
 export function generateThemeCss(schema, prefix, options = {}) {
     const { cssLayer, prettierIgnore, fallback = "supports", ...genOptions } = options;
     const PRETTIER_IGNORE_PREFIX = "/* prettier-ignore */\n";
-    const modes = [
-        {
-            selector: ":root",
-            tokens: generateCssTokens(schema.light, prefix, {
+    if (!isPlainObject(schema) || schema.light === undefined) {
+        throw new TokenSchemaError(`Invalid ThemeSchema: expected { light: TokenSchema, dark?: TokenSchema }` +
+            ` (got ${describe(schema)}). ${MERGE_HINT}`);
+    }
+    // Re-throw schema validation errors with the mode they came from — the
+    // same path exists in both modes, so an unqualified path is ambiguous.
+    const modeTokens = (mode, tokenSchema) => {
+        try {
+            return generateCssTokens(tokenSchema, prefix, {
                 ...genOptions,
-                mode: "light",
+                mode,
                 fallback: fallback === "static" ? "static" : "none",
-            }),
-        },
+            });
+        }
+        catch (e) {
+            if (e instanceof TokenSchemaError) {
+                throw new TokenSchemaError(`[${mode}] ${e.message}`);
+            }
+            throw e;
+        }
+    };
+    const modes = [
+        { selector: ":root", tokens: modeTokens("light", schema.light) },
     ];
     if (schema.dark) {
-        modes.push({
-            selector: ":root.dark",
-            tokens: generateCssTokens(schema.dark, prefix, {
-                ...genOptions,
-                mode: "dark",
-                fallback: fallback === "static" ? "static" : "none",
-            }),
-        });
+        modes.push({ selector: ":root.dark", tokens: modeTokens("dark", schema.dark) });
     }
     const blocks = modes.map(({ selector, tokens }) => toCssString(tokens, selector));
     if (fallback === "supports") {

package/dist/merge.d.ts

@@ -0,0 +1,38 @@
+import type { ThemeSchema, ThemeSchemaOverrides } from "./types.js";
+/**
+ * Merge sparse overrides over a complete base theme, returning a new complete
+ * {@link ThemeSchema} — the supported way to express "bundled theme X, but
+ * primary is indigo". The base is never mutated; an absent or empty override
+ * mode yields the base mode unchanged.
+ *
+ * The merge recurses through the containers (`light`/`dark` → `colors` →
+ * `intent`/`role` → `paired`/`single`) and **replaces whole leaves** — a
+ * `ColorPair` or `SingleColor` override supersedes the base entry entirely,
+ * never merges into it. Deliberate: merging inside a leaf would let a changed
+ * `DEFAULT` silently inherit a stale explicit `hover`/`active` or a
+ * `foreground` that no longer contrasts. To keep parts of a base leaf, spread
+ * it yourself: `{ ...base.light.colors.intent.primary, DEFAULT: "#4f46e5" }`.
+ *
+ * Override keys must already exist in the base (typo protection); non-empty
+ * dark overrides require the base to have a dark mode. To change the key set,
+ * author it on the base schema object.
+ *
+ * @param base - A complete theme (e.g. a bundled theme from `./themes`)
+ * @param overrides - Sparse overrides; see {@link ThemeSchemaOverrides}
+ *
+ * @example
+ * ```ts
+ * import { amberOliveSafari } from "@marianmeres/design-tokens/themes";
+ * import { generateThemeCss, mergeThemeSchema } from "@marianmeres/design-tokens";
+ *
+ * const theme = mergeThemeSchema(amberOliveSafari, {
+ * 	light: {
+ * 		colors: {
+ * 			intent: { primary: { DEFAULT: "#4f46e5", foreground: "#ffffff" } },
+ * 		},
+ * 	},
+ * });
+ * const css = generateThemeCss(theme, "app-");
+ * ```
+ */
+export declare function mergeThemeSchema(base: ThemeSchema, overrides: ThemeSchemaOverrides): ThemeSchema;

package/dist/merge.js

@@ -0,0 +1,135 @@
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Reject override keys outside `allowed` — the runtime analogue of the
+ * excess-property check the {@link ThemeSchemaOverrides} type performs on
+ * literals, for overrides that arrive as JSON (MCP, config files). */
+function assertKnownKeys(obj, allowed, path) {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.includes(key)) {
+            throw new Error(`Invalid ThemeSchemaOverrides: unknown key "${path}.${key}" ` +
+                `(expected ${allowed.map((a) => `"${a}"`).join(", ")}).`);
+        }
+    }
+}
+/**
+ * Replace whole leaves in `target` with clones from `source`. A key the base
+ * does not already have is an error, not an addition — the most likely cause
+ * is a typo, and merging a typo'd key would silently mint junk tokens while
+ * the intended token keeps its base value.
+ */
+function replaceLeaves(target, source, path) {
+    if (!isPlainObject(source)) {
+        throw new Error(`Invalid ThemeSchemaOverrides: "${path}" must be an object.`);
+    }
+    for (const [key, leaf] of Object.entries(source)) {
+        // Object.hasOwn, not `in`: the prototype chain would let keys like
+        // "constructor" / "toString" / "__proto__" slip past the guard (and on
+        // Node, assigning "__proto__" would fire the real setter).
+        if (!Object.hasOwn(target, key)) {
+            throw new Error(`Invalid ThemeSchemaOverrides: "${path}.${key}" does not exist ` +
+                `in the base theme (base has: ${Object.keys(target).join(", ")}). Overrides replace existing keys only — to introduce a ` +
+                `new key, author it on the base schema object.`);
+        }
+        if (leaf === undefined)
+            continue;
+        target[key] = structuredClone(leaf);
+    }
+}
+/** Merge one mode: clone the base, then replace overridden leaves. */
+function mergeMode(baseMode, overrides, path) {
+    const merged = structuredClone(baseMode);
+    if (overrides == null)
+        return merged;
+    if (!isPlainObject(overrides)) {
+        throw new Error(`Invalid ThemeSchemaOverrides: "${path}" must be an object.`);
+    }
+    assertKnownKeys(overrides, ["colors"], path);
+    const colors = overrides.colors;
+    if (colors == null)
+        return merged;
+    if (!isPlainObject(colors)) {
+        throw new Error(`Invalid ThemeSchemaOverrides: "${path}.colors" must be an object.`);
+    }
+    assertKnownKeys(colors, ["intent", "role"], `${path}.colors`);
+    if (colors.intent != null) {
+        replaceLeaves(merged.colors.intent, colors.intent, `${path}.colors.intent`);
+    }
+    const role = colors.role;
+    if (role != null) {
+        if (!isPlainObject(role)) {
+            throw new Error(`Invalid ThemeSchemaOverrides: "${path}.colors.role" must be an object.`);
+        }
+        assertKnownKeys(role, ["paired", "single"], `${path}.colors.role`);
+        if (role.paired != null) {
+            replaceLeaves(merged.colors.role.paired, role.paired, `${path}.colors.role.paired`);
+        }
+        if (role.single != null) {
+            replaceLeaves(merged.colors.role.single, role.single, `${path}.colors.role.single`);
+        }
+    }
+    return merged;
+}
+/**
+ * Merge sparse overrides over a complete base theme, returning a new complete
+ * {@link ThemeSchema} — the supported way to express "bundled theme X, but
+ * primary is indigo". The base is never mutated; an absent or empty override
+ * mode yields the base mode unchanged.
+ *
+ * The merge recurses through the containers (`light`/`dark` → `colors` →
+ * `intent`/`role` → `paired`/`single`) and **replaces whole leaves** — a
+ * `ColorPair` or `SingleColor` override supersedes the base entry entirely,
+ * never merges into it. Deliberate: merging inside a leaf would let a changed
+ * `DEFAULT` silently inherit a stale explicit `hover`/`active` or a
+ * `foreground` that no longer contrasts. To keep parts of a base leaf, spread
+ * it yourself: `{ ...base.light.colors.intent.primary, DEFAULT: "#4f46e5" }`.
+ *
+ * Override keys must already exist in the base (typo protection); non-empty
+ * dark overrides require the base to have a dark mode. To change the key set,
+ * author it on the base schema object.
+ *
+ * @param base - A complete theme (e.g. a bundled theme from `./themes`)
+ * @param overrides - Sparse overrides; see {@link ThemeSchemaOverrides}
+ *
+ * @example
+ * ```ts
+ * import { amberOliveSafari } from "@marianmeres/design-tokens/themes";
+ * import { generateThemeCss, mergeThemeSchema } from "@marianmeres/design-tokens";
+ *
+ * const theme = mergeThemeSchema(amberOliveSafari, {
+ * 	light: {
+ * 		colors: {
+ * 			intent: { primary: { DEFAULT: "#4f46e5", foreground: "#ffffff" } },
+ * 		},
+ * 	},
+ * });
+ * const css = generateThemeCss(theme, "app-");
+ * ```
+ */
+export function mergeThemeSchema(base, overrides) {
+    if (!isPlainObject(base) || !isPlainObject(base.light)) {
+        throw new Error(`mergeThemeSchema: "base" must be a complete ThemeSchema with a ` +
+            `"light" mode (e.g. a bundled theme).`);
+    }
+    const o = overrides ?? {};
+    if (!isPlainObject(o)) {
+        throw new Error(`Invalid ThemeSchemaOverrides: expected an object.`);
+    }
+    assertKnownKeys(o, ["light", "dark"], "overrides");
+    if (o.dark != null) {
+        if (!isPlainObject(o.dark)) {
+            throw new Error(`Invalid ThemeSchemaOverrides: "dark" must be an object.`);
+        }
+        // An *empty* dark override is "no changes to dark" — harmless against
+        // any base. Only actual dark overrides require the base to have one.
+        if (Object.keys(o.dark).length > 0 && base.dark == null) {
+            throw new Error(`Invalid ThemeSchemaOverrides: "dark" overrides were given but ` +
+                `the base theme has no dark mode — author the dark mode on ` +
+                `the base schema object instead.`);
+        }
+    }
+    return {
+        light: mergeMode(base.light, o.light, "light"),
+        ...(base.dark ? { dark: mergeMode(base.dark, o.dark, "dark") } : {}),
+    };
+}

package/dist/mod.d.ts

@@ -9,6 +9,8 @@
 export { generateCssTokens } from "./generate.js";
 /** Generate complete CSS for a theme (light + optional dark mode). */
 export { generateThemeCss } from "./generate.js";
+/** Merge sparse overrides over a complete base theme ("bundled theme X, but primary is indigo"). */
+export { mergeThemeSchema } from "./merge.js";
 /** Convert a tokens record to a CSS declaration block string. */
 export { toCssString } from "./generate.js";
 /** Evaluate every `color-mix()` in a token record to a literal color. */
@@ -25,9 +27,9 @@ export type { GenerateThemeOptions } from "./generate.js";
 export type { TokenFallback } from "./generate.js";
 /** Legacy-engine fallback strategy for a stylesheet: adds `"supports"`. */
 export type { ThemeFallback } from "./generate.js";
-/** Base color value with optional hover/active pseudo states. */
+/** Color pair: `DEFAULT` plus required `foreground`, with optional hover/active pseudo states. */
 export type { ColorPair } from "./types.js";
-/** Color value: a hex string or an object with DEFAULT and optional pseudo states. */
+/** Base color value: an object with `DEFAULT` and optional hover/active pseudo states. */
 export type { ColorValue } from "./types.js";
 /** Generated CSS token key-value pairs (without the `--` prefix on keys). */
 export type { GeneratedTokens } from "./types.js";
@@ -43,8 +45,12 @@ export type { RoleSingleKey } from "./types.js";
 export type { SingleColor } from "./types.js";
 /** A complete theme definition with required light mode and optional dark mode. */
 export type { ThemeSchema } from "./types.js";
-/** Complete token schema for a single mode (light or dark). */
+/** Complete token schema for a single mode (light or dark) — completeness is load-bearing; for sparse overrides use {@link mergeThemeSchema}. */
 export type { TokenSchema } from "./types.js";
+/** Sparse single-mode overrides for {@link mergeThemeSchema} — not accepted by {@link generateCssTokens}. */
+export type { TokenSchemaOverrides } from "./types.js";
+/** Sparse theme overrides for {@link mergeThemeSchema} — not accepted by {@link generateThemeCss}. */
+export type { ThemeSchemaOverrides } from "./types.js";
 /** Helper: partial known keys, allow additional. */
 export type { WithOptional } from "./types.js";
 /** Helper: require known keys, allow additional. */

package/dist/mod.js

@@ -9,6 +9,8 @@
 export { generateCssTokens } from "./generate.js";
 /** Generate complete CSS for a theme (light + optional dark mode). */
 export { generateThemeCss } from "./generate.js";
+/** Merge sparse overrides over a complete base theme ("bundled theme X, but primary is indigo"). */
+export { mergeThemeSchema } from "./merge.js";
 /** Convert a tokens record to a CSS declaration block string. */
 export { toCssString } from "./generate.js";
 /** Evaluate every `color-mix()` in a token record to a literal color. */

package/dist/themes/amber-olive-safari.js

@@ -61,7 +61,7 @@ const dark = {
     colors: {
         intent: {
             primary: {
-                DEFAULT: colors.amber[500],
+                DEFAULT: colors.amber[600],
                 foreground: colors.black,
             },
             accent: {

package/dist/types.d.ts

@@ -39,7 +39,14 @@ export type WithOptional<TKnown extends string, TValue> = Partial<Record<TKnown,
  */
 export type WithKnown<TRequired extends string, TOptional extends string, TValue> = Record<TRequired, TValue> & Partial<Record<TOptional, TValue>> & Record<string, TValue>;
 /**
- * Complete token schema for a single mode (light or dark).
+ * Complete token schema for a single mode (light or dark). Completeness is
+ * load-bearing, not ceremonial: the generator derives tokens whose values
+ * reference `--{prefix}color-background` (every `surface-{intent}` token) and
+ * `--{prefix}color-foreground` (role hover/active derivation), and only
+ * `role.paired.background` / `role.single.foreground` declare those. A sparse
+ * schema would generate a stylesheet that references tokens it never declares.
+ * To override parts of an existing theme, use `mergeThemeSchema` with a
+ * {@link ThemeSchemaOverrides} instead of passing a partial schema here.
  *
  * Defines intent colors (primary, accent, destructive, warning, success),
  * role paired colors (background, muted, surface required; surface-1 optional
@@ -55,6 +62,34 @@ export type TokenSchema = {
         };
     };
 };
+/**
+ * Sparse single-mode overrides for `mergeThemeSchema` — NOT accepted by
+ * `generateCssTokens`; merge it over a complete {@link TokenSchema} first.
+ *
+ * Deliberately carries no index signatures (unlike {@link TokenSchema}), so a
+ * typo'd key in an override literal is a compile error instead of a silently
+ * minted junk token. To introduce a genuinely new key, author it on the base
+ * schema object (e.g. `{ ...base.light.colors.intent, info: … }`) rather than
+ * through an override.
+ */
+export type TokenSchemaOverrides = {
+    colors?: {
+        intent?: Partial<Record<IntentColorKey, ColorPair>>;
+        role?: {
+            paired?: Partial<Record<RolePairedKey | RolePairedOptionalKey, ColorPair>>;
+            single?: Partial<Record<RoleSingleKey, SingleColor>>;
+        };
+    };
+};
+/**
+ * Sparse theme overrides for `mergeThemeSchema` — NOT accepted by
+ * `generateThemeCss`; merge it over a complete {@link ThemeSchema} first.
+ * An absent or empty mode leaves the base mode unchanged.
+ */
+export type ThemeSchemaOverrides = {
+    light?: TokenSchemaOverrides;
+    dark?: TokenSchemaOverrides;
+};
 /** Generated CSS token key-value pairs (without the `--` prefix on keys). */
 export type GeneratedTokens = Record<string, string>;
 /** A complete theme definition with required light mode and optional dark mode */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/design-tokens",
-	"version": "1.14.0",
+	"version": "1.16.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",