@tenphi/glaze 0.12.0 → 0.14.0

package/docs/methodology.md

@@ -65,58 +65,58 @@ A tight, predictable vocabulary that the rest of the doc relies on:
 
 ## Surfaces (root colors)
 
-`surface` is a root color (absolute `lightness`, no `base`) with a low saturation factor. The ladder chains off it via small relative offsets:
+`surface` is a root color (absolute `tone`, no `base`) with a low saturation factor. The ladder chains off it via small relative offsets:
 
 ```ts
 defaultTheme.colors({
-  surface:     { lightness: 100, saturation: 0.11 },
-  'surface-2': { base: 'surface', lightness: '-2', saturation: 0.15, inherit: false },
-  'surface-3': { base: 'surface', lightness: '-4', saturation: 0.19, inherit: false },
+  surface:     { tone: 100, saturation: 0.11 },
+  'surface-2': { base: 'surface', tone: '-2', saturation: 0.15, inherit: false },
+  'surface-3': { base: 'surface', tone: '-4', saturation: 0.19, inherit: false },
 });
 ```
 
-A factor of `0.11` of the seed gives a barely-noticeable hue shift — enough that light/dark surfaces feel branded, not enough to look tinted. The slight saturation bump on `-2` / `-3` compensates for perceived saturation dropping as lightness drops, so the ladder reads as one consistent surface family.
+A factor of `0.11` of the seed gives a barely-noticeable hue shift — enough that light/dark surfaces feel branded, not enough to look tinted. The slight saturation bump on `-2` / `-3` compensates for perceived saturation dropping as tone drops, so the ladder reads as one consistent surface family.
 
-`mode: 'auto'` (the default) feeds these through Glaze's Möbius dark inversion, so an `L=100` light-mode surface lands near `L≈15` in dark mode with proportional deltas across the ladder preserved. `inherit: false` on `-2` / `-3` keeps colored sibling themes lean — they only need a single tinted `surface`, not the whole ladder.
+`mode: 'auto'` (the default) inverts these in tone (`100 − t`) and remaps into the dark window, so a `tone: 100` light-mode surface lands at the dark window's floor in dark mode. Because tone is contrast-uniform, the relative deltas (`-2`, `-4`) translate to the same contrast steps in both schemes — no fitted curve required. `inherit: false` on `-2` / `-3` keeps colored sibling themes lean — they only need a single tinted `surface`, not the whole ladder.
 
 ## Text on surfaces (anchor at the edge)
 
-The headline trick of the whole methodology. Strong text uses an **absolute `lightness` near the edge of the window**; soft variants use a **directional relative hint plus a numeric `contrast`**.
+The headline trick of the whole methodology. Strong text uses an **absolute `tone` near the edge of the window**; soft variants use a **directional relative hint plus a numeric `contrast`**.
 
 ```ts
 'surface-text': {
-  base: 'surface', lightness: 2, saturation: 0.475,
+  base: 'surface', tone: 2, saturation: 0.475,
 },
 'surface-text-soft': {
-  base: 'surface', lightness: '-1', saturation: 0.375,
+  base: 'surface', tone: '-1', saturation: 0.375,
   contrast: [9, 11], inherit: false,
 },
 'surface-text-soft-2': {
-  base: 'surface', lightness: '-1', saturation: 0.24,
+  base: 'surface', tone: '-1', saturation: 0.24,
   contrast: [4.5, 5.5], inherit: false,
 },
 ```
 
 Repeat the same triple anchored to each subordinate surface (`surface-2-text`, `surface-2-text-soft`, `surface-3-text`, …) so the ladder stays self-consistent.
 
-The strong-text `lightness: 2` pins the light-mode resolved value to **L≈11.8** (mapped through the default `[10, 100]` window) and inverts to **L≈94** in dark mode (cr≈13.7 vs the dark surface). A `contrast: 'AAA'` solver pass would have stopped at L≈21 — meeting the AAA floor and no further. **Anchoring at the edge** beats the contrast solver because the solver only needs to *meet* the floor, not exceed it.
+The strong-text `tone: 2` pins the light-mode resolved value near the bottom of the light window (close to black against the near-white surface) and inverts to near-white in dark mode — both yielding very high contrast against their surface. A `contrast: 'AAA'` solver pass would have stopped at the AAA floor (cr = 7) and no further. **Anchoring at the edge** beats the contrast solver because the solver only needs to *meet* the floor, not exceed it.
 
-The soft variants use `lightness: '-1'` only as a *directional hint* — the real positioning comes from the numeric `contrast`. Numeric ratios give designers precise perceived weight where presets would only guarantee the AA/AAA floor.
+The soft variants use `tone: '-1'` only as a *directional hint* — the real positioning comes from the numeric `contrast`. Numeric ratios give designers precise perceived weight where presets would only guarantee the AA/AAA floor.
 
-In high-contrast mode the lightness window is bypassed entirely, so `lightness: 2` resolves to L=2 in light HC and L≈99 in dark HC (cr≈20.8 / 20.5).
+In high-contrast mode the tone window is bypassed entirely (full `[0, 100]` range), so `tone: 2` reaches close to black in light HC and close to white in dark HC — maximal contrast against the surface in both.
 
 ## Other neutral primitives
 
-Borders, placeholders, focus rings, and the floating "muted text" lightness — all default-only:
+Borders, placeholders, focus rings, and the floating "muted text" tone — all default-only:
 
 ```ts
-border:      { base: 'surface', lightness: ['-10', '-20'], saturation: 0.175,  inherit: false },
-placeholder: { base: 'surface', lightness: 67,             saturation: 0.175,  inherit: false },
-focus:       { base: 'surface', lightness: 71,             saturation: 0.8625, inherit: false },
-disabled:    { lightness: 80.8, saturation: 0.4,                                inherit: false },
+border:      { base: 'surface', tone: ['-10', '-20'], saturation: 0.175,  inherit: false },
+placeholder: { base: 'surface', tone: 67,             saturation: 0.175,  inherit: false },
+focus:       { base: 'surface', tone: 71,             saturation: 0.8625, inherit: false },
+disabled:    { tone: 80.8, saturation: 0.4,                                inherit: false },
 ```
 
