@tenphi/glaze 0.0.0-snapshot.d860537 → 0.0.0-snapshot.e7185f1

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
@@ -387,6 +390,7 @@ Available tuning parameters:
 | `minGapTarget` | 0.05 | Target minimum gap between pigment and bg lightness |
 | `alphaMax` | 0.6 | Asymptotic maximum alpha |
 | `bgHueBlend` | 0.2 | Blend weight pulling pigment hue toward bg hue |
+| `darkShadowCurve` | 0.5 | Power curve for dark-scheme alpha (0-1). Lower = more dampening; 1 = no dampening |
 
 ### Standalone Shadow Computation
 
@@ -413,6 +417,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:
@@ -467,7 +604,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 +621,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 +640,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 +702,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:
+
+```ts
+const palette = glaze.palette(
+  { primary, danger, success, warning },
+  { primary: 'primary' },
+);
+```
+
+### Prefix Behavior
 
-Tokens are grouped by scheme variant, with plain color names as keys:
+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 +729,68 @@ Custom prefix mapping:
 palette.tokens({ prefix: { primary: 'brand-', danger: 'error-' } });
 ```
 
+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 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 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://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs) style system)
 
 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.):
 
 ```ts
-const tastyTokens = palette.tasty({ prefix: true });
+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 +857,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 +882,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 +902,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 +914,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 +949,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',
@@ -752,16 +964,17 @@ glaze.configure({
   shadowTuning: {              // Default tuning for all shadow colors
     alphaMax: 0.6,
     bgHueBlend: 0.2,
+    darkShadowCurve: 0.5,      // Power curve for dark-scheme alpha dampening (0-1)
   },
 });
 ```
 
 ## 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,9 +993,19 @@ 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
 
@@ -801,6 +1024,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
 
@@ -846,6 +1075,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 },
 });
@@ -855,18 +1088,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 });
@@ -921,7 +1157,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 |