@tenphi/glaze 0.0.0-snapshot.c8281e2 → 0.0.0-snapshot.cdd8acc

package/README.md

@@ -70,8 +70,8 @@ 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({ primary: 'primary' });
+const palette = glaze.palette({ primary, danger, success }, { primary: 'primary' });
+const tokens = palette.tokens();
 // → { light: { 'primary-surface': 'okhsl(...)', 'surface': 'okhsl(...)', ... }, dark: { ... } }
 ```
 
@@ -265,13 +265,70 @@ Create a single color token without a full theme:
 ```ts
 const accent = glaze.color({ hue: 280, saturation: 80, lightness: 52, mode: 'fixed' });
 
-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.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(...);', ... }
+```
+
+### 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 or 6 digits)
+glaze.color('#26fcb2').tasty();
+
+// 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)
+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();
 ```
 
-Standalone colors are always root colors (no `base`/`contrast`).
+Optional second argument supplies overrides — including `base` (any color
+value), the WCAG `contrast` solver, and relative `hue` / `lightness`:
+
+```ts
+// Brand color seeded from a hex, with seed/lightness/mode overrides
+glaze.color('#26fcb2', { saturation: 80, mode: 'fixed' }).tasty();
+
+// Brand text guaranteed AAA against a brand-tinted dark surface
+glaze.color('#26fcb2', {
+  base: '#1a1a2e',           // any GlazeColorValue
+  lightness: '+48',          // relative offset from base lightness
+  contrast: 'AAA',
+  mode: 'fixed',
+}).tasty();
+```
+
+All overrides:
+
+| Option | Notes |
+|---|---|
+| `hue` | Number (absolute 0–360) or `'+N'`/`'-N'` (relative to seed) |
+| `saturation` | Override seed saturation (0–100) |
+| `lightness` | Number (absolute 0–100) or `'+N'`/`'-N'` (relative to base — requires `base`). Supports `[normal, hc]` pairs |
+| `saturationFactor` | Multiplier on seed (0–1, default 1) |
+| `mode` | `'auto'` (default) / `'fixed'` / `'static'` — see [Adaptation Modes](#adaptation-modes) |
+| `base` | Any `GlazeColorValue` — required for relative `lightness` and `contrast` |
+| `contrast` | WCAG floor against `base`. Same shape as `RegularColorDef.contrast` |
+
+Alpha components in `rgb(... / A)` / `hsl(... / A)` / `rgba(...)` / `hsla(...)` are
+parsed but the alpha channel is dropped with a `console.warn` (standalone
+colors have no opacity field — use `opacity` on a theme color if you need
+alpha). Named CSS colors (`'red'`, `'blueviolet'`) are not supported.
 
 ## From Existing Colors
 
@@ -567,7 +624,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:
 
@@ -603,7 +660,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)
 ```
 
@@ -639,26 +696,29 @@ Both `auto` and `fixed` modes use the same linear formula. `static` mode and hig
 
 ### 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 pure inversion (`100 - L`), fixed uses identity (`L`). This allows HC colors to reach the full 0–100 range.
+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
 
@@ -698,6 +758,15 @@ Combine multiple themes into a single palette:
 const palette = glaze.palette({ primary, danger, success, warning });
 ```
 
+Optionally designate a primary theme at creation time:
+
+```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:
@@ -716,15 +785,28 @@ Custom prefix mapping:
 palette.tokens({ prefix: { primary: 'brand-', danger: 'error-' } });
 ```
 
-To disable prefixing entirely, pass `prefix: false` explicitly. Note that tokens with the same name will overwrite each other (last theme wins).
+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
 
-Use the `primary` option to designate one theme as the primary. Its tokens are duplicated without prefix, providing convenient short aliases alongside the prefixed versions:
+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 });
-const tokens = palette.tokens({ primary: 'primary' });
+const palette = glaze.palette(
+  { primary, danger, success },
+  { primary: 'primary' },
+);
+const tokens = palette.tokens();
 // → {
 //   light: {
 //     'primary-surface': 'okhsl(...)',  // prefixed (all themes)
@@ -735,21 +817,32 @@ const tokens = palette.tokens({ primary: 'primary' });
 // }
 ```
 
+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-' }, primary: 'primary' });
-// → 'p-surface' + 'surface' (alias) + 'd-surface'
+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)
+### Tasty Export (for [Tasty](https://tasty.style) 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.):
+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 tastyTokens = palette.tasty({ primary: 'primary' });
+const palette = glaze.palette(
+  { primary, danger, success },
+  { primary: 'primary' },
+);
+const tastyTokens = palette.tasty();
 // → {
 //   '#primary-surface': { '': 'okhsl(...)', '@dark': 'okhsl(...)' },
 //   '#danger-surface':  { '': 'okhsl(...)', '@dark': 'okhsl(...)' },
@@ -845,7 +938,11 @@ const css = theme.css();
 Use in a stylesheet:
 
 ```ts
-const css = palette.css({ primary: 'primary' });
+const palette = glaze.palette(
+  { primary, danger, success },
+  { primary: 'primary' },
+);
+const css = palette.css();
 
 const stylesheet = `
 :root { ${css.light} }
@@ -862,7 +959,7 @@ Options:
 | `format` | `'rgb'` | Color format (`'rgb'`, `'hsl'`, `'okhsl'`, `'oklch'`) |
 | `suffix` | `'-color'` | Suffix appended to each CSS property name |
 | `prefix` | `true` (palette) | (palette only) `true` uses `"<themeName>-"`, or provide a custom map |
-| `primary` | — | (palette only) Theme name to duplicate without prefix |
+| `primary` | inherited | (palette only) Override or disable (`false`) the palette-level primary for this call |
 
 ```ts
 // Custom suffix
@@ -873,8 +970,8 @@ theme.css({ suffix: '' });
 theme.css({ format: 'hsl' });
 // → "--surface-color: hsl(...);"
 
-// Palette with primary
-palette.css({ primary: 'primary' });
+// Palette with primary (inherited from palette creation)
+palette.css();
 // → "--primary-surface-color: rgb(...);\n--surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
 ```
 
@@ -911,6 +1008,7 @@ glaze.configure({
   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',
@@ -1045,17 +1143,20 @@ 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 (prefix defaults to true)
-const tokens = palette.tokens({ primary: 'primary' });
+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({ primary: 'primary' });
+const tastyTokens = palette.tasty();
 
 // Export as CSS custom properties (rgb format by default)
-const css = palette.css({ primary: 'primary' });
+const css = palette.css();
 // css.light → "--primary-surface-color: rgb(...);\n--surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
 
 // Standalone shadow computation
@@ -1083,7 +1184,8 @@ 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.color(input)` | Create a standalone color token from `{ hue, saturation, lightness, ... }` |
+| `glaze.color(value, overrides?)` | Create a standalone color token from a hex string, 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`, `base` (any value form), and `contrast` |
 | `glaze.shadow(input)` | Compute a standalone shadow color (returns `ResolvedColorVariant`) |
 | `glaze.format(variant, format?)` | Format any `ResolvedColorVariant` as a CSS string |
 
@@ -1102,7 +1204,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 |
 
@@ -1111,7 +1213,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 |