-`border` uses an HC pair — the border darkens twice as much in high-contrast mode for visibility. `placeholder` and `focus` give a `base` for namespacing but use absolute lightness independently. `disabled` is a root color (no `base`) — it's used as a plain "muted text" token in some places, free of the surface chain.
+`border` uses an HC pair — the border darkens twice as much in high-contrast mode for visibility. `placeholder` and `focus` give a `base` for namespacing but use absolute tone independently. `disabled` is a root color (no `base`) — it's used as a plain "muted text" token in some places, free of the surface chain.
 
 ## Disabled chip (contrast-driven for scheme symmetry)
 
@@ -124,11 +124,11 @@ The disabled chip + label pair uses `mode: 'auto'` and **explicit numeric contra
 
 ```ts
 'disabled-surface': {
-  base: 'surface', lightness: '-1', saturation: 0.2,
+  base: 'surface', tone: '-1', saturation: 0.2,
   contrast: [1.5, 2], inherit: false,
 },
 'disabled-surface-text': {
-  base: 'disabled-surface', lightness: '+1', saturation: 0.3,
+  base: 'disabled-surface', tone: '+1', saturation: 0.3,
   contrast: 3, inherit: false,
 },
 ```
@@ -141,11 +141,11 @@ The general rule: when a color needs to *feel the same across schemes*, anchor i
 
 ```ts
 'surface-inverse': {
-  lightness: 12, saturation: 0.475, mode: 'fixed', inherit: false,
+  tone: 12, saturation: 0.475, mode: 'fixed', inherit: false,
 },
 ```
 
-`mode: 'fixed'` skips the dark-scheme Möbius inversion and only does a linear window mapping, so `surface-inverse` reads as a dark surface in *every* scheme — light, dark, and HC. In high-contrast variants the window is bypassed entirely (identity), so the color stays at its raw lightness across all four schemes.
+`mode: 'fixed'` skips the dark-scheme tone inversion and only remaps the tone into the dark window, so `surface-inverse` reads as a dark surface in *every* scheme — light, dark, and HC. In high-contrast variants the window is bypassed entirely (identity), so the color stays at its raw tone across all four schemes.
 
 Use it for tooltips, code blocks, popovers with their own dark theme. Pair with `#white` for foreground text.
 
@@ -153,21 +153,21 @@ This is the canonical "I want this color to stay recognizable" pattern. The othe
 
 ## Accent system (anchor pattern)
 
-The load-bearing trick. Define a single fixed white anchor `accent-surface-text`, then derive every accent surface from it with a small relative lightness offset and a numeric contrast under `mode: 'fixed'`:
+The load-bearing trick. Define a single fixed white anchor `accent-surface-text`, then derive every accent surface from it with a small relative tone offset and a numeric contrast under `mode: 'fixed'`:
 
 ```ts
-'accent-surface-text': { lightness: 100, mode: 'fixed' },
+'accent-surface-text': { tone: 100, mode: 'fixed' },
 
-'accent-surface':       { base: 'accent-surface-text', lightness: '-1', contrast: [4.5, 7],   mode: 'fixed' },
-'accent-surface-2':     { base: 'accent-surface-text', lightness: '-1', contrast: [4.8, 7.5], mode: 'fixed' },
-'accent-surface-3':     { base: 'accent-surface-text', lightness: '-1', contrast: [5.2, 8],   mode: 'fixed' },
-'accent-surface-hover': { base: 'accent-surface-text', lightness: '-1', contrast: [6,   8.5], mode: 'fixed' },
+'accent-surface':       { base: 'accent-surface-text', tone: '-1', contrast: [4.5, 7],   mode: 'fixed' },
+'accent-surface-2':     { base: 'accent-surface-text', tone: '-1', contrast: [4.8, 7.5], mode: 'fixed' },
+'accent-surface-3':     { base: 'accent-surface-text', tone: '-1', contrast: [5.2, 8],   mode: 'fixed' },
+'accent-surface-hover': { base: 'accent-surface-text', tone: '-1', contrast: [6,   8.5], mode: 'fixed' },
 ```
 
 Three things make this work:
 
 - **One anchor, one chain.** All accent surfaces stay in the same hue family because they all derive from `accent-surface-text`.
-- **`mode: 'fixed'` keeps the brand recognizable.** Without it, the dark-scheme Möbius inversion would turn the brand fill into a lightness-inverted counterpart that may no longer read as the intended brand surface. Fixed maps lightness linearly into the dark window, so a `L=52` brand color resolves to ~L=51.6 in dark mode — still recognizably the same color.
+- **`mode: 'fixed'` keeps the brand recognizable.** Without it, the dark-scheme tone inversion would turn the brand fill into a tone-inverted counterpart that may no longer read as the intended brand surface. Fixed remaps the tone into the dark window without inverting, so a `tone: 52` brand color stays mid-toned in dark mode — still recognizably the same color.
 - **Numeric contrasts, not presets.** `'AA'` / `'AAA'` would let the solver push the color far away from its anchor in dark schemes, breaking the relationship between `accent-surface` and its neighbors. Numeric ratios make the darkening between `accent-surface` (4.5/7), `-2` (4.8/7.5), `-3` (5.2/8), and `-hover` (6/8.5) a tight, designed sequence — a stepped gradient rather than four solver-generated outliers.
 
 The hover variant is a dedicated *fixed* token. Reusing `accent-text` (which is `mode: 'auto'` and inverts direction in dark) would break the hover feel.
