@tenphi/glaze 0.0.0-snapshot.4c063ef → 0.0.0-snapshot.4e8eab7

package/README.md

@@ -22,6 +22,7 @@ Glaze generates robust **light**, **dark**, and **high-contrast** color schemes
 
 - **OKHSL color space** — perceptually uniform hue and saturation
 - **WCAG 2 contrast solving** — automatic lightness adjustment to meet AA/AAA targets
+- **Mix colors** — blend two colors with OKHSL or sRGB interpolation, opaque or transparent, with optional contrast solving
 - **Shadow colors** — OKHSL-native shadow computation with automatic alpha, fg/bg tinting, and per-scheme adaptation
 - **Light + Dark + High-Contrast** — all schemes from one definition
 - **Per-color hue override** — absolute or relative hue shifts within a theme
@@ -69,9 +70,9 @@ const danger  = primary.extend({ hue: 23 });
 const success = primary.extend({ hue: 157 });
 
 // Compose into a palette and export
-const palette = glaze.palette({ primary, danger, success });
-const tokens = palette.tokens({ prefix: true });
-// → { light: { 'primary-surface': 'okhsl(...)', ... }, dark: { 'primary-surface': 'okhsl(...)', ... } }
+const palette = glaze.palette({ primary, danger, success }, { primary: 'primary' });
+const tokens = palette.tokens();
+// → { light: { 'primary-surface': 'okhsl(...)', 'surface': 'okhsl(...)', ... }, dark: { ... } }
 ```
 
 ## Core Concepts
@@ -193,6 +194,8 @@ A single value applies to both modes. All control is local and explicit.
 'muted':  { base: 'surface', lightness: ['-35', '-50'], contrast: ['AA-large', 'AA'] }
 ```
 
+**Full lightness spectrum in HC mode:** In high-contrast variants, the `lightLightness` and `darkLightness` window constraints are bypassed entirely. Colors can reach the full 0–100 lightness range, maximizing perceivable contrast. Normal (non-HC) variants continue to use the configured windows.
+
 ## Theme Color Management
 
 ### Adding Colors
