@cube-dev/ui-kit 0.0.0-canary-7c5dc45 → 0.0.0-canary-7d44972

package/docs/glaze/methodology.md

@@ -1,664 +1,336 @@
 # Methodology
 
-A practical way to design a Glaze palette without fighting dark mode. Start from
-tone relationships, add contrast only where a role needs a readable floor, and
-let `extend()` carry the same decisions across status hues.
-
-For the full API surface, see [api.md](api.md). For the Glaze color-model
-overview, see [okhst.md](okhst.md); the derivation lives in the
-[canonical OKHST specification](https://github.com/tenphi/okhst).
+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
 
-Glaze palettes work best as one default neutral theme plus a few colored sibling
-themes:
-
-- `default` owns the neutral system most components consume: `#surface`,
-  `#surface-text`, `#border`, `#disabled-surface`, and so on.
-- Status themes (`success`, `danger`, `warning`, `note`, ...) are created with
-  `extend()`. They swap the hue and keep only the inherited tokens that should
-  become status-aware.
-- `inherit: false` keeps a token local to the parent theme. Use it for neutral
-  ladders, shadows, code colors, overlays, and anything that should not be
-  repeated for every status hue.
-
-The main simplification is OKHST tone. Dark mode is a single inversion
-(`100 - t`) plus a scheme tone window, so a relative **tone delta** stays
-anchored to its base in every scheme. A token authored as `tone: '-4'` remains
-the same kind of visual step in light and dark. The step is exactly
-contrast-even for neutrals and approximate for chromatic colors; add a
-`contrast` floor when the measured result matters.
-
-Use `glaze.color()` instead of a theme when you need one standalone color or
-one base/dependent pair and do not need a named palette. The same tone,
-adaptation, and contrast rules apply; see
-[Standalone color tokens](api.md#standalone-color-tokens).
-
-## Implementation workflow
-
-Build in dependency order so every decision has a clear base:
-
-1. Configure the output schemes and application states once.
-2. Choose the default theme's hue and saturation seed.
-3. Define root surfaces with absolute tones.
-4. Add dependent surfaces, text, borders, and icons with tone deltas.
-5. Add contrast floors only to roles that need measured readability or
-   recognizability.
-6. Choose adaptation per color: `auto`, `fixed`, or `static`.
-7. Add explicit HC pairs where high contrast should increase separation.
-8. Mark default-only tokens `inherit: false`, then extend the shared
-   definitions into status themes.
-9. Compose and export the palette in the shape your application consumes.
-10. Verify complete screens in all emitted scheme variants.
-
-The sections below follow this order and build one palette incrementally.
-
-## Authoring decisions
-
-Use this order when defining a token:
-
-1. Pick the base it visually belongs to.
-2. Use an absolute numeric `tone` for independent placement. Use a signed
-   **tone delta** (`'+N'` / `'-N'`) for distance from a base: surface ladders,
-   soft chips, disabled states, hover ramps, and similar relationships.
-3. Add `contrast` only when readability or recognizability needs a measured
-   floor.
-4. Prefer APCA presets for content-like colors when perceptual readability is
-   the design goal:
-   `contrast: { apca: 'content' }` or
-   `contrast: { apca: ['content', 'body'] }`.
-5. Use WCAG numbers or presets when compatibility, policy, or migration
-   requires a WCAG ratio:
-   `contrast: 4.5`, `contrast: 'AAA'`, or `contrast: { wcag: [4.5, 7] }`.
-6. Let token names infer APCA roles. Names ending in `text`, `label`, `border`,
-   `surface`, `fill`, `bg`, and similar aliases already tell Glaze which side is
-   foreground or background. Set `role` only when a name is ambiguous.
-7. Add high-contrast pairs only where HC should intentionally tighten:
-   text/content contrast, border tone, shadow intensity, mix value, or similar.
-
-### Choosing adaptation mode
-
-| Mode             | Choose it when                                                                                                              |
-| ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `auto` (default) | The color should exchange light/dark positions through dark tone inversion. Typical for surfaces, text, borders, and icons. |
-| `fixed`          | A brand fill, status banner, or inverse surface should stay on the authored side of the tone scale.                         |
-| `static`         | The exact authored tone and saturation must render in every scheme, without tone-window mapping or dark desaturation.       |
-
-Dark tone inversion is controlled by `mode`; it is unrelated to `autoFlip`.
-`autoFlip` only allows an overshooting tone delta or an unsuccessful contrast
-direction to reverse around its base.
-
-### Root or dependent?
-
-- Use a root color when its tone has meaning on its own: the page surface, a
-  fixed brand anchor, or a scheme extreme.
-- Use a dependent color when its purpose exists relative to another token:
-  text on a surface, a border around a fill, or a tint of an accent.
-- Setting `base` with an absolute tone is valid when the color needs a contrast
-  relationship but not a tone delta. The absolute position is resolved
-  independently; `contrast` acts as a safety floor.
-
-## Seed and configure
-
-Keep hue decisions named and configure output modes once:
+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.
 
-```ts
-import { glaze } from '@tenphi/glaze';
+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
 
-const PURPLE_HUE = 280.3;
+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 DANGER_HUE  = 23.1;
 const WARNING_HUE = 84.3;
-const NOTE_HUE = 302.3;
+const NOTE_HUE    = 302.3;
 
 const SEED_SATURATION = 80;
-
-glaze.configure({
-  states: { dark: '@dark', highContrast: '@hc' },
-  modes: { dark: true, highContrast: true },
-});
 ```
 
-Per-color `saturation` is a factor of the theme seed, not an absolute
-saturation. With `SEED_SATURATION = 80`, `saturation: 0.25` means one quarter of
-that seed.
+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.
 
-### When dark needs its own chroma
+## Global `glaze.configure()`
 
-Dark schemes get a flat `darkDesaturation` haircut (10% by default), which is
-enough for most palettes. Reach for a second seed only when dark is wrong in a
-way a uniform reduction cannot fix — a hue that reads muddy against dark
-surfaces, or an accent that stays gaudy no matter how much you dial the global
-knob:
+Configure state aliases and output modes once at module load:
 
 ```ts
-const primary = glaze({
-  hue: PURPLE_HUE,
-  saturation: SEED_SATURATION,
-  darkHue: PURPLE_HUE - 12, // cooler purple on dark surfaces
-  darkSaturation: 62, // calmer than a 10% haircut would give
+glaze.configure({
+  states: { dark: '@dark', highContrast: '@hc' },
+  modes:  { dark: true,    highContrast: true },
 });
 ```
 
-An explicit `darkSaturation` replaces `darkDesaturation` rather than stacking
-with it, so the number you write is the number you get. Prefer tuning the seed
-over per-color `darkHue` / `darkSaturation`: one seed keeps the palette
-coherent, while scattered per-color dark overrides drift apart as the palette
-grows. Save the per-color form for the one or two tokens that genuinely need it.
+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
+## Naming conventions
 
-Prefer purpose first and variant last:
+A tight, predictable vocabulary that the rest of the doc relies on:
 
-- Surfaces: `surface`, `surface-2`, `surface-3`.
-- Foregrounds: `surface-text`, `surface-text-soft`, `surface-text-soft-2`.
-- Structure: `border`, `divider`, `outline`, `placeholder`, `focus`.
-- Fills: `accent-surface`, `accent-surface-2`,
-  `accent-surface-hover`.
-- Foregrounds on neutral surfaces: `accent-text`, `accent-text-soft`,
-  `accent-icon`.
-- Disabled states: `disabled-surface`, `disabled-surface-text`,
-  `accent-disabled-surface`, `accent-disabled-surface-text`.
-- Effects: `shadow-sm`, `shadow-md`, `shadow-lg`, `overlay`, `hover`, `tint`.
+| 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` |
 
-These names are not only readable. They also help APCA role inference pick the
-right polarity. For example, `button-text` is foreground, `input-bg` is a
-surface, and `card-outline` is a border.
+**Rule of thumb:** *purpose-name first, variant suffix last* (`-2`, `-text`, `-soft`, `-hover`, `-disabled`).
 
-## Build the default theme
+## Surfaces (root colors)
 
-Start with the surface family. It is mostly tone, with small saturation changes
-to keep the ladder visually coherent:
+`surface` is a root color (absolute `lightness`, no `base`) with a low saturation factor. The ladder chains off it via small relative offsets:
 
 ```ts
-const defaultTheme = glaze(PURPLE_HUE, SEED_SATURATION);
-
 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,
-  },
+  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 },
 });
 ```
 
-Because each tone delta re-anchors to the resolved surface in every scheme,
-these small relative offsets are enough to define the ladder. There is no
-separate dark-mode curve to tune.
+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.
+
+`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.
 
