@tenphi/glaze 0.0.0-snapshot.d38eee5 → 0.0.0-snapshot.d79cac8

package/docs/methodology.md

@@ -1,346 +0,0 @@
-# Methodology
-
-A practical guide for designing a real, production-grade Glaze palette. Recipe-ordered: the sections follow the same sequence you'd actually build a palette in, and each one ties the choice back to a Glaze behavior.
-
-## The mental model
-
-A Glaze palette is a **default neutral theme** plus a small fan of **colored sibling themes** (`success`, `danger`, `warning`, `note`, …) created via `extend()`. Most colors live in the default theme as neutrals; brand-tinted colors come from `extend()` swapping the hue.
-
-The default theme is what most components consume — its tokens are emitted unprefixed (`#surface`, `#border`). Colored themes are scoped to status surfaces and accent variants, emitted with a theme-name prefix (`#success-surface`, `#danger-accent-surface`).
-
-You design the default theme once, and `extend()` propagates that design across every status hue.
-
-Every color definition has an **`inherit`** flag (default: `true`) controlling whether it flows into child themes via `extend()`. Set `inherit: false` to scope a color to its parent theme only — this is how sibling themes stay lean, carrying only the tokens they actually need.
-
-## Hue / saturation seeds
-
-Declare hues as named constants up top, plus a single shared seed saturation:
-
-```ts
-const PURPLE_HUE  = 280.3;
-const SUCCESS_HUE = 156.9;
-const DANGER_HUE  = 23.1;
-const WARNING_HUE = 84.3;
-const NOTE_HUE    = 302.3;
-
-const SEED_SATURATION = 80;
-```
-
-Hues are design tokens too — keeping them named in one place beats burying numbers in `extend()` calls. The shared `SEED_SATURATION` keeps every status theme on the same saturation budget; per-color `saturation` factors below are 0–1 *of this seed*, not absolute.
-
-## Global `glaze.configure()`
-
-Configure state aliases and output modes once at module load:
-
-```ts
-glaze.configure({
-  states: { dark: '@dark', highContrast: '@hc' },
-  modes:  { dark: true,    highContrast: true },
-});
-```
-
-Match the state alias names to whatever your app wires into the global predefined states (`@dark` / `@hc` is what Tasty expects). Setting `modes.highContrast: true` makes every export emit four variants — HC tokens are then available globally without per-call overrides.
-
-## Naming conventions
-
-A tight, predictable vocabulary that the rest of the doc relies on:
-
-| Pattern | Tokens |
-|---|---|
-| Surface ladder | `surface`, `surface-2`, `surface-3` |
-| Text on surface (decreasing prominence) | `<surface>-text`, `<surface>-text-soft`, `<surface>-text-soft-2` |
-| Misc neutral primitives | `border`, `placeholder`, `focus`, `disabled` |
-| Neutral disabled chip | `disabled-surface`, `disabled-surface-text` |
-| Fixed-mode dark surface | `surface-inverse` |
-| Brand fills | `accent-surface`, `accent-surface-2`, `accent-surface-3`, `accent-surface-hover` |
-| Brand fill anchor | `accent-surface-text` (the fixed white token everything anchors to) |
-| Brand foregrounds on neutrals | `accent-text`, `accent-text-soft`, `accent-icon` |
-| Brand-tinted disabled | `accent-disabled-surface`, `accent-disabled-surface-text` |
-| Code syntax highlighting | `code-comment`, `code-keyword`, `code-string`, `code-number`, … |
-| Loading animation | `loading-face-1`, `loading-face-2`, `loading-face-3` |
-| Shadows | `shadow-sm`, `shadow-md`, `shadow-lg` |
-| Backdrop | `overlay` |
-
-**Rule of thumb:** *purpose-name first, variant suffix last* (`-2`, `-text`, `-soft`, `-hover`, `-disabled`).
-
-## Surfaces (root colors)
-
-`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:     { 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 tone drops, so the ladder reads as one consistent surface family.
-
-`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 `tone` near the edge of the window**; soft variants use a **directional relative hint plus a numeric `contrast`**.
-
-```ts
-'surface-text': {
-  base: 'surface', tone: 2, saturation: 0.475,
-},
-'surface-text-soft': {
-  base: 'surface', tone: '-1', saturation: 0.375,
-  contrast: [9, 11], inherit: false,
-},
-'surface-text-soft-2': {
-  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 `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 `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 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" tone — all default-only:
-
-```ts
-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 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)
-
-The disabled chip + label pair uses `mode: 'auto'` and **explicit numeric contrast** against `surface`, not preset `'AA'` / `'AAA'`:
-
-```ts
-'disabled-surface': {
-  base: 'surface', tone: '-1', saturation: 0.2,
-  contrast: [1.5, 2], inherit: false,
-},
-'disabled-surface-text': {
-  base: 'disabled-surface', tone: '+1', saturation: 0.3,
-  contrast: 3, inherit: false,
-},
-```
-
-Each token anchors to its immediate parent surface — `*-surface` contrasts against the root `surface`, while `*-surface-text` contrasts against its own chip (`disabled-surface`). This keeps the disabled state self-contained and resolves to consistent ratios in light, dark, and HC (chip ≈ 1.5–2× vs surface, label ≈ 3× on chip). An alpha-tinted overlay would have asymmetric behavior — composited alpha against a near-white light surface produces a much weaker chip than the same overlay against a near-dark dark surface, and the disabled state would stop *looking* disabled in one of the schemes.
-
-The general rule: when a color needs to *feel the same across schemes*, anchor it with `mode: 'auto'` + a numeric contrast against a surface, not with a preset.
-
-## `surface-inverse` (the fixed-mode escape hatch)
-
-```ts
-'surface-inverse': {
-  tone: 12, saturation: 0.475, mode: 'fixed', inherit: false,
-},
-```
-
-`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.
-
-This is the canonical "I want this color to stay recognizable" pattern. The other `mode: 'fixed'` use is the entire accent system below.
-
-## 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 tone offset and a numeric contrast under `mode: 'fixed'`:
-
-```ts
-'accent-surface-text': { tone: 100, 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 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.
-
-## Adaptive accent foregrounds
-
-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', 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 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. 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', tone: '+3', saturation: 0.5,
-},
-'accent-disabled-surface-text': {
-  base: 'accent-disabled-surface', tone: '+18', saturation: 0.4,
-  flip: false,
-},
-```
-
-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.
-
-## Per-color hue overrides (code highlighting)
-
-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, 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
-```
-
-The canonical pattern for "I want a color from a different hue family but the same adaptive behavior". Absolute `hue` overrides the theme seed for a single color; everything else (contrast against `surface`, dark adaptation, HC tightening) still works. `inherit: false` because syntax highlighting is a default-only concern.
-
-## Loading-animation faces
-
-A 3-step ramp using *absolute* tones with high saturation factors and tight numeric contrasts:
-
-```ts
-'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 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
-
-Three sizes, all sharing `bg: 'surface'` and `fg: 'surface-text'`, varying only `intensity`:
-
-```ts
-'shadow-sm': { type: 'shadow', bg: 'surface', fg: 'surface-text', intensity: 5,  inherit: false },
-'shadow-md': { type: 'shadow', bg: 'surface', fg: 'surface-text', intensity: 10, inherit: false },
-'shadow-lg': { type: 'shadow', bg: 'surface', fg: 'surface-text', intensity: 15, inherit: false },
-```
-
-Including `fg` matters: shadow strength scales with `|l_bg − l_fg|`, so anchoring `fg` to `surface-text` (which is anchored at the edge of the window) makes shadows *automatically deeper* in dark mode where the bg/fg gap is larger. All shadows are `inherit: false` — there's only one shadow system for the whole UI, and colored sibling themes don't carry their own.
-
-For HC, pass `intensity: [normal, hc]` (e.g. `[10, 20]`) to deepen shadows in high-contrast mode. The full algorithm and tuning knobs are in [api.md → Shadows](api.md#shadows).
-
-## Overlay (fixed opacity)
-
-```ts
-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`.)
-
-## Mixes for hover / tint
-
-Reach for mix tokens when you want one color to "tint through" another:
-
-```ts
-hover: {
-  type: 'mix', base: 'surface', target: 'accent-surface',
-  value: 8, blend: 'transparent',
-},
-// hover → accent-surface with alpha = 0.08
-
-tint: {
-  type: 'mix', base: 'surface', target: 'accent-surface',
-  value: 20,
-},
-```
-
-- **Transparent mix** — *the target color with controlled alpha*. Useful for hover overlays.
-- **Opaque mix** — solid blend of two colors. Good for subtle tints.
-
-Choose `space: 'okhsl'` (default) for design tokens — perceptually uniform, consistent with the rest of Glaze. Choose `space: 'srgb'` to match what the browser would render with a plain CSS overlay. Mix colors support the same `contrast` prop as regular colors; the solver adjusts the mix ratio (opaque) or opacity (transparent) to meet the target.
-
-## Colored sibling themes via `extend()`
-
-One shared `TINTED_SURFACE_OVERRIDE`, applied to every colored theme, with only the `hue` changing per status:
-
-```ts
-const TINTED_SURFACE_OVERRIDE: ColorMap = {
-  surface: { tone: 96, saturation: 0.8 },
-};
-
-const primaryTheme = defaultTheme.extend({                       colors: TINTED_SURFACE_OVERRIDE });
-const successTheme = defaultTheme.extend({ hue: SUCCESS_HUE,     colors: TINTED_SURFACE_OVERRIDE });
-const dangerTheme  = defaultTheme.extend({ hue: DANGER_HUE,      colors: TINTED_SURFACE_OVERRIDE });
-const warningTheme = defaultTheme.extend({ hue: WARNING_HUE,     colors: TINTED_SURFACE_OVERRIDE });
-const noteTheme    = defaultTheme.extend({ hue: NOTE_HUE,        colors: TINTED_SURFACE_OVERRIDE });
-```
-
-Colored themes need a visibly tinted surface for status banners — saturation jumps from the neutral `0.11` (default theme) to `0.8`. The `inherit: false` discipline pays off here: because most neutrals (`surface-2`, `surface-3`, `border`, `placeholder`, `disabled-*`, `code-*`, `loading-*`, `shadow-*`) are flagged default-only, each colored theme inherits *only* the accent + tinted surface chain and emits a small, focused token set.
-
-`primaryTheme` keeps the default hue but gets the tinted surface — useful for places that want a brand-tinted banner without semantic status meaning.
-
-## Palette composition
-
-Compose all themes into a palette so they can be exported as one token set:
-
-```ts
-const palette = glaze.palette({
-  default: defaultTheme,
-  primary: primaryTheme,
-  success: successTheme,
-  danger:  dangerTheme,
-  warning: warningTheme,
-  note:    noteTheme,
-});
-```
-
-The default theme is conventionally exported unprefixed (its tokens land as `#surface`, `#border`); colored themes are prefixed with their name. See [migration.md](migration.md) for the prefix map shape, alias patterns, and how to wire the resulting tokens into Tasty / CSS / framework-agnostic JSON.
-
-## High-contrast strategy
-
-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` tone (e.g. `tone: ['-10', '-20']`).
-
-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 `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.
-- [ ] HC pairs are present on every contrast-driven token, not just the strong ones.
-- [ ] Shadow `fg` is set when you want shadows to deepen in dark mode.
-- [ ] `glaze.configure({ states, modes })` matches the global predefined states wired in your app's root.