@@ -260,15 +263,306 @@ The export contains only the configuration — not resolved color values. Resolv
 Create a single color token without a full theme:
 
 ```ts
-const accent = glaze.color({ hue: 280, saturation: 80, lightness: 52, mode: 'fixed' });
+const accent = glaze.color({ hue: 280, saturation: 80, lightness: 52 });
+
+accent.resolve();          // → ResolvedColor with light/dark/lightContrast/darkContrast
+accent.token();            // → { '': 'okhsl(...)', '@dark': 'okhsl(...)' }  (tasty format)
+accent.tasty();            // → { '': 'okhsl(...)', '@dark': 'okhsl(...)' }  (same as token)
+accent.json();             // → { light: 'okhsl(...)', dark: 'okhsl(...)' }
+accent.css({ name: 'accent' });
+// → { light: '--accent-color: rgb(...);', dark: '--accent-color: rgb(...);', ... }
+accent.export();           // → JSON-safe snapshot — pass to `glaze.colorFrom(...)` to rehydrate
+```
+
+### Defaults
+
+`glaze.color()` is tuned for "render this exact color, but adapt the
+dark variant" — different from theme colors, which are seeds that
+adapt to both lightness windows. The defaults vary by input form,
+because string inputs are typically end-user values (color pickers,
+theme settings) where natural light/dark inversion is the expectation:
+
+Every input form defaults to **`mode: 'auto'`** so the resolved token
+adapts between light and dark like an ordinary theme color. The
+*scaling* snapshot taken at create time differs by input form:
+
+- **String value-shorthand** (hex, `rgb()`, `hsl()`, `okhsl()`,
+  `oklch()`):
+  - Light variant preserves the input lightness exactly.
+  - Dark variant is **Möbius-inverted** into `[globalConfig.darkLightness[0], 100]`,
+    so `glaze.color('#000')` renders as `#fff` in dark mode and
+    `glaze.color('#fff')` falls to the dark `lo` floor (default `0.15`).
+  - The dark `lo` is snapshotted from `globalConfig` at color-creation
+    time, matching how an explicit `scaling.darkLightness: [lo, hi]`
+    behaves.
+
+- **Object / tuple value-shorthand** (`{ h, s, l }`, `[r, g, b]`) and
+  the **structured form** (`{ hue, saturation, lightness, ... }`):
+  - Both light and dark variants are mapped through
+    `globalConfig.lightLightness` / `globalConfig.darkLightness`
+    (defaults `[10, 100]` / `[15, 95]`) — the same windows a theme color
+    uses. With the `'auto'` default the dark variant is Möbius-inverted
+    into that dark window, so a near-white seed lands at a near-dark
+    dark variant.
+  - Both windows are snapshotted at color-creation time so later
+    `glaze.configure()` calls don't retroactively change exported tokens.
+
+To opt back into the legacy fixed-linear default (no Möbius inversion),
+pass `{ mode: 'fixed' }` as the second arg, or supply an explicit
+`scaling` as the third arg (see [Lightness scaling](#lightness-scaling)).
+
+```ts
+// Default: pure black inverts to pure white in dark mode.
+glaze.color('#000000').tasty();
+// → { '': 'okhsl(0 0% 0%)', '@dark': 'okhsl(... 100%)' }
+
+// Opt back into the fixed-linear behavior:
+glaze.color('#000000', { mode: 'fixed' }).tasty();
+// → { '': 'okhsl(0 0% 0%)', '@dark': 'okhsl(... 15%)' }
+```
+
+### Value Shorthand
+
+The first argument can also be a color value — Glaze extracts the seed
+hue/saturation/lightness for you. All forms support the same exports
+(`resolve / token / tasty / json / css`):
+
+```ts
+// Hex (3, 6, or 8 digits — alpha dropped with warning)
+glaze.color('#26fcb2').tasty();
+glaze.color('#26fcb2ff').tasty(); // alpha dropped
+
+// CSS color functions Glaze itself emits (`rgb()`, `hsl()`, `okhsl()`, `oklch()`)
+// — anything from theme.tasty()/json()/css() round-trips back in.
+glaze.color('rgb(38 252 178)').tasty();
+glaze.color('hsl(152 97% 57%)').tasty();
+glaze.color('okhsl(152 95% 74%)').tasty();
+glaze.color('oklch(0.85 0.18 152)').tasty();
+
+// OKHSL object — Glaze's native shape (h: 0–360, s/l: 0–1).
+// Passing 0–100 values for s/l throws with a hint to use the
+// structured form { hue, saturation, lightness }.
+glaze.color({ h: 152, s: 0.95, l: 0.74 }).tasty();
+
+// RGB tuple, 0–255 (same range as glaze.fromRgb).
+glaze.color([38, 252, 178]).tasty();
+```
+
+The optional second argument supplies overrides — the WCAG `contrast`
+solver, relative `hue` / `lightness`, plus the usual seed knobs:
+
+```ts
+// Brand color seeded from a hex, with saturation/mode overrides
+glaze.color('#26fcb2', { saturation: 80, mode: 'fixed' }).tasty();
+
+// Brand text guaranteed AAA against the seed itself.
+// Relative `lightness: '+48'` is anchored to the literal seed value.
+glaze.color('#1a1a2e', {
+  lightness: '+48',
+  contrast: 'AAA',
+}).tasty();
+```
+
+By default, relative `lightness: '+N'` and `contrast: <ratio>` are
+anchored to the literal seed (the value passed to `glaze.color()`).
+Internally Glaze synthesizes a hidden `mode: 'static'` reference of
+the seed so the contrast solver compares against the unmapped color
+across every variant. Pass `base` (another `glaze.color()` token) to
+anchor against another color's resolved variant per scheme instead —
+see [Pairing Colors](#pairing-colors).
+
+All overrides:
+
+| Option | Notes |
+|---|---|
+| `hue` | Number (absolute 0–360) or `'+N'`/`'-N'` (relative to seed — never to `base`) |
+| `saturation` | Override seed saturation (0–100) |
+| `lightness` | Number (absolute 0–100) or `'+N'`/`'-N'`. Without `base`, relative is anchored to the literal seed; with `base`, anchored to `base`'s lightness per scheme. Supports `[normal, hc]` pairs |
+| `saturationFactor` | Multiplier on seed (0–1, default 1) |
+| `mode` | `'auto'` (default for every input form) / `'fixed'` / `'static'` — see [Adaptation Modes](#adaptation-modes) |
+| `contrast` | WCAG floor. Without `base`, anchored to the literal seed; with `base`, solved per scheme against `base`'s resolved variant. Same shape as `RegularColorDef.contrast`. When the target can't be physically met, `glaze` emits a `console.warn` and returns the closest passing variant |
+| `base` | Another `glaze.color()` token **or** a raw `GlazeColorValue` (hex / `rgb()` / `OkhslColor` / `[r, g, b]`). Raw values are auto-wrapped via `glaze.color(value)` so they pick up the same auto-invert defaults as an explicit wrap. When set, `contrast` and relative `lightness` anchor to it per scheme; relative `hue` still anchors to the seed |
+| `opacity` | Fixed alpha 0–1 applied to every variant. Surfaces in `rgb(... / A)`, `okhsl(... / A)`, etc. Combining with `contrast` is not recommended (perceived lightness becomes unpredictable) — `glaze` emits a `console.warn` |
+| `name` | **Debug label only** — surfaces in error and `console.warn` messages instead of the internal `"value"` sentinel. Does **not** change `.token()` / `.tasty()` / `.json()` / `.css()` output keys (those still use `''`, `light`, etc.). Reserved names (`"value"`, `"seed"`, `"externalBase"`) are rejected |
+
+Alpha components in `rgb(... / A)` / `hsl(... / A)` / `rgba(...)` /
+`hsla(...)` and 8-digit hex (`#rrggbbaa` / `#rgba`) are parsed but the
+alpha channel is dropped with a `console.warn`. To set a fixed alpha
+on a standalone color, use the `opacity` override (or `opacity` on a
+theme color). Named CSS colors (`'red'`, `'blueviolet'`) are not
+supported.
+
+### Lightness Scaling
+
+The optional third positional argument lets you override the lightness
+windows used by `glaze.color()`. Both keys mirror the field names from
+`GlazeConfig`:
+
+```ts
+// Preserve raw lightness in dark mode too:
+glaze.color('#26fcb2', undefined, { darkLightness: false }).tasty();
+
+// Or opt back into a theme-style window:
+glaze.color('#26fcb2', undefined, {
+  lightLightness: [10, 100],
+  darkLightness: [15, 95],
+}).tasty();
+
+// Structured form takes scaling as the second positional arg:
+glaze
+  .color({ hue: 152, saturation: 95, lightness: 74 }, { darkLightness: false })
+  .tasty();
+```
+
+| Key | Default for `glaze.color()` (string input) | Default for `glaze.color()` (object / tuple / structured) | Effect |
+|---|---|---|---|
+| `lightLightness` | `false` | `false` | `false` = preserve input. Pass `[lo, hi]` to opt into a remap window. |
+| `darkLightness` | `[globalConfig.darkLightness[0], 100]` (snapshotted; default `[15, 100]`) | `globalConfig.darkLightness` (snapshotted; default `[15, 95]`) | `false` = preserve input in dark too. Pass `[lo, hi]` to override the window. |
+
+> Note: `scaling` is all-or-nothing — passing it replaces both fields
+> at once. To keep one field's default, restate it explicitly. The
+> default windows are snapshotted from `globalConfig` at color-creation
+> time, so later `glaze.configure()` calls don't retroactively change
+> already-created tokens (and `token.export()` round-trips
+> byte-for-byte across `configure()` changes).
+
+### Pairing Colors
 
-accent.resolve();  // → ResolvedColor with light/dark/lightContrast/darkContrast
-accent.token();    // → { '': 'okhsl(...)', '@dark': 'okhsl(...)' }  (tasty format)
-accent.tasty();    // → { '': 'okhsl(...)', '@dark': 'okhsl(...)' }  (same as token)
-accent.json();     // → { light: 'okhsl(...)', dark: 'okhsl(...)' }
+`glaze.color()` accepts an optional `base` override that ties one
+standalone color to another. When you set `base`, the WCAG contrast
+solver and relative `lightness` offsets switch their anchor from the
+literal seed to the base's resolved variant per scheme — so the same
+text color automatically lands at AA against its background in light,
+dark, and high-contrast modes.
+
+```ts
+const bg = glaze.color('#1a1a2e');
+
+// Text guaranteed AA against `bg` in every scheme.
+const text = glaze.color('#ffffff', { base: bg, contrast: 'AA' });
+
+// Border 8 lightness units lighter than `bg` in each scheme.
+const border = glaze.color('#000000', {
+  base: bg,
+  lightness: '+8',
+  mode: 'fixed',
+});
 ```
 
-Standalone colors are always root colors (no `base`/`contrast`).
+`base` also accepts a raw `GlazeColorValue` for one-off pairs without
+a separate token binding:
+
+```ts
+// Equivalent to `base: glaze.color('#1a1a2e')` — `glaze` auto-wraps it.
+const text = glaze.color('#ffffff', { base: '#1a1a2e', contrast: 'AA' });
+```
+
+Behavior with `base`:
+
+- `contrast` is solved per scheme against `base`'s resolved variant
+  (light / dark / lightContrast / darkContrast).
+- Relative `lightness: '+N'` / `'-N'` is anchored to `base`'s lightness
+  per scheme (matches theme behavior).
+- Relative `hue: '+N'` still anchors to the **seed** (the value passed
+  to `glaze.color()`), not the base. Absolute hue overrides take
+  precedence as usual.
+- `mode` works as a per-pair knob — pass `mode: 'fixed'` to disable
+  Möbius inversion for the dependent color, or `mode: 'auto'` to keep
+  it (defaults follow the same string-vs-object rules as standalone).
+- The base token's `.resolve()` is called lazily on the first resolve
+  of the dependent and the result is captured by reference; later
+  mutations to the base don't apply (matches existing snapshot
+  semantics for `scaling.darkLightness`).
+- Raw value bases (`base: '#fff'`, `base: { h, s, l }`, `base: [r, g, b]`)
+  are auto-wrapped via `glaze.color(value)` and inherit the same
+  string-vs-object defaults. To skip auto-invert on the base, wrap it
+  yourself: `base: glaze.color(value, undefined, { darkLightness: false })`.
+- When the contrast target is physically unreachable (e.g. AAA against
+  a mid-grey base), `glaze` emits a single `console.warn` per
+  `(name, scheme, target)` triple and returns the closest passing
+  variant. Use the `name` override to make the warning more
+  identifiable in your logs.
+
+Chains compose:
+
+```ts
+const bg = glaze.color('#000000');
+const surface = glaze.color('#222222', { base: bg, contrast: 'AAA' });
+const text = glaze.color('#ffffff', { base: surface, contrast: 'AA' });
+// Each level meets its contrast budget against its base in every scheme.
+```
+
+### Naming Standalone Colors
+
+The `name` override is a **debug label**, not an output key:
+
+```ts
+const cardBg = glaze.color('#1a1a2e', {
+  name: 'card-bg',           // surfaces in `console.warn` / Error messages
+});
+
+cardBg.token();              // → { '': 'okhsl(...)', '@dark': 'okhsl(...)' }
+cardBg.json();               // → { light: 'okhsl(...)', dark: 'okhsl(...)' }
+cardBg.css({ name: 'card' }); // CSS variable name comes from `css({ name })`,
+                              // NOT from the override above
+```
+
+Use it to make warnings traceable when you have many `glaze.color()`
+calls in a project — without it, `glaze` falls back to the internal
+sentinel `"value"`:
+
+```ts
+// With name:
+// > glaze: color "card-bg" cannot meet contrast "AAA" (7.00) in dark scheme...
+
+// Without name:
+// > glaze: color "value" cannot meet contrast "AAA" (7.00) in dark scheme...
+```
+
+The reserved internal sentinels (`"value"`, `"seed"`, `"externalBase"`)
+are rejected with a clear error pointing at the conflict.
+
+### Persisting Standalone Colors
+
+`glaze.color()` tokens can be serialized to JSON-safe data and
+rehydrated later — useful for color pickers, theme settings UIs, and
+URL state.
+
+```ts
+const text = glaze.color('#1a1a1a', {
+  contrast: 'AA',
+  opacity: 0.9,
+  name: 'profile-text',
+});
+
+const data = text.export();         // JSON-safe snapshot
+const json = JSON.stringify(data);   // ship to localStorage / API / URL
+const restored = glaze.colorFrom(JSON.parse(json));
+// `restored.resolve()` matches `text.resolve()` byte-for-byte.
+```
+
+The export captures the original `value`, all overrides, and the
+effective `scaling` (snapshotted from `globalConfig` at create time so
+later `glaze.configure()` calls don't change exported tokens).
+Token-typed `base` is recursively serialized, value-typed `base` is
+preserved as the raw value.
+
+Both forms round-trip:
+
+```ts
+// Value form
+const a = glaze.color('#26fcb2', { contrast: 'AA' });
+const aBack = glaze.colorFrom(a.export());
+
+// Structured form
+const b = glaze.color({
+  hue: 280,
+  saturation: 50,
+  lightness: 50,
+  opacity: 0.5,
+});
+const bBack = glaze.colorFrom(b.export());
+```
 
 ## From Existing Colors
 
@@ -390,7 +684,10 @@ Available tuning parameters:
 
 ### Standalone Shadow Computation
 
-Compute a shadow outside of a theme:
+Compute a shadow outside of a theme. `bg` and `fg` accept any
+`GlazeColorValue`: hex (`#rgb` / `#rrggbb` / `#rrggbbaa`), `rgb()` /
+`hsl()` / `okhsl()` / `oklch()` strings, OKHSL objects, or `[r, g, b]`
+(0–255) tuples.
 
 ```ts
 const v = glaze.shadow({
@@ -400,6 +697,13 @@ const v = glaze.shadow({
 });
 // → { h: 280, s: 0.14, l: 0.2, alpha: 0.1 }
 
+// Equivalent with non-hex inputs:
+glaze.shadow({
+  bg: 'rgb(240 238 245)',
+  fg: { h: 280, s: 0.06, l: 0.13 },
+  intensity: 10,
+});
+
 const css = glaze.format(v, 'oklch');
 // → 'oklch(0.15 0.014 280 / 0.1)'
 ```
@@ -413,6 +717,139 @@ const css = glaze.format(v, 'oklch');
 }
 ```
 
+## Mix Colors
+
+Mix colors blend two existing colors together. Use them for hover overlays, tints, shades, and any derived color that sits between two reference colors.
+
+### Opaque Mix
+
+Produces a solid color by interpolating between `base` and `target`:
+
+```ts
+theme.colors({
+  surface: { lightness: 95 },
+  accent:  { lightness: 30 },
+
+  // 30% of the way from surface toward accent
+  tint: { type: 'mix', base: 'surface', target: 'accent', value: 30 },
+});
+```
+
+- `value` — mix ratio 0–100 (0 = pure base, 100 = pure target)
+- The result is a fully opaque color (alpha = 1)
+- Adapts to light/dark/HC schemes automatically via the resolved base and target
+
+### Transparent Mix
+
+Produces the target color with a controlled opacity — useful for hover overlays:
+
+```ts
+theme.colors({
+  surface: { lightness: 95 },
+  black:   { lightness: 0, saturation: 0 },
+
+  hover: {
+    type: 'mix',
+    base: 'surface',
+    target: 'black',
+    value: 8,
+    blend: 'transparent',
+  },
+});
+// hover → target color (black) with alpha = 0.08
+```
+
+The output color has `h`, `s`, `l` from the target and `alpha = value / 100`.
+
+### Blend Space
+
+By default, opaque mixing interpolates in OKHSL (perceptually uniform, consistent with Glaze's model). Use `space: 'srgb'` for linear sRGB interpolation, which matches browser compositing:
+
+```ts
+theme.colors({
+  surface: { lightness: 95 },
+  accent:  { lightness: 30 },
+
+  // sRGB blend — matches what the browser would render
+  hover: { type: 'mix', base: 'surface', target: 'accent', value: 20, space: 'srgb' },
+});
+```
+
+| Space | Behavior | Best for |
+|---|---|---|
+| `'okhsl'` (default) | Perceptually uniform OKHSL interpolation | Design token derivation |
+| `'srgb'` | Linear sRGB channel interpolation | Matching browser compositing |
+
+The `space` option only affects opaque blending. Transparent blending always composites in linear sRGB (matching browser alpha compositing).
+
+### Contrast Solving
+
+Mix colors support the same `contrast` prop as regular colors. The solver adjusts the mix ratio (opaque) or opacity (transparent) to meet the WCAG target:
+
+```ts
+theme.colors({
+  surface: { lightness: 95 },
+  accent:  { lightness: 30 },
+
+  // Ensure the mixed color has at least AA contrast against surface
+  tint: {
+    type: 'mix',
+    base: 'surface',
+    target: 'accent',
+    value: 10,
+    contrast: 'AA',
+  },
+
+  // Ensure the transparent overlay has at least 3:1 contrast
+  overlay: {
+    type: 'mix',
+    base: 'surface',
+    target: 'accent',
+    value: 5,
+    blend: 'transparent',
+    contrast: 3,
+  },
+});
+```
+
+### High-Contrast Pairs
+
+Both `value` and `contrast` support `[normal, highContrast]` pairs:
+
+```ts
+theme.colors({
+  surface: { lightness: 95 },
+  accent:  { lightness: 30 },
+
+  tint: {
+    type: 'mix',
+    base: 'surface',
+    target: 'accent',
+    value: [20, 40],          // stronger mix in high-contrast mode
+    contrast: [3, 'AAA'],     // stricter contrast in high-contrast mode
+  },
+});
+```
+
+### Achromatic Colors
+
+When mixing with achromatic colors (saturation near zero, e.g., white or black) in `okhsl` space, the hue comes from whichever color has saturation. This prevents meaningless hue artifacts and matches CSS `color-mix()` "missing component" behavior. For purely achromatic mixes, prefer `space: 'srgb'` where hue is irrelevant.
+
+### Mix Chaining
+
+Mix colors can reference other mix colors, enabling multi-step derivations:
+
+```ts
+theme.colors({
+  white: { lightness: 100, saturation: 0 },
+  black: { lightness: 0, saturation: 0 },
+  gray:  { type: 'mix', base: 'white', target: 'black', value: 50, space: 'srgb' },
+  lightGray: { type: 'mix', base: 'white', target: 'gray', value: 50, space: 'srgb' },
+});
+```
+
+Mix colors cannot reference shadow colors (same restriction as regular dependent colors).
+
 ## Output Formats
 
 Control the color format in exports with the `format` option:
@@ -431,7 +868,7 @@ theme.tokens({ format: 'hsl' });       // → 'hsl(270.5 45.2% 95.8%)'
 theme.tokens({ format: 'oklch' });     // → 'oklch(0.965 0.0123 280)'
 ```
 
-The `format` option works on all export methods: `theme.tokens()`, `theme.tasty()`, `theme.json()`, `theme.css()`, `palette.tokens()`, `palette.tasty()`, `palette.json()`, `palette.css()`, and standalone `glaze.color().token()` / `.tasty()` / `.json()`.
+The `format` option works on all export methods: `theme.tokens()`, `theme.tasty()`, `theme.json()`, `theme.css()`, `palette.tokens()`, `palette.tasty()`, `palette.json()`, `palette.css()`, and standalone `glaze.color().token()` / `.tasty()` / `.json()` / `.css()`.
 
 Colors with `alpha < 1` (shadow colors, or regular colors with `opacity`) include an alpha component:
 
@@ -467,7 +904,7 @@ Modes control how colors adapt across schemes:
 
 ```ts
 // Light: surface L=97, text lightness='-52' → L=45 (dark text on light bg)
-// Dark:  surface inverts to L≈14, sign flips → L=14+52=66
+// Dark:  surface inverts to L≈20 (Möbius curve), sign flips → L=20+52=72
 //        contrast solver may push further (light text on dark bg)
 ```
 
@@ -484,14 +921,14 @@ Modes control how colors adapt across schemes:
 
 ### Lightness
 
-Root color lightness is mapped linearly within the configured `lightLightness` window:
+Absolute lightness values (both root colors and dependent colors with absolute lightness) are mapped linearly within the configured `lightLightness` window:
 
 ```ts
 const [lo, hi] = lightLightness; // default: [10, 100]
 const mappedL = (lightness * (hi - lo)) / 100 + lo;
 ```
 
-Both `auto` and `fixed` modes use the same linear formula. `static` mode bypasses the mapping entirely.
+Both `auto` and `fixed` modes use the same linear formula. `static` mode and high-contrast variants bypass the mapping entirely (identity: `mappedL = l`).
 
 | Color | Raw L | Mapped L (default [10, 100]) |
 |---|---|---|
@@ -503,24 +940,29 @@ Both `auto` and `fixed` modes use the same linear formula. `static` mode bypasse
 
 ### Lightness
 
-**`auto`** — inverted within the configured window:
+**`auto`** — inverted with a Möbius transformation within the configured window:
 
 ```ts
 const [lo, hi] = darkLightness; // default: [15, 95]
-const invertedL = ((100 - lightness) * (hi - lo)) / 100 + lo;
+const t = (100 - lightness) / 100;
+const invertedL = lo + (hi - lo) * t / (t + darkCurve * (1 - t)); // darkCurve default: 0.5
 ```
 
-**`fixed`** — mapped without inversion:
+The `darkCurve` parameter (default `0.5`, range 0–1) controls how much the dark-mode inversion expands lightness deltas. Lower values produce stronger expansion; `1` gives linear (legacy) behavior. Accepts a `[normal, highContrast]` pair for separate HC tuning (e.g. `darkCurve: [0.5, 0.3]`); a single number applies to both. Unlike a power curve, the Möbius transformation provides **proportional expansion** — small and large deltas are scaled by similar ratios, preserving the visual hierarchy of the light theme.
+
+**`fixed`** — mapped without inversion (not affected by `darkCurve`):
 
 ```ts
 const mappedL = (lightness * (hi - lo)) / 100 + lo;
 ```
 
-| Color | Light L | Auto (inverted) | Fixed (mapped) |
-|---|---|---|---|
-| surface (L=97) | 97 | 17.4 | 92.6 |
-| accent-fill (L=52) | 52 | 53.4 | 56.6 |
-| accent-text (L=100) | 100 | 15 | 95 |
+| Color | Light L | Auto (curve=0.5) | Auto (curve=1, linear) | Fixed (mapped) |
+|---|---|---|---|---|
+| surface (L=97) | 97 | 19.7 | 17.4 | 92.6 |
+| accent-fill (L=52) | 52 | 66.9 | 53.4 | 56.6 |
+| accent-text (L=100) | 100 | 15 | 15 | 95 |
+
+In high-contrast variants, the `darkLightness` window is bypassed — auto uses the Möbius curve over the full [0, 100] range, and fixed uses identity (`L`). To use a different curve shape for HC, pass a `[normal, hc]` pair to `darkCurve` (e.g. `darkCurve: [0.5, 0.3]`).
 
 ### Saturation
 
@@ -560,12 +1002,21 @@ Combine multiple themes into a single palette:
 const palette = glaze.palette({ primary, danger, success, warning });
 ```
 
-### Token Export
+Optionally designate a primary theme at creation time:
 
-Tokens are grouped by scheme variant, with plain color names as keys:
+```ts
+const palette = glaze.palette(
+  { primary, danger, success, warning },
+  { primary: 'primary' },
+);
+```
+
+### Prefix Behavior
+
+Palette export methods (`tokens()`, `tasty()`, `css()`) default to `prefix: true` — all tokens are automatically prefixed with the theme name to avoid collisions:
 
 ```ts
-const tokens = palette.tokens({ prefix: true });
+const tokens = palette.tokens();
 // → {
 //   light: { 'primary-surface': 'okhsl(...)', 'danger-surface': 'okhsl(...)' },
 //   dark:  { 'primary-surface': 'okhsl(...)', 'danger-surface': 'okhsl(...)' },
@@ -578,15 +1029,68 @@ Custom prefix mapping:
 palette.tokens({ prefix: { primary: 'brand-', danger: 'error-' } });
 ```
 
-### Tasty Export (for [Tasty](https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs) style system)
+To disable prefixing entirely, pass `prefix: false` explicitly.
+
+### Collision Detection
+
+When two themes produce the same output key (via `prefix: false`, custom prefix maps, or primary unprefixed aliases), the first-written value wins and a `console.warn` is emitted:
+
+```ts
+const palette = glaze.palette({ a, b });
+palette.tokens({ prefix: false });
+// ⚠ glaze: token "surface" from theme "b" collides with theme "a" — skipping.
+```
+
+### Primary Theme
 
-The `tasty()` method exports tokens in the [Tasty](https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs) style-to-state binding format — `#name` color token keys with state aliases (`''`, `@dark`, etc.):
+The primary theme's tokens are duplicated without prefix, providing convenient short aliases alongside the prefixed versions. Set at palette creation to apply to all exports automatically:
 
 ```ts
-const tastyTokens = palette.tasty({ prefix: true });
+const palette = glaze.palette(
+  { primary, danger, success },
+  { primary: 'primary' },
+);
+const tokens = palette.tokens();
+// → {
+//   light: {
+//     'primary-surface': 'okhsl(...)',  // prefixed (all themes)
+//     'danger-surface':  'okhsl(...)',
+//     'success-surface': 'okhsl(...)',
+//     'surface':         'okhsl(...)',  // unprefixed alias (primary only)
+//   },
+// }
+```
+
+Override or disable per-export:
+
+```ts
+palette.tokens({ primary: 'danger' });  // use danger as primary for this call
+palette.tokens({ primary: false });     // no primary for this call
+```
+
+The `primary` option works on `tokens()`, `tasty()`, and `css()`. It combines with any prefix mode — when using a custom prefix map, primary tokens are still duplicated without prefix:
+
+```ts
+palette.tokens({ prefix: { primary: 'p-', danger: 'd-' } });
+// → 'p-surface' + 'surface' (alias from palette-level primary) + 'd-surface'
+```
+
+An error is thrown if the primary name doesn't match any theme in the palette.
+
+### Tasty Export (for [Tasty](https://tasty.style) style system)
+
+The `tasty()` method exports tokens in the [Tasty](https://tasty.style/docs) style-to-state binding format — `#name` color token keys with state aliases (`''`, `@dark`, etc.). See the [Playground](https://tasty.style/playground) for live examples of Glaze integration:
+
+```ts
+const palette = glaze.palette(
+  { primary, danger, success },
+  { primary: 'primary' },
+);
+const tastyTokens = palette.tasty();
 // → {
 //   '#primary-surface': { '': 'okhsl(...)', '@dark': 'okhsl(...)' },
 //   '#danger-surface':  { '': 'okhsl(...)', '@dark': 'okhsl(...)' },
+//   '#surface':         { '': 'okhsl(...)', '@dark': 'okhsl(...)' },  // alias
 // }
 ```
 
@@ -653,8 +1157,10 @@ palette.tasty({ states: { dark: '@dark', highContrast: '@hc' } });
 
 ### JSON Export (Framework-Agnostic)
 
+JSON export groups by theme name (no prefix needed):
+
 ```ts
-const data = palette.json({ prefix: true });
+const data = palette.json();
 // → {
 //   primary: { surface: { light: 'okhsl(...)', dark: 'okhsl(...)' } },
 //   danger:  { surface: { light: 'okhsl(...)', dark: 'okhsl(...)' } },
@@ -676,7 +1182,11 @@ const css = theme.css();
 Use in a stylesheet:
 
 ```ts
-const css = palette.css({ prefix: true });
+const palette = glaze.palette(
+  { primary, danger, success },
+  { primary: 'primary' },
+);
+const css = palette.css();
 
 const stylesheet = `
 :root { ${css.light} }
@@ -692,7 +1202,8 @@ Options:
 |---|---|---|
 | `format` | `'rgb'` | Color format (`'rgb'`, `'hsl'`, `'okhsl'`, `'oklch'`) |
 | `suffix` | `'-color'` | Suffix appended to each CSS property name |
-| `prefix` | — | (palette only) Same prefix behavior as `tokens()` |
+| `prefix` | `true` (palette) | (palette only) `true` uses `"<themeName>-"`, or provide a custom map |
+| `primary` | inherited | (palette only) Override or disable (`false`) the palette-level primary for this call |
 
 ```ts
 // Custom suffix
@@ -703,9 +1214,9 @@ theme.css({ suffix: '' });
 theme.css({ format: 'hsl' });
 // → "--surface-color: hsl(...);"
 
-// Palette with prefix
-palette.css({ prefix: true });
-// → "--primary-surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
+// Palette with primary (inherited from palette creation)
+palette.css();
+// → "--primary-surface-color: rgb(...);\n--surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
 ```
 
 ## Output Modes
@@ -738,9 +1249,10 @@ Resolution priority (highest first):
 
 ```ts
 glaze.configure({
-  lightLightness: [10, 100],   // Light scheme lightness window [lo, hi]
-  darkLightness: [15, 95],     // Dark scheme lightness window [lo, hi]
+  lightLightness: [10, 100],   // Light scheme lightness window [lo, hi] (bypassed in HC)
+  darkLightness: [15, 95],     // Dark scheme lightness window [lo, hi] (bypassed in HC)
   darkDesaturation: 0.1,       // Saturation reduction in dark scheme (0–1)
+  darkCurve: 0.5,              // Möbius beta for dark auto-inversion (0–1); or [normal, hc] pair
   states: {
     dark: '@dark',             // State alias for dark mode tokens
     highContrast: '@high-contrast',
@@ -758,10 +1270,10 @@ glaze.configure({
 
 ## Color Definition Shape
 
-`ColorDef` is a discriminated union of regular colors and shadow colors:
+`ColorDef` is a discriminated union of regular colors, shadow colors, and mix colors:
 
 ```ts
-type ColorDef = RegularColorDef | ShadowColorDef;
+type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
 
 interface RegularColorDef {
   lightness?: HCPair<number | RelativeValue>;
@@ -780,15 +1292,24 @@ interface ShadowColorDef {
   intensity: HCPair<number>; // 0–100
   tuning?: ShadowTuning;
 }
+
+interface MixColorDef {
+  type: 'mix';
+  base: string;     // "from" color name
+  target: string;   // "to" color name
+  value: HCPair<number>;     // 0–100 (mix ratio or opacity)
+  blend?: 'opaque' | 'transparent'; // default: 'opaque'
+  space?: 'okhsl' | 'srgb';        // default: 'okhsl'
+  contrast?: HCPair<MinContrast>;
+}
 ```
 
-A root color must have absolute `lightness` (a number). A dependent color must have `base`. Relative `lightness` (a string) requires `base`. Shadow colors use `type: 'shadow'` and must reference a non-shadow `bg` color.
+A root color must have absolute `lightness` (a number). A dependent color must have `base`. Relative `lightness` (a string) requires `base`. Shadow colors use `type: 'shadow'` and must reference a non-shadow `bg` color. Mix colors use `type: 'mix'` and must reference two non-shadow colors.
 
 ## Validation
 
 | Condition | Behavior |
 |---|---|
-| Both absolute `lightness` and `base` on same color | Warning, `lightness` takes precedence |
 | `contrast` without `base` | Validation error |
 | Relative `lightness` without `base` | Validation error |
 | `lightness` resolves outside 0–100 | Clamp silently |
@@ -802,6 +1323,12 @@ A root color must have absolute `lightness` (a number). A dependent color must h
 | Regular color `base` references a shadow color | Validation error |
 | Shadow `intensity` outside 0–100 | Clamp silently |
 | `contrast` + `opacity` combined | Warning |
+| Mix `base` references non-existent color | Validation error |
+| Mix `target` references non-existent color | Validation error |
+| Mix `base` references a shadow color | Validation error |
+| Mix `target` references a shadow color | Validation error |
+| Mix `value` outside 0–100 | Clamp silently |
+| Circular references involving mix colors | Validation error |
 
 ## Advanced: Color Math Utilities
 
@@ -847,6 +1374,10 @@ primary.colors({
   'shadow-md':   { type: 'shadow', bg: 'surface', fg: 'text', intensity: 10 },
   'shadow-lg':   { type: 'shadow', bg: 'surface', fg: 'text', intensity: 20 },
 
+  // Mix colors — hover overlays and tints
+  'hover':       { type: 'mix', base: 'surface', target: 'accent-fill', value: 8, blend: 'transparent' },
+  'tint':        { type: 'mix', base: 'surface', target: 'accent-fill', value: 20 },
+
   // Fixed-alpha overlay
   overlay:       { lightness: 0, opacity: 0.5 },
 });
@@ -856,18 +1387,21 @@ const success = primary.extend({ hue: 157 });
 const warning = primary.extend({ hue: 84 });
 const note    = primary.extend({ hue: 302 });
 
-const palette = glaze.palette({ primary, danger, success, warning, note });
+const palette = glaze.palette(
+  { primary, danger, success, warning, note },
+  { primary: 'primary' },
+);
 
-// Export as flat token map grouped by variant
-const tokens = palette.tokens({ prefix: true });
-// tokens.light → { 'primary-surface': 'okhsl(...)', 'primary-shadow-md': 'okhsl(... / 0.1)' }
+// Export as flat token map grouped by variant (prefix defaults to true)
+const tokens = palette.tokens();
+// tokens.light → { 'primary-surface': '...', 'surface': '...', 'danger-surface': '...' }
 
 // Export as tasty style-to-state bindings (for Tasty style system)
-const tastyTokens = palette.tasty({ prefix: true });
+const tastyTokens = palette.tasty();
 
 // Export as CSS custom properties (rgb format by default)
-const css = palette.css({ prefix: true });
-// css.light → "--primary-surface-color: rgb(...);\n--primary-shadow-md-color: rgb(... / 0.1);"
+const css = palette.css();
+// css.light → "--primary-surface-color: rgb(...);\n--surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
 
 // Standalone shadow computation
 const v = glaze.shadow({ bg: '#f0eef5', fg: '#1a1a2e', intensity: 10 });
@@ -894,8 +1428,10 @@ brand.colors({ surface: { lightness: 97 }, text: { base: 'surface', lightness: '
 | `glaze.from(data)` | Create a theme from an exported configuration |
 | `glaze.fromHex(hex)` | Create a theme from a hex color (`#rgb` or `#rrggbb`) |
 | `glaze.fromRgb(r, g, b)` | Create a theme from RGB values (0–255) |
-| `glaze.color(input)` | Create a standalone color token |
-| `glaze.shadow(input)` | Compute a standalone shadow color (returns `ResolvedColorVariant`) |
+| `glaze.color(input, scaling?)` | Create a standalone color token from `{ hue, saturation, lightness, opacity?, contrast?, base?, name?, ... }`. Optional `scaling` overrides the lightness windows |
+| `glaze.color(value, overrides?, scaling?)` | Create a standalone color token from a hex string (3/6/8 digits), an `rgb()` / `hsl()` / `okhsl()` / `oklch()` string, an `{ h, s, l }` OKHSL object, or an `[r, g, b]` (0–255) tuple. Overrides accept absolute or relative `hue` / `lightness`, `saturation`, `mode`, `contrast`, `opacity`, `name`, and `base` (a `GlazeColorToken` or any `GlazeColorValue`; raw values are auto-wrapped). When `base` is set, `contrast` and relative `lightness` are anchored to the base per scheme — see [Pairing Colors](#pairing-colors). Every input form defaults to `mode: 'auto'`; string inputs additionally preserve light lightness exactly and extend the dark window to `[lo, 100]`, while object / tuple / structured inputs snapshot both windows from `globalConfig.lightLightness` / `globalConfig.darkLightness`. |
+| `glaze.colorFrom(data)` | Rehydrate a `glaze.color()` token from a `.export()` snapshot. Inverse of `token.export()` — see [Persisting Standalone Colors](#persisting-standalone-colors) |
+| `glaze.shadow(input)` | Compute a standalone shadow color (returns `ResolvedColorVariant`). `bg` / `fg` accept any `GlazeColorValue` form |
 | `glaze.format(variant, format?)` | Format any `ResolvedColorVariant` as a CSS string |
 
 ### Theme Methods
@@ -913,7 +1449,7 @@ brand.colors({ surface: { lightness: 97 }, text: { base: 'surface', lightness: '
 | `theme.extend(options)` | Create a child theme |
 | `theme.resolve()` | Resolve all colors |
 | `theme.tokens(options?)` | Export as flat token map grouped by variant |
-| `theme.tasty(options?)` | Export as [Tasty](https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs) style-to-state bindings |
+| `theme.tasty(options?)` | Export as [Tasty](https://tasty.style/docs) style-to-state bindings |
 | `theme.json(options?)` | Export as plain JSON |
 | `theme.css(options?)` | Export as CSS custom property declarations |
 
@@ -922,7 +1458,7 @@ brand.colors({ surface: { lightness: 97 }, text: { base: 'surface', lightness: '
 | Method | Description |
 |---|---|
 | `glaze.configure(config)` | Set global configuration |
-| `glaze.palette(themes)` | Compose themes into a palette |
+| `glaze.palette(themes, options?)` | Compose themes into a palette (options: `{ primary? }`) |
 | `glaze.getConfig()` | Get current global config |
 | `glaze.resetConfig()` | Reset to defaults |