-### Text and borders
+## Text on surfaces (anchor at the edge)
 
-Use a hard edge tone for maximum-prominence text, and APCA floors for softer
-content:
+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`**.
 
 ```ts
-defaultTheme.colors({
-  'surface-text': {
-    base: 'surface',
-    tone: 2,
-    saturation: 0.475,
-  },
-  'surface-text-soft': {
-    base: 'surface',
-    tone: '-1',
-    saturation: 0.375,
-    contrast: { apca: ['content', 'body'] },
-    inherit: false,
-  },
-  'surface-text-soft-2': {
-    base: 'surface',
-    tone: '-1',
-    saturation: 0.24,
-    contrast: { apca: ['large', 'content'] },
-    inherit: false,
-  },
-  border: {
-    base: 'surface',
-    tone: ['-10', '-20'],
-    saturation: 0.175,
-    inherit: false,
-  },
-});
+'surface-text': {
+  base: 'surface', lightness: 2, saturation: 0.475,
+},
+'surface-text-soft': {
+  base: 'surface', lightness: '-1', saturation: 0.375,
+  contrast: [9, 11], inherit: false,
+},
+'surface-text-soft-2': {
+  base: 'surface', lightness: '-1', saturation: 0.24,
+  contrast: [4.5, 5.5], inherit: false,
+},
 ```
 
-`surface-text` uses an absolute `tone: 2` despite having a base: it is
-intentionally edge-anchored, and the base records the relationship used by
-role inference. The soft variants use a `-1` tone delta as the preferred
-direction and APCA as the readable floor. `border` uses an HC tone-delta pair
-because borders usually need a larger visible step in high contrast.
+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 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.
 
-Repeat the same pattern for `surface-2` and `surface-3` only if components need
-text directly on those surfaces.
+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).
 
-### Neutral utility tokens
+## Other neutral primitives
 
-Keep neutral-only primitives local to the default theme:
+Borders, placeholders, focus rings, and the floating "muted text" lightness — all default-only:
 
 ```ts