package/docs/okhst.md

@@ -1,259 +0,0 @@
-# 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),
-`autoFlip = true`.
-
-Reference: `REF_EPS = 0.05`.
-
-## 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 | ApcaPreset> };
-
-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] }`, `{ apca: ['content', 'body'] }`). `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).
-
-#### Polarity (roles)
-
-APCA is **asymmetric**: `|apcaContrast(a, b)| ≠ |apcaContrast(b, a)|`, because
-the normal-polarity exponents (dark text on light bg) differ from the
-reverse-polarity exponents (light text on dark bg). Glaze picks the argument
-order from each color's semantic **role** against its base:
-
-| Role      | Polarity | Argument order                 | Aliases (name inference)                    |
-| --------- | -------- | ------------------------------ | ------------------------------------------- |
-| `text`    | `fg`     | `apcaContrast(candidate, base)`| `text`, `fg`, `foreground`, `content`, `ink`, `label`, `stroke` |
-| `border`  | `fg`     | `apcaContrast(candidate, base)`| `border`, `divider`, `outline`, `separator`, `hairline`, `rule` |
-| `surface` | `bg`     | `apcaContrast(base, candidate)`| `surface`, `bg`, `background`, `fill`, `canvas`, `paper`, `layer` |
-
-A color's role is resolved per the chain: explicit `role` → inferred from the
-color name (last recognized token wins, so `button-text` → `text`,
-`input-bg` → `surface`) → the opposite of the base's role → `'text'` (foreground)
-default. Name inference is on by default (`config.inferRole: true`) and can be
-disabled. WCAG is symmetric, so role never changes WCAG results — it only fixes
-APCA argument order.
-
-#### APCA presets
-
-APCA targets may be a raw Lc number or a named preset (APCA Bronze Simple Mode
-conformance levels), independent of role:
-
-```ts
-type ApcaPreset = 'preferred' | 'body' | 'content' | 'large' | 'non-text' | 'min';
-```
-
-| Preset        | Lc  | Use case                                             |
-| ------------- | --- | ---------------------------------------------------- |
-| `'preferred'` | 90  | Preferred body / column text                         |
-| `'body'`      | 75  | Minimum body / column text                           |
-| `'content'`   | 60  | Readable non-body content (~WCAG AA 4.5:1)           |
-| `'large'`     | 45  | Large/bold headlines; fine icons/outlines (~3:1)     |
-| `'non-text'`  | 30  | Solid icons/controls; placeholder/disabled text      |
-| `'min'`       | 15  | Dividers/decorative; APCA "point of invisibility"    |
-
-```ts
-contrast: { apca: 'content' }          // Lc 60
-contrast: { apca: ['content', 'body'] } // HC pair: 60 normal, 75 high-contrast
-```
-
-## 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.