@tenphi/cookbook 0.32.0 → 0.33.0

package/docs/upstream/glaze/docs/reference/contrast.md

@@ -0,0 +1,277 @@
+---
+title: Contrast and high contrast
+description: HCPair, ContrastSpec and its WCAG and APCA presets, high-contrast escalation, and the manual contrast level.
+---
+
+This page lists the contrast types, presets, and rules. For how the solver finds a tone, when to pick WCAG or APCA, and live examples, see [Contrast solving](../contrast.mdx). For how a color adapts across schemes, see [Light, dark, and high contrast](../schemes.mdx).
+
+```ts
+import type {
+  HCPair,
+  ContrastSpec,
+  MinContrast,
+  ContrastPreset,
+  ApcaPreset,
+} from '@tenphi/glaze';
+```
+
+## `HCPair<T>`
+
+A value used in both contrast tiers, or an explicit `[normal, highContrast]` pair:
+
+```ts
+type HCPair<T> = T | [T, T];
+```
+
+The first entry drives the `light` and `dark` variants, the second `lightContrast` and `darkContrast`. A single value applies to both.
+
+| Field | Type | Pair example |
+| --- | --- | --- |
+| `tone` on a [regular color](./color-definitions.md#regularcolordef) | `HCPair<ToneValue>` | `tone: ['-8', '-16']` |
+| `contrast` on a regular or [mix](./color-definitions.md#mixcolordef) color | `HCPair<ContrastSpec>` | `contrast: [4.5, 7]` |
+| `intensity` on a [shadow or glow](./color-definitions.md#shadowcolordef--glowcolordef) | `HCPair<number>` | `intensity: [8, 14]` |
+| `value` on a [mix](./color-definitions.md#mixcolordef) | `HCPair<number>` | `value: [10, 20]` |
+| `tone` and `contrast` on a [color token](./color-tokens.md) | `HCPair<…>` | `tone: [74, 80]` |
+
+```ts
+tone: '-8'; // -8 in normal and high contrast
+tone: ['-8', '-16']; // -8 normal, -16 high contrast
+contrast: { apca: 'content' }; // preset, auto-escalated in high contrast
+contrast: { apca: ['content', 'body'] }; // explicit normal / HC targets
+```
+
+For `contrast`, the pair can wrap the whole spec or sit inside the metric (see [`ContrastSpec`](#contrastspec)). An explicit high-contrast value in either position turns off the automatic [escalation](#high-contrast-escalation) for that color.
+
+Under a numeric [`contrastLevel`](#manual-contrast-level), the normal variants are resolved between the two entries.
+
+## `ContrastSpec`
+
+A contrast floor with a choice of metric:
+
+```ts
+type ContrastPreset = 'AA' | 'AAA' | 'AA-large' | 'AAA-large';
+type ApcaPreset =
+  | 'preferred'
+  | 'body'
+  | 'content'
+  | 'large'
+  | 'non-text'
+  | 'min';
+
+type MinContrast = number | ContrastPreset; // a bare WCAG target
+
+type ContrastSpec =
+  | number // WCAG ratio
+  | ContrastPreset // WCAG preset
+  | { wcag: HCPair<number | ContrastPreset> }
+  | { apca: HCPair<number | ApcaPreset> }; // APCA Lc target
+```
+
+Every `contrast` field takes `HCPair<ContrastSpec>`: [`RegularColorDef`](./color-definitions.md#contrast), [`MixColorDef`](./color-definitions.md#mixcolordef), and the [color token](./color-tokens.md) inputs.
+
+| Form | Metric | Example | Normal | High contrast |
+| --- | --- | --- | --- | --- |
+| Number | WCAG | `contrast: 4.5` | 4.5 | 4.5 |
+| WCAG preset | WCAG | `contrast: 'AAA'` | 7 | 7 |
+| `{ wcag }` | WCAG | `contrast: { wcag: 6 }` | 6 | 6 |
+| Outer pair | WCAG | `contrast: [4.5, 7]` | 4.5 | 7 |
+| Inner pair | WCAG | `contrast: { wcag: [4.5, 7] }` | 4.5 | 7 |
+| Pair of objects | WCAG | `contrast: [{ wcag: 4.5 }, { wcag: 7 }]` | 4.5 | 7 |
+| `{ apca }` number | APCA | `contrast: { apca: 60 }` | Lc 60 | Lc 75 (escalated) |
+| `{ apca }` preset | APCA | `contrast: { apca: 'content' }` | Lc 60 | Lc 75 (escalated) |
+| Inner APCA pair | APCA | `contrast: { apca: [45, 60] }` | Lc 45 | Lc 60 |
+| Inner APCA preset pair | APCA | `contrast: { apca: ['content', 'body'] }` | Lc 60 | Lc 75 |
+
+- A bare number or preset means **WCAG**. Use `{ wcag }` / `{ apca }` to name the metric.
+- A WCAG number below `1` is treated as `1`. A negative APCA number uses its magnitude.
+- The floor is measured against the color's `base`, in each scheme separately. It is a floor, not a target: a color whose preferred tone already clears it with the solver's small margin (×1.01 for WCAG, +0.5 Lc for APCA) keeps it, and one that misses moves only as far as the floor requires. How the search works, `autoFlip`, and unreachable targets are covered in [Contrast solving](../contrast.mdx#how-the-solver-finds-a-tone).
+- WCAG is symmetric. APCA is not, so a color's [role](./color-definitions.md#roles) decides which side of the pair is measured as text.
+- On a theme color, `contrast` requires `base`. Without one, validation throws `glaze: color "<name>" has "contrast" without "base".` On a [color token](./color-tokens.md#pairing-colors) without a `base`, the floor is measured against the token's own input color.
+- `contrast` together with `opacity` emits a `console.warn`: a translucent color has no fixed perceived tone.
+- A floor that is physically unreachable pins a regular color or token to the extreme of the side the solver searched first (not necessarily the closer one) and warns. A mix pins its ratio or opacity to the end of the range it searched and warns too: normally the pure target, but a mix whose value is already 100 (including the high-contrast entry of `value: [80, 100]`) can only search toward the base, so it pins to the pure base. A preferred tone or value that clears the floor itself is never given up for an unmet extreme: a value-100 mix whose pure target passes keeps it. Tone is contrast-uniform for grays, so Glaze also re-measures each chromatic regular color whose floor the solver met and emits a deduped drift advisory if it lands under the floor; the solver measures the real color, so this normally stays silent. See [When a floor can't be met](../contrast.mdx#when-a-floor-cant-be-met) and [Warnings](./configuration.md#warnings).
+
+### WCAG presets
+
+`ContrastPreset`:
+
+| Preset | Ratio | WCAG criterion | High-contrast successor |
+| --- | --- | --- | --- |
+| `'AA-large'` | 3 | SC 1.4.3, large text | `'AAA-large'` (4.5) |
+| `'AA'` | 4.5 | SC 1.4.3 | `'AAA'` (7) |
+| `'AAA-large'` | 4.5 | SC 1.4.6, large text | — (top tier) |
+| `'AAA'` | 7 | SC 1.4.6 | — (top tier) |
+
+`resolveMinContrast(value)` maps a `MinContrast` to its ratio; see [Resolving a spec](./utilities.md#resolving-a-spec).
+
+### APCA presets
+
+`ApcaPreset` keywords are the APCA Bronze Simple Mode conformance levels. They don't depend on the role.
+
+| Preset | Lc | Use |
+| --- | --- | --- |
+| `'preferred'` | 90 | Preferred body and column text |
+| `'body'` | 75 | Minimum for body and column text |
+| `'content'` | 60 | Readable non-body content (about WCAG AA 4.5:1) |
+| `'large'` | 45 | Large or bold headlines; fine icons and outlines (about 3:1) |
+| `'non-text'` | 30 | Solid icons and controls; placeholder and disabled text |
+| `'min'` | 15 | Dividers and decoration; APCA's point of invisibility |
+
+The same map is exported as `APCA_PRESETS` (see [Constants and types](./utilities.md#constants-and-types)). A raw Lc number works anywhere a preset does.
+
+## High-contrast escalation
+
+Without an explicit high-contrast entry, the `lightContrast` / `darkContrast` variants solve for a stronger floor:
+
+| Authored | Normal | High contrast |
+| --- | --- | --- |
+| `'AA'`, `{ wcag: 'AA' }` | 4.5 | 7 (`'AAA'`) |
+| `'AA-large'`, `{ wcag: 'AA-large' }` | 3 | 4.5 (`'AAA-large'`) |
+| `'AAA'`, `'AAA-large'` | 7, 4.5 | Unchanged — already the top WCAG tier. |
+| A WCAG number (`4.5`, `{ wcag: 6 }`) | as written | Unchanged — a bare ratio has no successor tier. |
+| An APCA number or preset | Lc | Lc + 15, capped at 106 (a target already above 106 is kept). |
+| An explicit pair, outer or inner | first entry | second entry, no escalation. |
+
+- **WCAG promotion** follows the spec's own Enhanced level, SC 1.4.3 → SC 1.4.6.
+- **APCA Enhanced Level** adds `APCA_HC_ENHANCEMENT` (15 Lc), the Lc analog of AAA over AA, and clamps the result to `APCA_MAX_LC` (106). The cap only limits the boost: a normal target already above 106 stays as it is, never lower than the normal tier's.
+- **An explicit high-contrast value** in the outer `contrast` pair or the inner `wcag` / `apca` pair replaces the automatic step. Use one to hold a ceiling. APCA caps large or bold text at Lc 90 to avoid glare, so for a heading write `{ apca: ['preferred', 'preferred'] }` rather than letting high contrast boost it past 90.
+- **Other pairs** (`tone`, `intensity`, mix `value`) have no automatic escalation: a single value is used in both tiers.
+- **Tone windows** don't apply in high contrast: placement and the contrast search use the full `0–100` tone range. See [Light, dark, and high contrast](../schemes.mdx#high-contrast).
+
+## Metric switching
+
+A `contrast` pair can't switch metric between its entries. A WCAG ratio and an APCA Lc are different scales, so `[4.5, { apca: 75 }]` has no target between its ends, and even without a manual level the two variants would be judged incomparably. Validation throws:
+
+```text
+glaze: color "text" has a "contrast" pair that switches metric
+  (wcag → apca).
+A WCAG ratio and an APCA Lc are different scales; use one metric for
+  both entries, e.g. { wcag: [normal, highContrast] }.
+```
+
+Pair values inside one metric instead: `{ wcag: [4.5, 7] }` or `{ apca: [60, 90] }`.
+
+## Manual contrast level
+
+`contrastLevel` puts the normal end of the two-tier contrast model on a `0–100` slider. It is a config field, so it works globally, per theme, per token, and through `extend()`:
+
+```ts
+import { glaze } from '@tenphi/glaze';
+
+glaze.configure({ contrastLevel: 60 });
+const theme = glaze(280, 80, { contrastLevel: 60 });
+const brand = glaze.color('#26fcb2', { contrastLevel: 60 });
+```
+
+The level moves the **normal** variants, `light` and `dark`. It says nothing about high contrast: `lightContrast` / `darkContrast` stay the true high-contrast resolution at every level, and [`modes.highContrast`](./output.md#output-modes) alone decides whether they are emitted.
+
+| Value | Meaning |
+| --- | --- |
+| `'auto'` | Default. The normal variants take the authored normal entries as they are. |
+| `0` | The same output as `'auto'`, reached through the slider. |
+| `100` | The normal variants are the high-contrast ones. Set globally, the separate tier is dropped as a duplicate; see [High-contrast output](#high-contrast-output). |
+| `1`–`99` (any number between) | The normal variants are resolved at that level. |
+
+- Levels `0` and `100` reproduce the classic `light` / `dark` and `lightContrast` / `darkContrast` output bit for bit.
+- Numbers are clamped to `0–100`. A non-finite number, or any value other than a number or `'auto'` (such as the string `'50'`), throws: `glaze: contrastLevel must be a finite number 0–100 or 'auto' (got NaN).`
+- The field is listed with the rest of the config in [`GlazeConfig`](./configuration.md#glazeconfig) and [`GlazeConfigOverride`](./configuration.md#glazeconfigoverride).
+
+### What the level interpolates
+
+Exactly the three things that make a high-contrast variant differ from its normal one:
+
+| Mechanism | At level `L` |
+| --- | --- |
+| Authored `HCPair`s: `tone`, `contrast`, shadow / glow `intensity`, mix `value` | The two entries are interpolated. |
+| The tone-window bypass | Each window endpoint moves linearly toward the full range: light `10 → 0`, dark `15 → 0` and `95 → 100` with the defaults. The render `eps` is not interpolated. |
+| Contrast escalation (`AA → AAA`, APCA `+15 Lc`) | Both ends are resolved with the [escalation rules](#high-contrast-escalation), then the numeric target is interpolated. `'AA'` at level 50 solves for 5.75; `{ apca: 'content' }` at level 25 for Lc 63.75. |
+
+The interpolated values go through the ordinary resolve, so a contrast floor at any level is **solved**, not approximated. Which side of its base a solved color prefers is fixed once per half of the ramp; see [Which side of its base a color takes](#which-side-of-its-base-a-color-takes).
+
+They feed the two normal passes only. The high-contrast passes ignore the level and resolve exactly as in `'auto'` mode.
+
+Hue, saturation, `darkDesaturation`, `opacity`, and `pastel` don't vary with high contrast, so the level doesn't change them.
+
+### Un-interpolable tone pairs switch at 50
+
+A pair whose entries are of different kinds has no midpoint: blending them would change *which* resolution rule applies partway up the ramp. These pairs use the normal entry below level 50 and the high-contrast entry from 50 up:
+
+```ts
+tone: [50, 'max']; // absolute vs extreme
+tone: [50, '+20']; // absolute vs delta (on a color with a base)
+tone: ['max', 'min']; // extremes carry no magnitude
+```
+
+Same-kind pairs interpolate smoothly: `[30, 20]`, `['-6', '-12']`, `{ wcag: [4.5, 7] }`, `[{ apca: 60 }, { apca: 90 }]`. Numeric pairs (`intensity`, `value`) always interpolate.
+
+A `contrast` pair can't switch metric at all; see [Metric switching](#metric-switching).
+
+### Which side of its base a color takes
+
+[`autoFlip`](./color-definitions.md#autoflip) decides per solve, and its tie-break (when both sides of the base meet the floor, take the one nearer the preferred tone) depends on the target. Along a ramp of targets that tie-break can change, so a naive solve would let a color jump across its own base as the slider moves.
+
+Under a manual level, each level first runs a probe: a solve at the nearer endpoint's target (level `0` below 50, level `100` from 50 up), from that level's preferred tone and base. The color then prefers the side the probe lands on:
+
+- While the preferred side meets the floor, the color stays there, even where the other side would be nearer its preferred tone.
+- The probe's target is the same across each half of the ramp, so the preferred side normally holds through it and changes only at level 50, where un-interpolable pairs also switch, when the two endpoints land on different sides. The preferred tone and the base move with the tone windows, though, so a color whose endpoint solve is close to a tie (both sides about equally near its preferred tone) can switch sides at another level.
+- Flipping is re-ordered, not disabled. At a level where the preferred side can't reach the interpolated target, the solver falls back to the opposite side, so the floor is met wherever either side can meet it. Where neither side can, the color pins to the preferred side's extreme. A color near the limit of what either side can reach can therefore cross its base at other levels, and back again, even when both endpoints land on the same side.
+- A probe that lands on its base pins no side. With `contrast: [1, 4.5]`, the level-0 probe keeps the preferred tone, and for a `'+0'` delta that is the base's own tone. Each level then picks a side by the solver's own tie rule, exactly as the same color without a `tone` would.
+
+For example, in a gray theme (`glaze(0, 0)`), a static tone-95 color with `contrast: [3, 6]` on a static tone-60 base stays above the base through level 12, where it reaches white, and sits below it from level 13 (tone 19.6) on. White reaches only 3.38:1 against the base, and the target, rising from 3 to 6, passes that at level 12.7.
+
+A color can also cross and come back. In the same theme, black reaches 4.55:1 against a static tone-49.77 base and white 4.61:1. A color on that base with `tone: '-1'` and `contrast: 'AA'` sits below it in light at both endpoints, but at levels 3 and 4 only white meets the rising target, so it moves above the base. From level 5 neither side meets the target, and it pins back to black.
+
+The underlying solver option is `preferInitial` on [`findToneForContrast`](./utilities.md#findtoneforcontrastoptions), for the same behavior in a custom pipeline.
+
+### High-contrast output
+
+The level and the high-contrast tier are independent, and they compose: the slider raises the baseline, and a `prefers-contrast: more` block still escalates on top of whatever level the reader chose.
+
+- `resolve()` returns four variants at every level. `lightContrast` / `darkContrast` are bit-identical to what `'auto'` resolves for those slots.
+- [`modes.highContrast`](./output.md#output-modes) alone decides whether the tier is emitted, as in `'auto'` mode. A level doesn't turn it on or off, with the one exception below.
+- `css()` ignores `modes` and always returns four strings. At a mid level its `lightContrast` / `darkContrast` strings carry escalated values that differ from the normal ones, so an existing `@media (prefers-contrast: more)` block keeps doing real work.
+- A level on a **single theme or token** never changes which modes are emitted: `modes` is global, and one palette sibling must not collapse the shared token structure.
+
+| `contrastLevel` | `modes.highContrast: false` (default) | `modes.highContrast: true` |
+| --- | --- | --- |
+| `'auto'` or `0` | `light`, `dark` | + `lightContrast`, `darkContrast` |
+| `1`–`99` | `light`, `dark` at the level | + the tier, unchanged by the level |
+| `100`, set globally | `light`, `dark` equal the high-contrast values | The same: the tier is dropped as a duplicate. |
+
+At a global level of `100` the normal variants *are* the high-contrast ones, so a separate tier would be an exact copy. Glaze emits a single light / dark set and suppresses even an explicit per-call `modes: { highContrast: true }`. A level of `100` set on one theme or token still reports into the tier, with values equal to its own normal ones.
+
+### Driving it at runtime
+
+`configure()` bumps the config version, which invalidates every theme and token cache, so a slider only needs to re-export:
+
+```ts
+import { glaze } from '@tenphi/glaze';
+
+const theme = glaze(280, 80);
+theme.colors({
+  surface: { tone: 97 },
+  'surface-text': { base: 'surface', tone: '-52', contrast: 'AA' },
+});
+
+const slider = document.querySelector<HTMLInputElement>(
+  '#contrast-level',
+)!;
+const style = document.head.appendChild(document.createElement('style'));
+
+slider.oninput = () => {
+  glaze.configure({ contrastLevel: slider.valueAsNumber });
+  const { light, dark } = theme.css();
+  style.textContent =
+    `:root { ${light} }\n` +
+    `@media (prefers-color-scheme: dark) { :root { ${dark} } }`;
+};
+```
+
+A resolve at a manual level runs the same four passes as an `'auto'` one. Only level `100` skips the two high-contrast passes, because the normal passes already produced those values.
+
+### Clearing it, exporting it, base links
+
+- **`configure()` never clears a field by omission.** `glaze.configure({})` keeps the current level. Pass `contrastLevel: 'auto'` to leave manual mode, globally or on one theme of a palette.
+- **`.export()` freezes only an authored level.** A level set on the instance, or passed to `.export(override)`, is written to the snapshot. A level inherited from `glaze.configure()` is a live reader preference and is left out, so a restored theme still follows the current slider. `modes` and `states` are never written to a snapshot. See [`theme.export()`](./theme.md#themeexportoverride).
+- **Set the level globally, or on both sides of a base link.** A dependent [color token](./color-tokens.md#pairing-colors) reads its base token as the base resolved it, so a level set on only one of them solves the dependent's floor at its own level against a base at another. Tone deltas still step cleanly: an `'auto'` base under another level's dark window is read back through the link's, so a `'+0'` link lands on its base and dark steps use the link's scale. In the high-contrast tier, a dependent reads its base's high-contrast slots (and at level `100`, the base's mirrored normal ones).
+
+`resolveContrastForLevel(spec, level, polarity?)` resolves a `contrast` spec at a level the same way, for custom pipelines. For levels strictly between `0` and `100` it throws on a pair that switches metric. See [Resolving a spec](./utilities.md#resolving-a-spec).

package/docs/upstream/glaze/docs/reference/index.md

@@ -0,0 +1,225 @@
+---
+title: API reference
+description: A map of every public export in @tenphi/glaze, the conventions they share, and how authoring snapshots are versioned.
+---
+
+The reference is organized for lookup. This page maps every public export to the page that documents it, then covers the conventions the whole API shares and how authoring snapshots are versioned. For explanations and visuals, start with the concept pages: [Light, dark, and high contrast](../schemes.mdx), [Contrast solving](../contrast.mdx), [Shadows and glows](../shadows-and-glows.mdx), [Mixes and transparency](../mixes.mdx), and [Tone and OKHST](../okhst.mdx).
+
+```ts
+import { glaze } from '@tenphi/glaze';
+import type { GlazeTheme, ColorMap } from '@tenphi/glaze';
+```
+
+The package ships ESM and CommonJS with full type declarations and has no runtime dependencies.
+
+## Reference pages
+
+| Page | Covers |
+| --- | --- |
+| [Themes](./theme.md) | `glaze()`, `fromHex` / `fromRgb` / `themeFrom`, theme properties and methods, `extend`, `resolve`, `export`. |
+| [Color definitions](./color-definitions.md) | The `ColorDef` union: regular, shadow, glow, and mix colors, every field, and a glow's HDR value. |
+| [Contrast and high contrast](./contrast.md) | `HCPair`, `ContrastSpec`, WCAG and APCA presets, high-contrast escalation, the manual contrast level. |
+| [Color tokens](./color-tokens.md) | Standalone `glaze.color()` tokens, their methods, and `glaze.colorFrom()`. |
+| [Palettes](./palette.md) | `glaze.palette()`, prefixes, collisions, the primary alias, `glaze.paletteFrom()`. |
+| [Output formats](./output.md) | Every output method and option, color formats, output modes, state aliases, `splitHue`, HDR output. |
+| [Configuration](./configuration.md) | `glaze.configure()` and every `GlazeConfig` field, per-instance overrides, validation, warnings. |
+| [Utilities](./utilities.md) | `glaze.format` / `glaze.formatHdr`, the HDR channel helpers, standalone `glaze.shadow` / `glaze.glow`, color math, tone utilities, the contrast solver, role helpers, guards. |
+
+## `glaze` and its statics
+
+`glaze` is the only value most code needs. It is a function with static methods attached:
+
+| Member | Returns | Documented in |
+| --- | --- | --- |
+| `glaze(hue, saturation?, config?)` | `GlazeTheme` | [Themes](./theme.md#glazehue-saturation-config) |
+| `glaze(seed, config?)` | `GlazeTheme` | [Themes](./theme.md#glazeseed-config) |
+| `glaze.fromHex(hex)` | `GlazeTheme` | [Themes](./theme.md#glazefromhexhex--glazefromrgbr-g-b) |
+| `glaze.fromRgb(r, g, b)` | `GlazeTheme` | [Themes](./theme.md#glazefromhexhex--glazefromrgbr-g-b) |
+| `glaze.themeFrom(data)` | `GlazeTheme` | [Themes](./theme.md#glazethemefromdata--glazefromdata) |
+| `glaze.from(data)` | `GlazeTheme` | Alias of `themeFrom` — [Themes](./theme.md#glazethemefromdata--glazefromdata) |
+| `glaze.palette(themes, options?)` | `GlazePalette` | [Palettes](./palette.md#glazepalettethemes-options) |
+| `glaze.paletteFrom(data)` | `GlazePalette` | [Palettes](./palette.md#paletteexportoverride--glazepalettefromdata) |
+| `glaze.color(input, config?)` | `GlazeColorToken` | [Color tokens](./color-tokens.md#glazecolorinput-config) |
+| `glaze.colorFrom(data)` | `GlazeColorToken` | [Color tokens](./color-tokens.md#tokenexportoverride--glazecolorfromdata) |
+| `glaze.shadow(input)` | `ResolvedColorVariant` | [Utilities](./utilities.md#glazeshadowinput--glazeglowinput) |
+| `glaze.glow(input)` | `ResolvedColorVariant` | [Utilities](./utilities.md#glazeshadowinput--glazeglowinput) |
+| `glaze.format(variant, format?, pastel?)` | `string` | [Utilities](./utilities.md#glazeformatvariant-format-pastel) |
+| `glaze.formatHdr(variant, hdrFormat?)` | `string \| undefined` | [Utilities](./utilities.md#glazeformathdrvariant-hdrformat) |
+| `glaze.configure(config)` | `void` | [Configuration](./configuration.md#glazeconfigureconfig) |
+| `glaze.getConfig()` | `GlazeConfigResolved` | [Configuration](./configuration.md#glazegetconfig) |
+| `glaze.resetConfig()` | `void` | [Configuration](./configuration.md#global-config) |
+| `glaze.isThemeExport(data)` | `data is GlazeThemeExport` | [Authoring snapshots](#authoring-snapshots-and-versioning) |
+| `glaze.isColorTokenExport(data)` | `data is GlazeColorTokenExport` | [Authoring snapshots](#authoring-snapshots-and-versioning) |
+| `glaze.isPaletteExport(data)` | `data is GlazePaletteExport` | [Authoring snapshots](#authoring-snapshots-and-versioning) |
+
+## Instance methods
+
+| Instance | Members | Documented in |
+| --- | --- | --- |
+| `GlazeTheme` | `hue`, `saturation`, `darkHue`, `darkSaturation`, `getConfig`, `colors`, `color`, `remove`, `has`, `list`, `reset`, `extend`, `resolve`, `export` | [Themes](./theme.md#theme-methods) |
+| `GlazeTheme` output | `tokens`, `tasty`, `json`, `css`, `dtcg`, `dtcgResolver`, `tailwind` | [Output formats](./output.md) |
+| `GlazePalette` | `list`, `primary`, `theme`, `themes`, `export`, and the seven output methods | [Palettes](./palette.md#palette-members) |
+| `GlazeColorToken` | `resolve`, `token`, `tasty`, `json`, `css`, `dtcg`, `dtcgResolver`, `tailwind`, `export` | [Color tokens](./color-tokens.md#token-methods) |
+
+## Named exports
+
+Everything below is exported from `'@tenphi/glaze'` next to `glaze`. Apart from `GLAZE_EXPORT_VERSION` and the type guards, these are lower-level building blocks for advanced use and custom pipelines.
+
+| Export | Kind | Documented in |
+| --- | --- | --- |
+| `glaze` | Function | This page |
+| `GLAZE_EXPORT_VERSION` | Constant (`2`) | [Authoring snapshots](#authoring-snapshots-and-versioning) |
+| `isThemeExport`, `isColorTokenExport`, `isPaletteExport` | Type guards (same functions as the `glaze.*` statics) | [Authoring snapshots](#authoring-snapshots-and-versioning) |
+| `assertNativeFormat`, `assertAllPastel` | Export guards | [Utilities](./utilities.md#export-guards); where they apply: [Color formats](./output.md#color-formats) (`assertNativeFormat`), [`splitHue` requirements](./output.md#requirements) (`assertAllPastel`) |
+| `findToneForContrast`, `findValueForMixContrast`, `resolveMinContrast`, `resolveContrastForMode`, `resolveContrastForLevel`, `resolveApcaTarget`, `apcaContrast` | Contrast solver functions | [Utilities](./utilities.md#contrast-solver) |
+| `APCA_PRESETS`, `APCA_HC_ENHANCEMENT`, `APCA_MAX_LC` | Contrast constants | [Utilities](./utilities.md#constants-and-types); presets in [Contrast and high contrast](./contrast.md#apca-presets) |
+| `normalizeRole`, `inferRoleFromName`, `roleToPolarity`, `oppositeRole` | Role helpers | [Utilities](./utilities.md#role-helpers) |
+| `toTone`, `fromTone`, `toneFromY`, `yFromTone`, `okhstToOkhsl`, `okhslToOkhst`, `variantToOkhsl`, `REF_EPS` | OKHST tone utilities | [Utilities](./utilities.md#okhst-tone-utilities); the model in [Tone and OKHST](../okhst.mdx) |
+| `okhslToLinearSrgb`, `okhslToSrgb`, `okhslToOklab`, `oklabToOkhsl`, `srgbToOkhsl`, `hslToSrgb`, `okhslToOklch`, `cuspLightness`, `parseHex`, `parseHexAlpha`, `srgbToHex`, `relativeLuminanceFromLinearRgb`, `contrastRatioFromLuminance`, `gamutClampedLuminance`, `apcaLuminanceFromLinearRgb` | Color math | [Utilities](./utilities.md#color-math) |
+| `formatOkhsl`, `formatOkhst`, `formatRgb`, `formatHsl`, `formatOklch` | Format writers (0–1 scale) | [Utilities](./utilities.md#format-writers) |
+| `formatSrgb`, `formatSrgbLinear` | HDR writers: extended or linear sRGB channels, unclamped, as `color(srgb R G B)` / `color(srgb-linear R G B)` | [Utilities](./utilities.md#format-writers); the format: [Extended sRGB](../hdr.mdx#extended-srgb) |
+| `hdrToSrgb`, `hdrToLinearSrgb` | HDR channels: a `ResolvedHdr` → extended or linear sRGB, unclamped | [Utilities](./utilities.md#hdrtosrgbhdr--hdrtolinearsrgbhdr) |
+
+## Types
+
+All public types are exported with `import type`.
+
+| Area | Types | Documented in |
+| --- | --- | --- |
+| Theme | `GlazeTheme`, `GlazeThemeSeed`, `GlazeExtendOptions`, `GlazeThemeExport` | [Themes](./theme.md) |
+| Resolved values | `ResolvedColor`, `ResolvedColorVariant` | [Themes](./theme.md#themeresolve) |
+| HDR values | `ResolvedHdr`, `GlazeHdrFormat` | [Color definitions](./color-definitions.md#hdr-values-resolvedhdr), [Utilities](./utilities.md#glazeformathdrvariant-hdrformat), [Output formats](./output.md#hdr-output) |
+| Color definitions | `ColorDef`, `ColorMap`, `RegularColorDef`, `ShadowColorDef`, `GlowColorDef`, `MixColorDef`, `LightingTuning`, `ShadowTuning`, `GlowTuning` | [Color definitions](./color-definitions.md) |
+| Tone and adaptation | `ToneValue`, `RelativeValue`, `ExtremeValue`, `AdaptationMode` | [Color definitions](./color-definitions.md), [Configuration](./configuration.md) |
+| Roles | `Role`, `RoleInput`, `Polarity` | [Color definitions](./color-definitions.md), [Utilities](./utilities.md) |
+| Contrast | `HCPair`, `MinContrast`, `ContrastSpec`, `ContrastPreset`, `ApcaPreset` | [Contrast and high contrast](./contrast.md) |
+| Contrast solver | `ResolvedContrast`, `FindToneForContrastOptions`, `FindToneForContrastResult`, `FindValueForMixContrastOptions`, `FindValueForMixContrastResult` | [Utilities](./utilities.md) |
+| Configuration | `GlazeConfig`, `GlazeConfigOverride`, `GlazeConfigResolved`, `ToneWindow` | [Configuration](./configuration.md) |
+| Color values | `GlazeColorValue`, `HexColor`, `OkhslColor`, `OkhstColor`, `RgbColor`, `OklchColor` | [Color tokens](./color-tokens.md) |
+| Color tokens | `GlazeColorToken`, `GlazeColorInput`, `GlazeFromInput`, `GlazeColorOverrides`, `GlazeColorCssOptions`, `GlazeColorTailwindOptions`, `GlazeColorDtcgResult`, `GlazeColorDtcgResolverOptions`, `GlazeColorTokenExport`, `GlazeColorInputExport`, `GlazeColorOverridesExport` | [Color tokens](./color-tokens.md) |
+| Standalone shadow and glow | `GlazeLightingInput`, `GlazeShadowInput`, `GlazeGlowInput` | [Utilities](./utilities.md) |
+| Palette | `GlazePalette`, `GlazePaletteOptions`, `GlazePaletteExportOptions`, `GlazePaletteTastyOptions`, `GlazePaletteCssOptions`, `GlazePaletteExport` | [Palettes](./palette.md) |
+| Output options | `GlazeColorFormat`, `GlazeOutputModes`, `GlazeTokenOptions`, `GlazeTastyOptions`, `GlazeJsonOptions`, `GlazeCssOptions`, `GlazeCssResult`, `GlazeCssSchemeBlocks`, `GlazeTailwindOptions` | [Output formats](./output.md) |
+| DTCG | `GlazeDtcgOptions`, `GlazeDtcgResult`, `DtcgColorSpace`, `DtcgColorToken`, `DtcgColorValue`, `DtcgSrgbColorValue`, `DtcgOklchColorValue`, `DtcgDocument` | [Output formats](./output.md#dtcgoptions) |
+| DTCG HDR extension | `GlazeDtcgExtensions`, `GlazeDtcgHdr` | [Output formats](./output.md#dtcg-extensions) |
+| DTCG resolver | `GlazeDtcgResolverOptions`, `GlazeDtcgResolverContextNames`, `GlazeDtcgResolverDocument`, `DtcgResolverSet`, `DtcgResolverModifier`, `DtcgResolverRef`, `DtcgTokenTree` | [Output formats](./output.md#dtcgresolveroptions) |
+| `splitHue` planning | `HuePlan`, `HueDeclaration`, `ChannelCtx` | [Output formats](./output.md#planning-types) |
+| Snapshots | `GlazeExportKind`, `GlazeExportVersion` | [Authoring snapshots](#authoring-snapshots-and-versioning) |
+
+## Conventions
+
+### Scales
+
+Glaze mixes a few numeric scales. Which one applies depends on where a value is authored:
+
+| Value | Scale | Where |
+| --- | --- | --- |
+| Hue | 0–360 degrees | Everywhere: seeds, per-color `hue` / `darkHue`, resolved variants, value objects. |
+| Seed saturation | 0–100 | `glaze(hue, saturation)`, `GlazeThemeSeed.saturation` / `darkSaturation`, `theme.saturation`, the structured `glaze.color({ saturation })`, `GlazeColorOverrides.saturation`. |
+| Per-color saturation | 0–1, a factor of the seed | `RegularColorDef.saturation` / `darkSaturation`; `saturationFactor` / `darkSaturationFactor` on color tokens. With `from`, an explicit `saturation` is still a factor of the seed. |
+| Tone | 0–100 | Authored `tone`, tone deltas (`'+20'`). Shadow and glow `intensity` is a step in tones (0–100). |
+| Tone window endpoints | 0–100 OKHSL lightness, not tone | `lightTone` / `darkTone` `lo` and `hi`. The default `darkTone: [15, 95]` holds tones 9.25–95.9, so a tone-100 `auto` surface lands at tone 9.25 in dark. See [Tone windows](./configuration.md#tone-windows). |
+| Mix `value` | 0–100 | `MixColorDef.value` (0 = base, 100 = target). |
+| Resolved variant | `h` 0–360; `s`, `t`, `alpha` 0–1 | `ResolvedColorVariant`, the input to `glaze.format()`. Its optional `hdr` (`ResolvedHdr`) uses the same scales plus `exposure`. |
+| Headroom, exposure | Stops above SDR white; each stop doubles luminance. `headroom` 0–2. | `glowTuning.headroom` and a glow's `tuning.headroom`; `ResolvedHdr.exposure` and DTCG `exposure`. 1 stop past white is tone 121.98, 2 stops tone 144.34. |
+| HDR channels | Extended or linear sRGB, unclamped; `1` is SDR white. One stop above it is `1.3533` extended, `2` linear. | Extended: every exporter's HDR strings, DTCG `hdr.value`, `glaze.formatHdr()` by default, `hdrToSrgb`, `formatSrgb`. Linear: `glaze.formatHdr(v, 'srgb-linear')`, `hdrToLinearSrgb`, `formatSrgbLinear`. |
+| Value objects | `{ h, s, l }` and `{ h, s, t }`: `s`, `l`, `t` 0–1. `{ r, g, b }`: 0–255. `{ l, c, h }`: `L` and `C` 0–1, `H` degrees. | `from`, `glaze.color()`, `glaze.shadow()` / `glaze.glow()` inputs. |
+| Format writers and converters | `h` 0–360; `s`, `l`, `t` 0–1 | `formatOkhsl` … `formatOklch` and the color math functions. The format writers warn when they get 0–100 percentages (the pre-2.0 scale). |
+| Opacity, ratios | 0–1 | `opacity`, `darkDesaturation`, lighting `tint` / `reach` / `hueBleed`. |
+| Contrast level | 0–100, or `'auto'` | `contrastLevel`. |
+| sRGB channels | 0–255 | `glaze.fromRgb(r, g, b)`, `rgb()` output. |
+
+### Scheme variant names
+
+Every resolved color has four variants: `light`, `dark`, `lightContrast`, and `darkContrast`. `ResolvedColor` and the results of `tokens()`, `json()`, `css()`, and `dtcg()` use these names as keys. `tasty()` keys the variants by state alias, `tailwind()` by selector, and `dtcgResolver()` uses the names as its default context names. See [Scheme variants](./output.md#scheme-variants).
+
+### High-contrast pairs
+
+Fields that can differ in high contrast accept an `HCPair<T>`: either a single value or a `[normal, highContrast]` tuple.
+
+```ts
+type HCPair<T> = T | [T, T];
+
+theme.colors({
+  border: { base: 'surface', tone: ['-8', '-20'] },
+  'surface-text': { base: 'surface', contrast: ['AA', 'AAA'] },
+});
+```
+
+`tone`, `contrast`, shadow and glow `intensity`, and mix `value` accept pairs. The first entry drives `light` / `dark`, the second `lightContrast` / `darkContrast`. Under a manual `contrastLevel` the normal variants interpolate between the two. Full rules: [Contrast and high contrast](./contrast.md).
+
+### Tone values
+
+An authored `tone` is a number (absolute, 0–100), a signed string (`'+N'` / `'-N'`, a tone delta from `base`), or `'max'` / `'min'` (the scheme's tone extreme). See [Color definitions](./color-definitions.md#tone-values) and, for what tone means, [Tone and OKHST](../okhst.mdx).
+
+## Authoring snapshots and versioning
+
+Every instance can be saved as a JSON-safe **authoring snapshot** — the definitions and a frozen config, not resolved colors — and restored later:
+
+| Export | Restore | Kind |
+| --- | --- | --- |
+| [`theme.export(override?)`](./theme.md#themeexportoverride) | [`glaze.themeFrom(data)`](./theme.md#glazethemefromdata--glazefromdata) | `'theme'` |
+| [`token.export(override?)`](./color-tokens.md#tokenexportoverride--glazecolorfromdata) | [`glaze.colorFrom(data)`](./color-tokens.md#tokenexportoverride--glazecolorfromdata) | `'color'` |
+| [`palette.export(override?)`](./palette.md#paletteexportoverride--glazepalettefromdata) | [`glaze.paletteFrom(data)`](./palette.md#paletteexportoverride--glazepalettefromdata) | `'palette'` |
+
+Resolved output (`tokens()`, `css()`, `json()`, …) is a different thing: it can't be restored. [Exporting and integration](../exporting.mdx) explains when to use which.
+
+### `kind` and `version`
+
+Every `.export()` writes two fields:
+
+- `kind` — `GlazeExportKind`: `'theme'`, `'color'`, or `'palette'`.
+- `version` — `GLAZE_EXPORT_VERSION`, currently `2` (`GlazeExportVersion` is its literal type).
+
+| Version | Written by |
+| --- | --- |
+| `1` | Glaze 1.1–2.x. |
+| `2` | Glaze 3: shadow `intensity`, `fg`, and tuning changed meaning, and `glow` was added. |
+
+### Restore checks
+
+`themeFrom`, `colorFrom`, and `paletteFrom` apply the same rules:
+
+| Snapshot | Result |
+| --- | --- |
+| No `kind` / no `version` (legacy or hand-written) | Accepted. |
+| `kind` doesn't match the restore function | Throws, e.g. `glaze.themeFrom: expected kind "theme", got "palette".` |
+| `version` not an integer ≥ 1 | Throws `… invalid "version" field — expected an integer >= 1 (got <value>).` |
+| `version` greater than `GLAZE_EXPORT_VERSION` | Throws `… unsupported export version <n> (this library supports version 2). Upgrade @tenphi/glaze to load this snapshot.` |
+| `version: 1` theme or palette with shadow colors or a `shadowTuning` config | Throws (below). |
+| `version: 1` without shadows | Restores as before. |
+
+A version-1 theme snapshot with shadows is rejected because Glaze 3 changed what shadow `intensity`, `fg`, and tuning mean: restoring it would silently render every shadow differently. The error names the shadows and points to the upgrade guide:
+
+```text
+glaze.themeFrom: this snapshot is export version 1 (Glaze 1.1–2) and contains
+  shadow colors ("card-shadow").
+Glaze 3 changed what shadow "intensity", "fg" and tuning mean, so it would
+  restore with different shadows.
+Re-author them as described in docs/migration.md ("3.0 — shadows and
+  glows") and export again.
+```
+
+A theme entry inside a palette snapshot that has no `version` of its own is checked against the palette's `version`. The check keys on `version: 1`, so a snapshot without any `version` (a hand-written one, or one from Glaze 1.0) is not checked: re-author its shadows before restoring it. How to re-author Glaze 2 shadows is in [3.0 — shadows and glows](../migration.md#30--shadows-and-glows).
+
+### Type guards
+
+`isThemeExport`, `isColorTokenExport`, and `isPaletteExport` (also available as `glaze.isThemeExport` etc.) tell the snapshot kinds apart. They check `kind` when present and fall back to the shape for legacy snapshots:
+
+| Guard | `true` when |
+| --- | --- |
+| `isThemeExport(data)` | A plain object with `kind: 'theme'` or no `kind`, numeric `hue` and `saturation`, and no `form` or `themes` field. |
+| `isColorTokenExport(data)` | A plain object with `kind: 'color'` or no `kind`, and `form` of `'value'` or `'structured'`. |
+| `isPaletteExport(data)` | A plain object with `kind: 'palette'` or no `kind`, a `themes` object, no `form`, and no numeric `hue`. |
+
+A `kind` that names a different snapshot type always returns `false`. The guards check structure only; they don't validate `version` or the color definitions.
+
+```ts
+import { glaze } from '@tenphi/glaze';
+
+const data: unknown = JSON.parse(saved);
+
+if (glaze.isPaletteExport(data)) glaze.paletteFrom(data);
+else if (glaze.isThemeExport(data)) glaze.themeFrom(data);
+else if (glaze.isColorTokenExport(data)) glaze.colorFrom(data);
+```