-defaultTheme.colors({
-  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:      { 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 },
 ```
 
-Absolute tones are fine for primitives whose job is visual placement rather than
-a strict relationship to a specific surface.
+`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.
 
-## Chips and disabled states
+## Disabled chip (contrast-driven for scheme symmetry)
 
-For subtle fills, tone is usually clearer than contrast:
+The disabled chip + label pair uses `mode: 'auto'` and **explicit numeric contrast** against `surface`, not preset `'AA'` / `'AAA'`:
 
 ```ts
-defaultTheme.colors({
-  'disabled-surface': {
-    base: 'surface',
-    tone: '-3',
-    saturation: 0.2,
-    inherit: false,
-  },
-  'disabled-surface-text': {
-    base: 'disabled-surface',
-    tone: '+18',
-    saturation: 0.3,
-    autoFlip: false,
-    inherit: false,
-  },
-});
+'disabled-surface': {
+  base: 'surface', lightness: '-1', saturation: 0.2,
+  contrast: [1.5, 2], inherit: false,
+},
+'disabled-surface-text': {
+  base: 'disabled-surface', lightness: '+1', saturation: 0.3,
+  contrast: 3, inherit: false,
+},
 ```
 
-This says exactly what the pair should do: the chip sits a small tone delta off
-the page, and the label sits a muted delta from the chip. `autoFlip: false`
-keeps the label on the authored side when the delta reaches the edge.
+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.
 
-Use contrast instead when the chip must hit an explicit accessibility floor:
+## `surface-inverse` (the fixed-mode escape hatch)
 
 ```ts
-defaultTheme.colors({
-  'disabled-surface-text': {
-    base: 'disabled-surface',
-    tone: '+1',
-    saturation: 0.3,
-    contrast: { apca: 'non-text' },
-    inherit: false,
-  },
-});
+'surface-inverse': {
+  lightness: 12, saturation: 0.475, mode: 'fixed', inherit: false,
+},
 ```
 
-When a token needs the scheme extreme, use `tone: 'min'` or `tone: 'max'`
-directly. Avoid large magic numbers or fake contrast floors just to push a color
-to the edge.
+`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.
 
-Pair the extreme with a `base` when the gap between the two has to survive the
-scheme switch. Glaze then replays the light-scheme tone shift against the
-resolved dark base instead of re-mapping the extreme through the dark window,
-so a knockout on a surface keeps the same contrast in both schemes.
+Use it for tooltips, code blocks, popovers with their own dark theme. Pair with `#white` for foreground text.
 
-## Fixed surfaces and accent fills
+This is the canonical "I want this color to stay recognizable" pattern. The other `mode: 'fixed'` use is the entire accent system below.
 
-Use `mode: 'fixed'` when the authored color should stay recognizable across
-schemes.
+## 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'`:
 
 ```ts
-defaultTheme.colors({
-  'surface-inverse': {
-    tone: 12,
-    saturation: 0.475,
-    mode: 'fixed',
-    inherit: false,
-  },
-
-  'accent-surface-text': {
-    tone: 100,
-    mode: 'fixed',
-  },
-  'accent-surface': {
-    base: 'accent-surface-text',
-    tone: '-1',
-    contrast: { apca: ['content', 'body'] },
-    mode: 'fixed',
-  },
-  'accent-surface-2': {
-    base: 'accent-surface-text',
-    tone: '-1',
-    contrast: { apca: [65, 80] },
-    mode: 'fixed',
-  },
-  'accent-surface-hover': {
-    base: 'accent-surface-text',
-    tone: '-1',
-    contrast: { apca: ['body', 'preferred'] },
-    mode: 'fixed',
-  },
-});
+'accent-surface-text': { lightness: 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' },
 ```
 
-The accent fill family is a fixed chain against a fixed text anchor. The names
-infer `surface` and `text` roles, so APCA gets the right polarity without extra
-fields.
+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.
+- **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
 
-Brand foregrounds that sit on neutral surfaces should stay adaptive:
+The opposite of the fills. Brand-colored *foregrounds* are anchored to **`surface`, not `accent-surface`**, with `mode: 'auto'` (default) and full saturation:
 
 ```ts
-defaultTheme.colors({
-  'accent-text': {
-    base: 'surface',
-    tone: '-1',
-    saturation: 1,
-    contrast: { apca: ['content', 'body'] },
-  },
-  'accent-text-soft': {
-    base: 'surface',
-    tone: '-1',
-    saturation: 1,
-    contrast: { apca: ['large', 'content'] },
-  },
-  'accent-icon': {
-    base: 'surface',
-    tone: '-1',
-    saturation: 0.9375,
-    contrast: { apca: ['non-text', 'large'] },
-  },
-});
+'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]  },
 ```
 
-Anchor these to `surface`, not to `accent-surface`. Their real job is to remain
-readable on neutral UI, so `mode: 'auto'` and a surface base are the right
-defaults.
+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.
+
+`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 states can usually be pure tone:
+## 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:
 
 ```ts
-defaultTheme.colors({
-  'accent-disabled-surface': {
-    base: 'surface',
-    tone: '+3',
-    saturation: 0.5,
-  },
-  'accent-disabled-surface-text': {
-    base: 'accent-disabled-surface',
-    tone: '+18',
-    saturation: 0.4,
-    autoFlip: false,
-  },
-});
+'accent-disabled-surface': {
+  base: 'surface', lightness: '-1', saturation: 0.5,
+  contrast: [1.4, 1.3],
+},
+'accent-disabled-surface-text': {
+  base: 'accent-disabled-surface', lightness: '+1', saturation: 0.4,
+  contrast: 1.51, mode: 'fixed',
+},
 ```
 
-These are inherited, so status themes automatically get
-`success-accent-disabled-surface`, `danger-accent-disabled-surface`, and the
-matching text tokens.
+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.
+
+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.
 
-## Special-purpose colors
+## Per-color hue overrides (code highlighting)
 
-Use absolute `hue` overrides for tokens that should come from another hue family
-but keep the same adaptation behavior:
+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
-defaultTheme.colors({
-  'code-comment': {
-    base: 'surface',
-    hue: 280,
-    saturation: 0.1,
-    tone: '-1',
-    contrast: { apca: ['large', 'content'] },
-    inherit: false,
-  },
-  'code-keyword': {
-    base: 'surface',
-    hue: 348,
-    saturation: 1,
-    tone: '-1',
-    contrast: { apca: ['content', 'body'] },
-    inherit: false,
-  },
-  'code-string': {
-    base: 'surface',
-    hue: SUCCESS_HUE,
-    saturation: 1,
-    tone: '-1',
-    contrast: { apca: ['large', 'content'] },
-    inherit: false,
-  },
-});
+'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-punctuation, code-number, code-function, code-attribute follow the same shape
 ```
 
-Use small tone ramps for decorative motion:
+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* lightnesses with high saturation factors and tight numeric contrasts:
 
 ```ts
-defaultTheme.colors({
-  'loading-face-1': {
-    base: 'surface',
-    tone: 98,
-    saturation: 0.3,
-    inherit: false,
-  },
-  'loading-face-2': {
-    base: 'surface',
-    tone: 91,
-    saturation: 0.62,
-    inherit: false,
-  },
-  'loading-face-3': {
-    base: 'surface',
-    tone: 79,
-    saturation: 0.66,
-    inherit: false,
-  },
-});
+'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 },
 ```
 
-Since tone steps now invert consistently across schemes, the same ramp keeps its
-spacing in light and dark without involving the contrast solver. Use an HC tone
-pair only when the animation should become more pronounced in high contrast.
+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.
 
-## Effects
+## Shadows
 
-Define one neutral shadow system:
+Three sizes, all sharing `bg: 'surface'` and `fg: 'surface-text'`, varying only `intensity`:
 
 ```ts
-defaultTheme.colors({
-  'shadow-sm': {
-    type: 'shadow',
-    bg: 'surface',
-    fg: 'surface-text',
-    intensity: 5,
-    inherit: false,
-  },
-  'shadow-md': {
-    type: 'shadow',
-    bg: 'surface',
-    fg: 'surface-text',
-    intensity: [10, 20],
-    inherit: false,
-  },
-  'shadow-lg': {
-    type: 'shadow',
-    bg: 'surface',
-    fg: 'surface-text',
-    intensity: [15, 30],
-    inherit: false,
-  },
-});
+'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` lets shadow strength follow the resolved foreground/background
-gap. Use an HC pair for shadows that should deepen in high contrast.
+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).
 
-Use `opacity` for one fixed-alpha color:
+## Overlay (fixed opacity)
 
 ```ts
-defaultTheme.colors({
-  overlay: { tone: 10, opacity: 0.5, inherit: false },
-});
+overlay: { lightness: 10, opacity: 0.5, inherit: false },
 ```
 
-Use mixes when one color should tint through another:
+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
-defaultTheme.colors({
-  hover: {
-    type: 'mix',
-    base: 'surface',
-    target: 'accent-surface',
-    value: 8,
-    blend: 'transparent',
-  },
-  tint: {
-    type: 'mix',
-    base: 'surface',
-    target: 'accent-surface',
-    value: 20,
-  },
-});
+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 mixes are good for hover overlays. Opaque mixes are good for solid
-tints. Opaque mixes default to perceptual OKHSL interpolation; choose `srgb`
-when matching channel compositing matters. Transparent mixes always composite
-in linear sRGB. Mix colors can also use `contrast`; the solver adjusts the
-value or opacity to hit the floor. See [Mix colors](api.md#mix-colors).
+- **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.
 
-## Extend into status themes
+## Colored sibling themes via `extend()`
 
-Once the default theme is shaped, create colored siblings by replacing hue and
-overriding only the root surface that should become visibly tinted:
+One shared `TINTED_SURFACE_OVERRIDE`, applied to every colored theme, with only the `hue` changing per status:
 
 ```ts
-const TINTED_SURFACE_OVERRIDE = {
-  surface: { tone: 96, saturation: 0.8 },
+const TINTED_SURFACE_OVERRIDE: ColorMap = {
+  surface: { lightness: 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,
-});
+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 });
 ```
 
-The inherited accent and disabled tokens now resolve in each status hue. Tokens
-marked `inherit: false` stay default-only, so sibling themes remain small.
+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.
 
-## Export the palette
+`primaryTheme` keeps the default hue but gets the tinted surface — useful for places that want a brand-tinted banner without semantic status meaning.
 
-Compose the themes once:
+## 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,
+  danger:  dangerTheme,
   warning: warningTheme,
-  note: noteTheme,
+  note:    noteTheme,
 });
 ```
 
-The usual export shape is default unprefixed and status themes prefixed:
-
-```ts
-const prefix = {
-  default: '',
-  primary: 'primary-',
-  success: 'success-',
-  danger: 'danger-',
-  warning: 'warning-',
-  note: 'note-',
-};
-
-palette.tasty({ prefix });
-```
-
-An explicit prefix map is the clearest choice when the palette has a neutral
-`default` theme. The separate palette `primary` option serves another pattern:
-it duplicates one named theme without a prefix while retaining its prefixed
-tokens. Do not combine the two accidentally; choose the token namespace your
-components expect.
-
-The palette design is independent of the exporter:
-
-```ts
-palette.tokens({ prefix }); // JavaScript maps, native oklch by default
-palette.css({ prefix }); // CSS custom-property declarations
-palette.dtcg({ prefix }); // one design-token tree per scheme
-palette.tailwind({ prefix }); // Tailwind CSS v4 theme
-```
-
-Use `palette.tasty({ prefix })` for [Tasty](https://tasty.style) state bindings. See
-[migration.md](migration.md#choosing-an-export) for output shapes, application
-wiring, and the `primary` alias pattern.
-
-## High contrast
+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 is not a separate palette. Any value that accepts an HC pair can
-tighten the HC variant: `tone`, `contrast`, shadow `intensity`, and mix `value`.
+## High-contrast strategy
 
-Use HC pairs where users should actually get more separation:
+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:
 
-- Text/content contrast: `{ apca: ['content', 'body'] }`.
-- Accent fills: `{ apca: ['content', 'body'] }` or stronger.
-- Borders: `tone: ['-10', '-20']`.
-- Shadows: `intensity: [10, 20]`.
-- Decorative ramps that must stay perceivable.
+- 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']`).
 