@@ -177,31 +177,41 @@ The hover variant is a dedicated *fixed* token. Reusing `accent-text` (which is
 The opposite of the fills. Brand-colored *foregrounds* are anchored to **`surface`, not `accent-surface`**, with `mode: 'auto'` (default) and full saturation:
 
 ```ts
-'accent-text':      { base: 'surface', lightness: '-1', saturation: 1,      contrast: [6.4, 10] },
-'accent-text-soft': { base: 'surface', lightness: '-1', saturation: 1,      contrast: [4.5, 7]  },
-'accent-icon':      { base: 'surface', lightness: '-1', saturation: 0.9375, contrast: [3.2, 5]  },
+'accent-text':      { base: 'surface', tone: '-1', saturation: 1,      contrast: [6.4, 10] },
+'accent-text-soft': { base: 'surface', tone: '-1', saturation: 1,      contrast: [4.5, 7]  },
+'accent-icon':      { base: 'surface', tone: '-1', saturation: 0.9375, contrast: [3.2, 5]  },
 ```
 
-Foregrounds need to stay readable on the surface they actually sit on — anchoring to the brand fill would only enforce contrast against that fill, leaving the dark-mode color washed out against the actual surface (e.g. SECONDARY button labels sit on `surface`, not on the brand fill). Anchoring to `surface` + `mode: 'auto'` lets the solver lift the lightness in dark mode so the contrast floor holds in both schemes.
+Foregrounds need to stay readable on the surface they actually sit on — anchoring to the brand fill would only enforce contrast against that fill, leaving the dark-mode color washed out against the actual surface (e.g. SECONDARY button labels sit on `surface`, not on the brand fill). Anchoring to `surface` + `mode: 'auto'` lets the solver lift the tone in dark mode so the contrast floor holds in both schemes.
 
 `accent-text-soft` shares the anchor and saturation but relaxes the contrast floor for a visibly less prominent secondary foreground (link base color, subdued labels). Critically, it stays `mode: 'auto'` — a fixed version would collapse to cr≈3 against the dark surface and break AA.
 
 ## Brand-tinted disabled
 
-Mirrors the neutral disabled pair from above but with higher saturation so the chip reads as a *muted brand color* rather than fully neutral grey:
+Mirrors the neutral disabled pair from above but with higher saturation so the chip reads as a *muted brand color* rather than fully neutral grey. A disabled chip has no contrast *requirement* — it just needs to sit a hair off the surface and carry a faint label. That's a job for **tone**, not the contrast solver:
 
 ```ts
 'accent-disabled-surface': {
-  base: 'surface', lightness: '-1', saturation: 0.5,
-  contrast: [1.4, 1.3],
+  base: 'surface', tone: '+3', saturation: 0.5,
 },
 'accent-disabled-surface-text': {
-  base: 'accent-disabled-surface', lightness: '+1', saturation: 0.4,
-  contrast: 1.51, mode: 'fixed',
+  base: 'accent-disabled-surface', tone: '+18', saturation: 0.4,
+  flip: false,
 },
 ```
 
-The HC pair `[1.4, 1.3]` is intentionally *lower* in high-contrast mode — the tinted chip naturally gains more contrast against `surface` when the lightness window bypasses (identity mapping), so we loosen the constraint to leave room for stronger text-on-chip contrast. The text token uses `contrast: 1.51`, which is the maximum value that stays below Glaze's auto-flip threshold (the solver would otherwise invert the color past the midpoint, producing a result on the wrong side of its base). This keeps the label legible without flipping into an unexpected hue.
+Tone offsets say what we mean directly: the chip is three tone steps off `surface`, the label eighteen steps off the chip — a deliberately low-contrast pair, no solver involved. Because tone is contrast-uniform, those steps look the same in light and dark, and `mode: 'auto'` (the default) keeps the relationship intact when the scheme inverts.
+
+`flip: false` on the label is the safety rail. A relative `tone: '+18'` lands above the chip; if the chip is already near the top of the range (a light surface), `+18` would overshoot 100. With flip on (the default), Glaze mirrors the offset to `-18` so it reflects back into range — handy for contrast tokens, but here it would put the label on the *wrong* side of the chip. Turning flip off clamps to the boundary instead, keeping the label on the side you authored.
+
+When a token genuinely needs the extreme — the lightest or darkest tone the scheme allows — reach for `'max'` / `'min'` rather than a large number or a contrast hack:
+
+```ts
+'card-floor':  { tone: 'min' }, // darkest tone (root, no base needed)
+'card-ceil':   { tone: 'max' }, // lightest tone
+```
+
+`'max'` resolves to the scheme's highest authored tone (100) and `'min'` to the lowest (0); neither needs a `base`. They flow through scheme mapping like any absolute tone, so under `mode: 'auto'` they invert in dark — `'max'` is the lightest tone in light mode and, after inversion, the *darkest* in dark. Use `mode: 'static'` if you want the same extreme pinned across every scheme, or `mode: 'fixed'` to keep it on the same end without inverting. Either way: no magic numbers, no contrast floor standing in for "push it all the way".
 
 These are inherited (no `inherit: false`), so each colored sibling theme automatically emits `<theme>-accent-disabled-surface` and `<theme>-accent-disabled-surface-text`. PRIMARY-style disabled buttons stay tinted with the active theme's hue (danger-tinted danger button, success-tinted success button), preserving brand identity even in the disabled state.
 
@@ -210,9 +220,9 @@ These are inherited (no `inherit: false`), so each colored sibling theme automat
 The `code-*` tokens use **absolute `hue` numbers** regardless of the seed. Each is `base: 'surface'` with `mode: 'auto'`, a per-token saturation, and a numeric contrast floor:
 
 ```ts
-'code-comment': { base: 'surface', hue: 280,        saturation: 0.1, lightness: '-1', contrast: [4.5, 7], inherit: false },
-'code-keyword': { base: 'surface', hue: 348,        saturation: 1,   lightness: '-1', contrast: [5, 7.5], inherit: false },
-'code-string':  { base: 'surface', hue: SUCCESS_HUE, saturation: 1, lightness: '-1', contrast: [4.5, 7], inherit: false },
+'code-comment': { base: 'surface', hue: 280,        saturation: 0.1, tone: '-1', contrast: [4.5, 7], inherit: false },
+'code-keyword': { base: 'surface', hue: 348,        saturation: 1,   tone: '-1', contrast: [5, 7.5], inherit: false },
+'code-string':  { base: 'surface', hue: SUCCESS_HUE, saturation: 1, tone: '-1', contrast: [4.5, 7], inherit: false },
 // …code-punctuation, code-number, code-function, code-attribute follow the same shape
 ```
 
@@ -220,15 +230,15 @@ The canonical pattern for "I want a color from a different hue family but the sa
 
 ## Loading-animation faces
 
-A 3-step ramp using *absolute* lightnesses with high saturation factors and tight numeric contrasts:
+A 3-step ramp using *absolute* tones with high saturation factors and tight numeric contrasts:
 
 ```ts
-'loading-face-1': { base: 'surface', lightness: 98, saturation: 0.3,  contrast: [1.04, 1.5], inherit: false },
-'loading-face-2': { base: 'surface', lightness: 91, saturation: 0.62, contrast: [1.24, 2.5], inherit: false },
-'loading-face-3': { base: 'surface', lightness: 79, saturation: 0.66, contrast: [1.75, 4],   inherit: false },
+'loading-face-1': { base: 'surface', tone: 98, saturation: 0.3,  contrast: [1.04, 1.5], inherit: false },
+'loading-face-2': { base: 'surface', tone: 91, saturation: 0.62, contrast: [1.24, 2.5], inherit: false },
+'loading-face-3': { base: 'surface', tone: 79, saturation: 0.66, contrast: [1.75, 4],   inherit: false },
 ```
 
-Combines absolute lightness positioning (so the ramp is deterministic in light mode) with a numeric contrast floor (so the ramp still reads in dark and HC). The HC contrast jumps significantly (`1.04 → 1.5`, `1.24 → 2.5`, `1.75 → 4`) so the animation stays perceivable for low-vision users.
+Combines absolute tone positioning (so the ramp is deterministic in light mode) with a numeric contrast floor (so the ramp still reads in dark and HC). The HC contrast jumps significantly (`1.04 → 1.5`, `1.24 → 2.5`, `1.75 → 4`) so the animation stays perceivable for low-vision users.
 
 ## Shadows
 
@@ -247,7 +257,7 @@ For HC, pass `intensity: [normal, hc]` (e.g. `[10, 20]`) to deepen shadows in hi
 ## Overlay (fixed opacity)
 
 ```ts
-overlay: { lightness: 10, opacity: 0.5, inherit: false },
+overlay: { tone: 10, opacity: 0.5, inherit: false },
 ```
 
 The shortcut for *one solid color with a fixed alpha* — no shadow algorithm, no mix. `opacity` on a regular color attaches an alpha component to every variant. Use it for backdrops, scrims, modal overlays. (Combining `opacity` with `contrast` is not recommended — perceived lightness becomes unpredictable when alpha is fixed; Glaze emits a `console.warn`.)
@@ -280,7 +290,7 @@ One shared `TINTED_SURFACE_OVERRIDE`, applied to every colored theme, with only
 
 ```ts
 const TINTED_SURFACE_OVERRIDE: ColorMap = {
-  surface: { lightness: 96, saturation: 0.8 },
+  surface: { tone: 96, saturation: 0.8 },
 };
 
 const primaryTheme = defaultTheme.extend({                       colors: TINTED_SURFACE_OVERRIDE });
@@ -313,21 +323,21 @@ The default theme is conventionally exported unprefixed (its tokens land as `#su
 
 ## High-contrast strategy
 
-Glaze's high-contrast mode is opt-in per token: anywhere `lightness`, `contrast`, `intensity`, or `value` accepts an HC pair, you can pass `[normal, hc]` to tighten the HC variant. The heuristic is to pair anything that's already contrast-driven:
+Glaze's high-contrast mode is opt-in per token: anywhere `tone`, `contrast`, `intensity`, or `value` accepts an HC pair, you can pass `[normal, hc]` to tighten the HC variant. The heuristic is to pair anything that's already contrast-driven:
 
 - Text-against-surface contrasts (`[9, 11]`, `[4.5, 5.5]`, `[6.4, 10]`).
 - The accent surface ladder (`[4.5, 7]` → `[5.2, 8]` → `[6, 8.5]`).
 - The loading ramp's contrasts.
 - Shadow `intensity` (e.g. `intensity: [10, 20]`).
-- `border` lightness (e.g. `lightness: ['-10', '-20']`).
+- `border` tone (e.g. `tone: ['-10', '-20']`).
 
-In HC the lightness window is **bypassed entirely** — light HC and dark HC operate on the full `[0, 100]` range. That's why edge-anchored absolute lightnesses like `surface-text: { lightness: 2 }` blow out to L=2 in light HC and L≈99 in dark HC, exactly what you want for maximum contrast.
+In HC the tone window is **bypassed entirely** — light HC and dark HC operate on the full `[0, 100]` range. That's why edge-anchored absolute tones like `surface-text: { tone: 2 }` reach close to black in light HC and close to white in dark HC, exactly what you want for maximum contrast.
 
 ## Closing checklist
 
 Before shipping a palette, verify:
 
-- [ ] Every text token has an explicit `contrast` *or* an edge-anchored absolute `lightness`.
+- [ ] Every text token has an explicit `contrast` *or* an edge-anchored absolute `tone`.
 - [ ] Every accent surface uses `mode: 'fixed'` + numeric `contrast` (not preset `'AA'` / `'AAA'`).
 - [ ] Every brand foreground (`accent-text*`, `accent-icon`) is anchored to `surface`, **not** to `accent-surface`.
 - [ ] Every `inherit: false` is intentional — colored sibling themes only carry the tokens they actually need.

package/docs/migration.md

@@ -4,6 +4,76 @@ How to plug a Glaze palette into an existing app — exporting tokens in the rig
 
 If you're starting from scratch, see [methodology.md](methodology.md) first — that's about *designing* the palette. This doc is about *consuming* it.
 
+## Upgrading to the tone model (`lightness` → `tone`)
+
+Glaze replaced OKHSL **lightness** with a contrast-uniform **tone** axis (OKHST). The Möbius dark-mode curve is gone — dark mode is now a single tone inversion remapped into a per-mode window. See [`docs/okhst.md`](okhst.md) for the model. This is a breaking change; here's what to update.
+
+### Rename the authoring axis
+
+`lightness` is gone. Replace it with `tone` everywhere:
+
+```ts
+// before
+theme.colors({ surface: { lightness: 97 }, text: { base: 'surface', lightness: '-52' } });
+// after
+theme.colors({ surface: { tone: 97 }, text: { base: 'surface', tone: '-52' } });
+```
+
+The same applies to `glaze.color({ ..., lightness })` (structured form) → `tone`, and the `{ h, s, l }` value object is unchanged (still OKHSL) — but you can now also pass `{ h, s, t }` (OKHST) or an `okhst(H S% T%)` string.
+
+Tone is **0–100** like the old lightness, but the *scale is contrast-uniform*, not perceptual-lightness-uniform. Numeric values won't land at the same OKHSL lightness — equal tone steps now give equal WCAG contrast. Re-eyeball absolute values (especially mid-range ones); relative deltas and contrast-floored tokens usually need no change because they were already contrast-driven.
+
+### Config window shape
+
+The lightness windows became tone windows, and `darkCurve` was removed (no curve to tune). The `[lo, hi]` tuple form carries over directly:
+
+```ts
+// before
+glaze.configure({ lightLightness: [10, 100], darkLightness: [15, 95], darkCurve: 0.5 });
+// after
+glaze.configure({
+  lightTone: [10, 100],
+  darkTone: [15, 95],
+  // darkCurve removed; saturationTaper: 0.15 is the new gentle-extremes knob
+});
+```
+
+`lightLightness`/`darkLightness` → `lightTone`/`darkTone`. The window value is `[lo, hi]` (reference eps — the common form), `{ lo, hi, eps }` (advanced: explicit render curvature), or `false` to disable clamping. `false` removes the *boundaries* (full `[0, 100]` range), not the contrast-uniform tone curve. Per-token `glaze.color(value, config)` overrides use the same shape.
+
+### The `contrast` prop now selects a metric
+
+A bare number or preset is still **WCAG** and needs no change. To use APCA or split a pair across the metric, use the object form:
+
+```ts
+contrast: 4.5            // unchanged — WCAG 4.5
+contrast: { wcag: 6 }    // explicit WCAG
+contrast: { apca: 60 }   // APCA Lc floor
+contrast: { wcag: [4.5, 7] } // pair inside the metric
+```
+
+### Forcing extremes: `'max'` / `'min'`
+
+For colors that should sit at the scheme's tone extreme (pure-white knockouts, near-black scrims, deliberately faint disabled chips), reach for `tone: 'max'` / `tone: 'min'` instead of a large absolute number or a low contrast floor standing in for "push it all the way". `'max'` resolves to author tone 100, `'min'` to 0, and both flow through scheme mapping (so they invert in dark under `mode: 'auto'`). No `base` required.
+
+```ts
+// before — low contrast as a proxy for "stay near the surface"
+'disabled-text': { base: 'chip', tone: '+1', contrast: 1.51, mode: 'fixed' }
+// after — say it directly with tone
+'disabled-text': { base: 'chip', tone: '+18', saturation: 0.4, flip: false }
+```
+
+### The `flip` prop
+
+Relative `tone` offsets that overshoot `[0, 100]` now **mirror to the other side of the base by default** (controlled by the new per-color `flip`, which inherits the global `autoFlip`, default `true`). Previously such offsets always clamped to the boundary. If you relied on clamping — e.g. `tone: '+48'` to stack a color up to 100 — set `flip: false` on that color (or `glaze.configure({ autoFlip: false })` globally) to restore the clamping behavior. `flip` also governs the contrast solver's direction (its previous sole role).
+
+### Resolved variants store tone
+
+`ResolvedColorVariant` now exposes `t` (tone, 0–1) instead of `l`. If you read resolved internals, convert with `variantToOkhsl(variant).l`. Token/CSS/JSON output is unchanged — Glaze still emits `okhsl(...)` / `rgb(...)` etc. (`okhst` is input-only and is never emitted).
+
+### Export snapshots
+
+`theme.export()` / `color.export()` snapshots now carry `lightTone` / `darkTone` window objects (not `lightLightness` / `darkLightness`). Old exported JSON with the legacy keys will need its `config` block rewritten before `glaze.from()` / `glaze.colorFrom()`.
+
 ## Choosing an export
 
 Glaze emits the same resolved colors in four shapes. Pick one based on your renderer.
@@ -176,15 +246,15 @@ Walk your current color system and bucket every token into one of these categori
 - **Shadows / overlays** — elevation, scrims.
 - **One-off colors** — syntax highlighting, charts, illustrations.
 
-Each bucket maps cleanly to one of the patterns in [methodology.md](methodology.md). The bucket determines the *shape* of the Glaze definition (root vs dependent, `mode: 'auto'` vs `'fixed'`, contrast-floor vs absolute lightness), not the value.
+Each bucket maps cleanly to one of the patterns in [methodology.md](methodology.md). The bucket determines the *shape* of the Glaze definition (root vs dependent, `mode: 'auto'` vs `'fixed'`, contrast-floor vs absolute tone), not the value.
 
 ### 2. Reproduce the existing values
 
-Pick a Glaze definition shape that lands the new color *close to* the legacy hex in light mode. The methodology doc explains the shape per bucket; the API doc covers the levers (`lightness`, `saturation`, `contrast`, `mode`, `hue`).
+Pick a Glaze definition shape that lands the new color *close to* the legacy hex in light mode. The methodology doc explains the shape per bucket; the API doc covers the levers (`tone`, `saturation`, `contrast`, `mode`, `hue`).
 
 Two tactics that make matching easier:
 
-- **Anchor strong text at the edge** instead of solving for `'AAA'`. The contrast solver stops at the floor (cr=7), which usually leaves text noticeably softer than a legacy hex like `#1a1a1a`. An absolute `lightness: 2` (or wherever the legacy token sits in OKHSL) preserves the look.
+- **Anchor strong text at the edge** instead of solving for `'AAA'`. The contrast solver stops at the floor (cr=7), which usually leaves text noticeably softer than a legacy hex like `#1a1a1a`. An absolute `tone: 2` (or wherever the legacy token sits) preserves the look.
 - **Use numeric `contrast` ratios** for soft / accent / disabled tokens. Presets give you the WCAG floor and nothing more — for matching a designed palette you usually want a specific perceived weight, not the floor.
 
 ### 3. Keep the old token names
@@ -196,9 +266,9 @@ Use a custom `prefix` map (and theme aliases if needed) so the names your compon
 // New: define them in Glaze, map the prefix so they emit unchanged.
 
 defaultTheme.colors({
-  dark:      { base: 'surface', lightness: 2,  saturation: 0.475 },
-  'dark-02': { base: 'surface', lightness: '-1', saturation: 0.375, contrast: [9, 11]   },
-  'dark-03': { base: 'surface', lightness: '-1', saturation: 0.24,  contrast: [4.5, 5.5] },
+  dark:      { base: 'surface', tone: 2,  saturation: 0.475 },
+  'dark-02': { base: 'surface', tone: '-1', saturation: 0.375, contrast: [9, 11]   },
+  'dark-03': { base: 'surface', tone: '-1', saturation: 0.24,  contrast: [4.5, 5.5] },
 });
 
 palette.tasty({ prefix: { default: '' } });
@@ -211,8 +281,8 @@ Once consumers are off the legacy names, rename the Glaze tokens to match your c
 
 Glaze gives you light/dark/HC for free, but only the light mode is matched against the legacy palette. Before promoting the migration:
 
-- Spot-check every surface, text, accent, and disabled pair in dark mode. The Möbius dark inversion plus per-color `mode` choices may produce results that *look right* in light but feel off in dark (typical fix: switch a brand color to `mode: 'fixed'`, or anchor a foreground to `surface` instead of the brand fill — see [methodology.md](methodology.md)).
-- If the legacy system had no high-contrast mode, audit the HC variants Glaze emits. Anywhere the resolved cr is too low or the color blows out, add an HC pair (`lightness: ['-7', '-20']`, `contrast: [4.5, 7]`, etc.).
+- Spot-check every surface, text, accent, and disabled pair in dark mode. The tone inversion plus per-color `mode` choices may produce results that *look right* in light but feel off in dark (typical fix: switch a brand color to `mode: 'fixed'`, or anchor a foreground to `surface` instead of the brand fill — see [methodology.md](methodology.md)).
+- If the legacy system had no high-contrast mode, audit the HC variants Glaze emits. Anywhere the resolved cr is too low or the color blows out, add an HC pair (`tone: ['-7', '-20']`, `contrast: [4.5, 7]`, etc.).
 - Run real screens, not just the token grid. The interaction of multiple Glaze tokens against each other (text on chip, hover bg vs. fill, disabled label on disabled chip) is where mismatches show up.
 
 ### 5. Trim what `extend()` doesn't need
@@ -224,9 +294,10 @@ After migration, mark every default-only token (borders, shadows, disabled chip,
 | Symptom | Cause | Fix |
 |---|---|---|
 | Disabled state stops looking disabled in dark mode. | Alpha-tinted overlay on `surface-text` (which inverts), giving asymmetric perceived contrast. | Replace with a `mode: 'auto'` color anchored to `surface` with a numeric `contrast` (see [methodology.md → Disabled chip](methodology.md#disabled-chip-contrast-driven-for-scheme-symmetry)). |
-| Brand color flips to its complement in dark mode. | Default `mode: 'auto'` runs the Möbius inversion. | Set `mode: 'fixed'` so the lightness is mapped (not inverted). |
+| Brand color flips to its complement in dark mode. | Default `mode: 'auto'` inverts the tone. | Set `mode: 'fixed'` so the tone is remapped (not inverted). |
 | Brand text washes out against the dark surface. | Foreground was anchored to `accent-surface` (the brand fill), so contrast was only enforced against that fill — not the actual surface. | Anchor `accent-text` etc. to `surface` with `mode: 'auto'`. |
-| Tokens look right in light, broken in HC. | The HC pass bypasses the lightness window — solver runs over the full `[0, 100]` range. | Add explicit `[normal, hc]` pairs to `lightness` / `contrast` for the affected tokens. |
+| Tokens look right in light, broken in HC. | The HC pass bypasses the tone window — solver runs over the full `[0, 100]` range. | Add explicit `[normal, hc]` pairs to `tone` / `contrast` for the affected tokens. |
+| A relative `tone` like `'+48'` lands on the *wrong* (darker) side of its base. | Overshooting offsets now mirror to the other side of the base by default (`flip` inherits `autoFlip`). | Set `flip: false` on the color to clamp to the boundary instead, or use `tone: 'max'`/`'min'` to force the extreme. |
 | `palette.tokens()` emits unexpected unprefixed names. | A `primary` was set on the palette (or per-call) and is duplicating the theme's tokens without prefix. | Pass `primary: false` to disable for that export, or rename `glaze.palette(themes, { primary })`. |
 | `console.warn: token "foo" collides with theme "bar"`. | Two themes resolved to the same output key under your prefix config. | Adjust the prefix map so each token is unique, or accept the first-write-wins behavior. |
 | `console.warn: color "X" cannot meet contrast`. | The requested contrast target is physically unreachable for the color's hue/saturation against its base. | Lower the floor, change the base, or accept the closest passing variant. Use the `name` override on standalone colors to make the warning identifiable. |

package/docs/okhst.md

@@ -0,0 +1,224 @@
+# OKHST — the contrast-uniform tone space
+
+This is the canonical specification for the color model Glaze uses internally
+and accepts as input. It is the source of truth that [api.md](api.md),
+[methodology.md](methodology.md), and [migration.md](migration.md) reference.
+
+## What OKHST is
+
+**OKHST is OKHSL with its lightness axis replaced by a contrast-uniform _tone_
+axis.** It shares OKHSL's hue (`h`, 0–360) and saturation (`s`, 0–1) verbatim;
+only the third coordinate changes:
+
+| Space | Coords | Third axis |
+|---|---|---|
+| OKHSL | `h, s, l` | `l` — perceptual lightness (toe-adjusted OKLab L) |
+| OKHST | `h, s, t` | `t` — tone: a normalized log of luminance |
+
+OKHST exists for one reason: in OKHSL, _equal lightness steps_ are perceptually
+even but produce _uneven contrast_ (the ratio between adjacent steps drifts).
+OKHST's tone axis is shaped so that _equal tone steps_ produce _even WCAG
+contrast_ between steps. Authoring ramps in tone gives you contrast-even ladders
+for free, and dark-mode inversion becomes a single subtraction (`100 - t`)
+instead of a fitted curve.
+
+OKHST is an **input space only**. It is parseable as an `okhst(H S% T%)` string
+and an `{ h, s, t }` object, but it is **never emitted** — there is no CSS
+`okhst()` function, so output formats stay `okhsl | rgb | hsl | oklch`.
+
+## The tone transfer
+
+For a gray (s = 0) at OKHSL lightness `l`, luminance is closed-form through the
+OKHSL toe and OKLab cube:
+
+```
+Y = toeInv(l) ** 3          // OKLab L = toeInv(l); luminance ≈ L³
+l = toe(cbrt(Y))            // exact inverse
+```
+
+(`toe` / `toeInv` already exist in [okhsl-color-math.ts](../src/okhsl-color-math.ts).)
+
+Tone is a normalized natural-log of `Y`, offset by a small `eps`:
+
+```
+toTone(Y, eps)   = (ln(Y + eps) - ln(eps)) / (ln(1 + eps) - ln(eps)) * 100
+fromTone(T, eps) = exp( (T / 100) * (ln(1 + eps) - ln(eps)) + ln(eps) ) - eps
+```
+
+`toTone` and `fromTone` are exact analytic inverses, so a round-trip is lossless
+to ~1e-15. `toTone(0) = 0` and `toTone(1) = 100` for any `eps`, so tone is always
+a clean 0–100 scale.
+
+### Why `eps ≈ 0.05` makes tone contrast-uniform
+
+WCAG 2 contrast is `(Y_hi + 0.05) / (Y_lo + 0.05)`. Pick `eps = 0.05` and the
+tone transfer becomes a normalized `ln(Y + 0.05)`. Two colors that differ by a
+fixed tone delta `ΔT` then differ by a fixed _ratio_ of `(Y + 0.05)` — i.e. a
+fixed WCAG contrast ratio — regardless of where on the scale they sit:
+
+```
+cr(T2, T1) = (Y2 + 0.05) / (Y1 + 0.05)
+           = exp( (T2 - T1)/100 * (ln(1.05) - ln(0.05)) )
+```
+
+Empirically (gray, `eps = 0.05`), each `+10` tone multiplies contrast-vs-black by
+a near-constant factor:
+
+| tone | cr vs black |
+|---|---|
+| 10 | 1.36 |
+| 30 | 2.49 |
+| 50 | 4.58 |
+| 70 | 8.43 |
+| 90 | 15.49 |
+| 100 | 21.00 |
+
+So a tone ramp `[20, 40, 60, 80]` has _constant_ contrast between adjacent
+stops. That is the whole point.
+
+## Core invariant: `T → L` is independent of `H` and `S`
+
+`okhstToOkhsl({ h, s, t })` passes `h` and `s` through unchanged and sets
+`l = fromTone(t)`. `fromTone` is a pure function of `(t, eps)`; OKHSL's
+`l → OKLab L = toeInv(l)` map has no hue/saturation term — `h`/`s` enter only
+the chroma/cusp math. Therefore:
+
+> **A given tone yields the same OKHSL lightness for every hue and saturation.**
+
+OKHST inherits OKHSL's gamut and reversibility exactly: every `(h, s, t)` is
+realizable and round-trips.
+
+**This uniformity is in lightness, not luminance.** Equal tone gives equal
+OKHSL `L` for all `h`/`s`, but equal _WCAG/APCA contrast_ only for grays.
+A saturated yellow and a saturated blue at the same tone share a lightness yet
+differ in real luminance `Y`. This chromatic drift is the one honest
+approximation in the design — see [§10 Verification](#verification-apca--wcag-drift).
+The single deliberate exception to the invariant is the optional `contrast`
+solver, which shifts a stop's tone per `h`/`s` to meet a luminance-based floor.
+
+## Reference eps vs per-mode eps
+
+Two distinct roles, kept separate on purpose:
+
+- **Reference eps (`0.05`, fixed).** Defines the OKHST _color space_ and the
+  canonical stored tone. `okhst()` input, `{ h, s, t }` input, the internal
+  `ResolvedColorVariant.t`, relative `tone` offsets, and the contrast solver all
+  use the reference eps. This is what makes OKHST stable and scheme-independent.
+- **Per-mode eps (`lightTone.eps`, `darkTone.eps`).** A _rendering_ curvature
+  knob per scheme. It only affects how authored tone is mapped through a scheme
+  window before the result is stored. Defaults to the reference value, so by
+  default the two coincide and there is nothing to reconcile.
+
+When a mode's eps differs from the reference, `mapToneForScheme` maps using the
+mode eps to land a final OKHSL `l`, then stores `toTone(l, REF_EPS)` so offsets
+and contrast stay comparable across schemes.
+
+## Scheme pipeline (no Möbius)
+
+```
+author tone T (0–100)
+  → mode branch:
+      auto + dark : invert  T' = 100 - T
+      fixed / light: keep    T' = T
+      static      : identity, skip window
+  → window remap: T' into the scheme window [lo, hi] (tone units)
+  → render curvature (mode eps) → OKHSL l
+  → store canonical tone t = toTone(l, REF_EPS)        // variant {h, s, t, alpha}
+  → (edge only) fromTone(t, REF_EPS) → l → sRGB / luminance
+  optional: contrast floor (wcag/apca) searches in tone, overriding t
+```
+
+High-contrast is **not** a separate curve. It reuses the same math with the
+window forced to the full range `[0, 100]`, keeping the mode's eps. There is no
+`darkCurve` and no separate HC curve.
+
+`fixed` mode remaps into the window but does **not** invert (brand colors stay
+recognizable). `static` skips the window entirely (identity) so the same tone
+renders in every scheme.
+
+## Calibrated constants (defaults)
+
+Chosen as clean defaults that keep light mode close to the previous pipeline
+while the axis stays contrast-uniform (the old Möbius curve was intentionally
+non-uniform, which is what we are replacing). The light floor sits at `lo = 10`
+and the dark floor at `lo = 15`, so neither scheme bottoms out darker than the
+legacy pipeline produced. `eps` is pinned to the reference value `0.05` so the
+tone axis stays WCAG-uniform.
+
+| Config | lo | hi | eps |
+|---|---|---|---|
+| `lightTone` | 10 | 100 | 0.05 |
+| `darkTone` | 15 | 95 | 0.05 |
+
+A window is authored as `[lo, hi]` (reference eps — the common form),
+`{ lo, hi, eps }` (advanced: explicit per-mode render curvature), or `false`
+to disable clamping. `false` is the full range `[0, 100]` at the reference eps —
+it removes the **boundaries**, not the tone curve.
+
+Other defaults: `darkDesaturation = 0.1` (unchanged), `saturationTaper = 0.15`,
+`autoFlip = true`.
+
+Reference: `REF_EPS = 0.05`.
+
+## Saturation taper
+
+At the tone extremes the in-gamut chroma collapses, so high saturation near
+white/black reads as noise. `saturationEnvelope(s, toneFinal, taper)` applies a
+smoothstep rolloff over the outer `taper` fraction of the tone range (default
+`0.15` → outer 15% on each end). `taper = 0` disables it. It is conservative by
+design: mid-tones are untouched, so existing ramps barely shift.
+
+## Contrast metric (unified)
+
+`contrast` is a single prop with a pluggable metric:
+
+```ts
+type ContrastSpec =
+  | number                 // bare WCAG ratio
+  | ContrastPreset         // 'AA' | 'AAA' | 'AA-large' | 'AAA-large' (WCAG)
+  | { wcag: HCPair<number | ContrastPreset> }
+  | { apca: HCPair<number> };
+
+contrast?: HCPair<ContrastSpec>;
+```
+
+A bare number or preset means WCAG. The `[normal, highContrast]` pair may live at
+the outer level (`[4.5, 7]`, `[{ wcag: 4.5 }, { wcag: 7 }]`) **or** inside the
+metric (`{ wcag: [4.5, 7] }`, `{ apca: [45, 60] }`). `resolveContrastForMode`
+peels the outer pair by mode, then the inner metric pair by the same mode, then
+resolves presets, returning `{ metric, target }`.
+
+The solver searches in **tone** (contrast-uniform → fast convergence and a
+closed-form WCAG seed). For WCAG, the seed is the tone whose gray luminance hits
+`Y = R·(Y_base + 0.05) − 0.05`; chromatic drift is then refined by binary search.
+For APCA, it binary-searches tone against the APCA Lc target.
+
+### APCA
+
+`apcaContrast(yText, yBg)` implements SAPC/APCA Lc (soft-clamp of low luminances
+plus the polarity exponents for normal vs reverse contrast), returning a signed
+Lc whose magnitude the solver compares against the target. Its inputs are APCA
+*screen* luminances `Ys = 0.2126·R^2.4 + 0.7152·G^2.4 + 0.0722·B^2.4` over the
+gamma-encoded channels (`apcaLuminanceFromLinearRgb`), **not** WCAG relative
+luminance — the soft-clamp constants are calibrated against `Ys`, so the solver
+feeds it the matching basis. This is a faithful-but-simplified APCA (it omits
+the spatial/font-size lookup that maps Lc to a usable text size).
+
+## Verification (APCA / WCAG drift)
+
+Because chromatic swatches inherit gray's tone-derived lightness but drift in
+real luminance, a color resolved with a `base` + `contrast` may land slightly
+under the contrast its tone implies. After resolving such a color, Glaze
+computes the actual WCAG ratio and APCA Lc of the chromatic result against its
+base and emits a deduped `console.warn` when it drifts below the gray-tone
+expectation. This is advisory: it surfaces the one approximation rather than
+hiding it. The dedupe cache is the existing 256-entry cache in
+[warnings.ts](../src/warnings.ts).
+
+## Migration from `lightness`
+
+`lightness` (OKHSL `l`, 0–100) is replaced by `tone` (0–100). They are **not**
+the same number — tone is the contrast-uniform reparameterization. To convert an
+old absolute `lightness: L` to the equivalent `tone`, use
+`toTone(L/100, 0.05)`. See [migration.md](migration.md) for the full guide and
+a conversion table.