-In HC variants, Glaze bypasses the normal tone window and uses the full
-`[0, 100]` range. Edge tones can reach the edge; contrast floors have more room
-to solve.
+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.
 
-## Checklist
+## Closing checklist
 
 Before shipping a palette, verify:
 
-- Text, icon, and content tokens either have APCA/WCAG contrast or are
-  deliberately edge-anchored.
-- Accent fills use `mode: 'fixed'`; accent foregrounds on neutral UI stay
-  `mode: 'auto'` and are based on `surface`.
-- Ambiguous APCA tokens have an explicit `role`; obvious names rely on inference.
-- Low-stakes visual relationships use tone deltas instead of fake contrast
-  floors.
-- `inherit: false` is set on default-only tokens so status themes stay focused.
-- HC pairs exist where high contrast should visibly tighten.
-- `glaze.configure({ states, modes })` matches the states registered in the app.
-- Every emitted scheme (`light`, `dark`, `lightContrast`, `darkContrast`) has
-  been reviewed on complete screens, not only in a token grid.
-- Rendered WCAG/APCA results have been checked for chromatic foreground/base
-  pairs that carry accessibility requirements.
-- Resolution emits no unexplained unreachable-contrast or token-collision
-  warnings.
+- [ ] Every text token has an explicit `contrast` *or* an edge-anchored absolute `lightness`.
+- [ ] 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.