@tenphi/glaze 0.0.0-snapshot.c3d484c → 0.0.0-snapshot.c61bbdf

package/AGENTS.md

@@ -13,7 +13,9 @@
 ```
 glaze/
 ├── src/                       Source
-├── docs/                      Long-form docs (okhst / api / methodology / migration)
+├── docs/                      Long-form docs: concepts, guides, reference (md/mdx, rendered by the site)
+├── docs-site/                 Site-only files: home page + live-example components
+├── playground/                Interactive playground (Vite)
 ├── assets/                    Logo + brand assets
 ├── scripts/                   Repo helpers
 ├── README.md                  Compact intro
@@ -23,6 +25,8 @@ glaze/
 ├── tsconfig.json
 ├── tsdown.config.ts           Build config
 ├── vitest.config.ts           Test config
+├── astro.config.ts            Docs site (Astro + Cookbook)
+├── docs.config.ts             Docs site config: navigation, theme, `@hc` state
 └── eslint.config.js
 ```
 
@@ -31,36 +35,54 @@ glaze/
 | File | Description |
 |---|---|
 | [src/index.ts](src/index.ts) | Public barrel; re-exports `glaze`, every public type, the contrast-solver utilities, and the OKHSL/sRGB/OKLab math helpers. |
-| [src/glaze.ts](src/glaze.ts) | `glaze()` factory + attached statics: `palette`, `paletteFrom`, `color`, `colorFrom`, `themeFrom`, `from` (alias), `fromHex`, `fromRgb`, `shadow`, `format`, `configure`, `getConfig`, `resetConfig`, `isThemeExport` / `isColorTokenExport` / `isPaletteExport`. Thin wiring layer over the focused modules below. |
+| [src/glaze.ts](src/glaze.ts) | `glaze()` factory + attached statics: `palette`, `paletteFrom`, `color`, `colorFrom`, `themeFrom`, `from` (alias), `fromHex`, `fromRgb`, `shadow`, `glow`, `format`, `configure`, `getConfig`, `resetConfig`, `isThemeExport` / `isColorTokenExport` / `isPaletteExport`. Thin wiring layer over the focused modules below. |
 | [src/theme.ts](src/theme.ts) | Single-theme factory (`createTheme`). Owns the mutable `ColorMap`, the `resolve()` cache (versioned against `getConfigVersion()`), and the `tokens` / `tasty` / `json` / `css` / `extend` / `export` methods. `export(override?)` deep-clones defs and freezes effective config with `kind`/`version`. |
 | [src/palette.ts](src/palette.ts) | Multi-theme composition (`createPalette` / `createPaletteFromExport`). Shared per-theme driver `buildPaletteOutput` handles prefix resolution, primary duplication, collision filtering. Authoring: `export(override?)`, `theme` / `themes` / `list` / `primary`. |
 | [src/color-token.ts](src/color-token.ts) | Standalone `glaze.color()` tokens. Parses values through `color-value.ts`; owns the structured-input validator, the two factory paths, sparse local config + live resolve, and the JSON-safe export / `glaze.colorFrom` rehydrate round-trip. |
 | [src/color-value.ts](src/color-value.ts) | `GlazeColorValue` parsing + validation: hex (3/6/8), the `rgb()` / `hsl()` / `okhsl()` / `okhst()` / `oklch()` functions, and the four value-object shapes, all normalized to OKHSL by `extractOkhslFromValue`. Split out of `color-token.ts` so the resolver can reach it for a theme color's `from` without closing an import cycle. Leaf module — depends only on the color math. |
-| [src/serialize.ts](src/serialize.ts) | Authoring-export helpers: `GLAZE_EXPORT_VERSION`, `assertExportKind` / `assertExportVersion`, and `isThemeExport` / `isColorTokenExport` / `isPaletteExport` type guards. |
-| [src/resolver.ts](src/resolver.ts) | Four-pass solver (light → light-HC → dark → dark-HC), dropping to two-pass (light → dark) with mirrored HC slots only at `contrastLevel: 100`, where the normal passes already are the HC ones (`hcMirrorsNormal`). Under any other manual level `passTone` / `passNumber` / `resolveContrastSpec` feed interpolated inputs into the two *normal* passes and a probe solve at the nearer endpoint pins which side of its base a contrast-solved color sits on; the HC passes bypass the level and the probe entirely, so the HC tier is bit-identical to `'auto'`. Stores canonical tone (`t`) in variants; per-scheme branches for regular, shadow, and mix defs; integrates the contrast solver, and the OKHST tone helpers. `resolveChannels` owns per-scheme hue/saturation (incl. the `darkHue` / `darkSaturation` seed + def overrides, the `darkDesaturation` bypass, and the absolute hue/saturation a `from` color carries in place of the seed factor) and feeds both the emitted variant and the contrast solver. `configForColor` gives a `from` color a local `lightTone: false` so its light variant reproduces the authored value. Converts to/from OKHSL lightness only at the mix/shadow edges. Pre-seeds externally-resolved bases for `glaze.color({ base })`. |
+| [src/serialize.ts](src/serialize.ts) | Authoring-export helpers: `GLAZE_EXPORT_VERSION` (2 since Glaze 3), `assertExportKind` / `assertExportVersion`, `assertNoLegacyShadows` (rejects a version-1 theme snapshot with shadow defs or `shadowTuning`, since shadows changed meaning in 3.0; palettes pass their version down to each theme), and `isThemeExport` / `isColorTokenExport` / `isPaletteExport` type guards. |
+| [src/resolver.ts](src/resolver.ts) | Four-pass solver (light → light-HC → dark → dark-HC), dropping to two-pass (light → dark) with mirrored HC slots only at `contrastLevel: 100`, where the normal passes already are the HC ones (`hcMirrorsNormal`). Under any other manual level `passTone` / `passNumber` / `resolveContrastSpec` feed interpolated inputs into the two *normal* passes and a probe solve at the nearer endpoint pins which side of its base a contrast-solved color sits on; the HC passes bypass the level and the probe entirely, so the HC tier is bit-identical to `'auto'`. Stores canonical tone (`t`) in variants; per-scheme branches for regular, shadow / glow (one shared `resolveLightingForScheme`), and mix defs; integrates the contrast solver, and the OKHST tone helpers. `resolveChannels` owns per-scheme hue/saturation (incl. the `darkHue` / `darkSaturation` seed + def overrides, the `darkDesaturation` bypass, and the absolute hue/saturation a `from` color carries in place of the seed factor) and feeds both the emitted variant and the contrast solver. `configForColor` gives a `from` color a local `lightTone: false` so its light variant reproduces the authored value. Converts to/from OKHSL lightness only at the mix / shadow / glow edges. Pre-seeds externally-resolved bases for `glaze.color({ base })`. |
 | [src/okhst.ts](src/okhst.ts) | The OKHST tone layer. `REF_EPS`, tone↔lightness transfers (`toTone`/`fromTone`, `toneFromY`/`yFromTone`), OKHST↔OKHSL conversions, `variantToOkhsl` (tone→lightness at render), `normalizeToneWindow` (`[lo,hi]` / `{lo,hi,eps}` / `false` → `{lo,hi,eps}`), `mapToneForScheme` (scheme inversion + window remap, HC bypass), `mapSaturationDark` (the `darkDesaturation` reducer the resolver skips when a dark saturation is authored), and `schemeToneRange` for the solver. `activeWindow` owns the HC window bypass and its continuous form under `contrastLevel`. Only tone adapts here — hue/saturation are the resolver's business. |
 | [src/contrast-solver.ts](src/contrast-solver.ts) | Tone-based binary-search solver for WCAG **and** APCA. Public API: `findToneForContrast` (incl. the `preferInitial` tie-break the manual level uses on its normal passes to keep a color's side stable), `findValueForMixContrast`, `resolveContrastForMode`, `resolveContrastForLevel` (both ends resolved, target interpolated for a manual `contrastLevel`; throws on a metric switch), `contrastMetricOf`, `resolveMinContrast`, `apcaContrast`. Closed-form WCAG seed + tone search. |
-| [src/shadow.ts](src/shadow.ts) | Shadow + mix def predicates (`isShadowDef`, `isMixDef`), default `ShadowTuning`, tuning merge, the actual `computeShadow` math (hue blend, saturation cap, lightness clamp, `tanh` alpha curve) operating on OKHSL lightness at the edge, and `circularLerp` for hue. |
+| [src/lighting.ts](src/lighting.ts) | Shadow / glow / mix def predicates (`isShadowDef`, `isGlowDef`, `isLightingDef`, `isMixDef`), `DEFAULT_LIGHTING_TUNING` + `resolveLightingTuning` (defaults ← global `shadowTuning` / `glowTuning` ← per-color, field by field), `circularLerp`, and the exact solver `computeLighting`: object factor `k = max(0, 1 + β·d·(t_bg − t_fg)/100)` (`objectFactor`), the pigment (pure black / white unless `reach` / `tint` / `hueBleed` say otherwise), and a bisection on opacity against browser compositing so the composite's luminance tone lands exactly `intensity × k` tones darker (shadow) / lighter (glow). Out-of-reach steps pin to the pigment's strongest composite (a golden-section search covers tinted shadow pigments whose channels diverge) and report `reached` for the warning. |
 | [src/hc-pair.ts](src/hc-pair.ts) | Tiny shared helpers: HC-pair selection (`pairNormal` / `pairHC`), HC-pair interpolation for the manual contrast level (`contrastFraction`, `hcMirrorsNormal` — the level-100 "HC slots are duplicates" predicate, `levelFraction`, `numberAt`, `parseToneValueAt`, `PAIR_SWITCH`), tone-value parsing (`parseToneValue` for absolute / relative / `'max'`/`'min'` extremes, `isExtremeTone`), root-tone discrimination (`isAbsoluteTone`, now incl. extremes), `clamp` / `lerp`, hue resolution (`resolveEffectiveHue`), relative-value parsing. Leaf module — types only, so every other module can import it. |
 | [src/formatters.ts](src/formatters.ts) | Variant→string dispatch (`okhsl` / `rgb` / `hsl` / `oklch`) and the four token-map shapes Glaze emits: `buildTokenMap` ([Tasty](https://tasty.style) `#name` keys + state aliases), `buildFlatTokenMap` (per-variant maps), `buildJsonMap` (per-color JSON), `buildCssMap` (CSS custom-property declarations). For `splitHue` it emits the light hue declarations plus, via `darkHueDeclarations` in `channels.ts`, the whole dark set when a `darkHue` makes it differ. Also the `resolveModes` helper used everywhere. |
-| [src/okhsl-color-math.ts](src/okhsl-color-math.ts) | OKHSL ↔ linear-sRGB ↔ gamma-sRGB ↔ OKLab conversions, hex parsing (3/6/8 digits), gamut clamping, and the `formatOkhsl` / `formatOkhst` / `formatRgb` / `formatHsl` / `formatOklch` writers. Converters and writers share one scale — `h` 0–360, `s` / `l` / `t` 0–1 — so any converter composes with any writer (the 0–100 tone axis lives in `okhst.ts`'s `toTone` / `fromTone`, not here); `warnPercentScale` catches pre-2.0 percentage-scale input instead of emitting a plausible wrong color. The only file with the actual color science. |
+| [src/okhsl-color-math.ts](src/okhsl-color-math.ts) | OKHSL ↔ linear-sRGB ↔ gamma-sRGB ↔ OKLab conversions, hex parsing (3/6/8 digits), gamut clamping, browser compositing (`toDisplayGamma` / `compositeOverGamma` — `source-over` on gamma-encoded sRGB, shared by transparent mixes and shadows / glows), and the `formatOkhsl` / `formatOkhst` / `formatRgb` / `formatHsl` / `formatOklch` writers. Converters and writers share one scale — `h` 0–360, `s` / `l` / `t` 0–1 — so any converter composes with any writer (the 0–100 tone axis lives in `okhst.ts`'s `toTone` / `fromTone`, not here); `warnPercentScale` catches pre-2.0 percentage-scale input instead of emitting a plausible wrong color. The only file with the actual color science. |
 | [src/config.ts](src/config.ts) | Global config singleton. `defaultConfig()` is the one source of truth for defaults; `configure()` mutates the live object and bumps a monotonic `configVersion` so theme caches invalidate. `snapshotConfig()` powers `glaze.getConfig()`. `freezeConfigForExport()` freezes resolve-relevant fields for authoring export (`pastel` is instance-only; `contrastLevel` is frozen only when instance-authored, since a global level is a live preference). `normalizeContrastLevel()` validates the manual contrast level. |
-| [src/validation.ts](src/validation.ts) | `validateColorDefs` (missing references, shadow-bg-cannot-be-shadow, mix-cannot-target-shadow, contrast-without-base, relative-without-base, WCAG-vs-APCA metric switch in a `contrast` pair, etc.) + `topoSort` so the resolver processes each color after its dependencies. |
-| [src/warnings.ts](src/warnings.ts) | Deduped contrast-unmet warnings. Caps cache at 256 entries to keep dev-server output bounded. |
-| [src/types.ts](src/types.ts) | All public TypeScript types: `HCPair`, `MinContrast`, `ContrastSpec`, `RelativeValue`, `ExtremeValue` (`'max'`/`'min'`), `ToneValue`, `AdaptationMode`, `OkhstColor`, `ToneWindow` (`[lo,hi]` \| `{lo,hi,eps}` \| `false`), `ColorDef` discriminated union (with `tone` + `flip` + `darkHue` / `darkSaturation`), `GlazeConfig` (with `lightTone` / `darkTone` / `autoFlip` / `contrastLevel`), `GlazeThemeSeed` (`hue` / `saturation` + optional dark pair), `GlazeTheme`, `GlazePalette`, `GlazeColorToken`, the `*Export` shapes, etc. `ResolvedColorVariant` stores `{ h, s, t, alpha }`. |
-| `src/glaze.test.ts` | Main test suite — covers the factory surface, resolver behavior, palette composition, shadow/mix algorithms, the manual contrast level, and the standalone color token round-trip. |
+| [src/validation.ts](src/validation.ts) | `validateColorDefs` (missing references, shadow / glow `bg` / `fg` cannot be a shadow or glow, mixes and regular bases cannot reference one, contrast-without-base, relative-without-base, WCAG-vs-APCA metric switch in a `contrast` pair, etc.) + `topoSort` so the resolver processes each color after its dependencies. |
+| [src/warnings.ts](src/warnings.ts) | Deduped resolve-time warnings: contrast unmet, chromatic contrast drift, and out-of-reach shadow / glow steps (`warnLightingUnreachable`). Caps cache at 256 entries to keep dev-server output bounded. |
+| [src/types.ts](src/types.ts) | All public TypeScript types: `HCPair`, `MinContrast`, `ContrastSpec`, `RelativeValue`, `ExtremeValue` (`'max'`/`'min'`), `ToneValue`, `AdaptationMode`, `OkhstColor`, `ToneWindow` (`[lo,hi]` \| `{lo,hi,eps}` \| `false`), `ColorDef` discriminated union (regular with `tone` + `flip` + `darkHue` / `darkSaturation`; `ShadowColorDef` / `GlowColorDef`; `MixColorDef`), `LightingTuning` (aliased as `ShadowTuning` / `GlowTuning`), `GlazeConfig` (with `lightTone` / `darkTone` / `autoFlip` / `contrastLevel` / `shadowTuning` / `glowTuning`), `GlazeThemeSeed` (`hue` / `saturation` + optional dark pair), `GlazeTheme`, `GlazePalette`, `GlazeColorToken`, the `*Export` shapes, etc. `ResolvedColorVariant` stores `{ h, s, t, alpha }`. |
+| `src/glaze.test.ts` | Main test suite — covers the factory surface, resolver behavior, palette composition, shadow / glow (per-surface step uniformity, object influence, unreachable steps, v1 snapshot rejection) and mix algorithms, the manual contrast level, and the standalone color token round-trip. |
 | `src/contrast-solver.test.ts` | Tests for the binary-search solver in isolation. |
 | `src/hc-pair.test.ts` | Tests for the pure HC-pair selection and interpolation helpers. |
 | `src/okhsl-color-math.test.ts` | Tests for the format writers' 0–1 scale contract, the percentage-scale guard, and producer→writer composition. |
 
 ### `docs/` files
 
+The documentation site (Cookbook on Astro) renders `docs/**/*.{md,mdx}` at the
+path without the extension, plus `docs-site/index.mdx` as the home page.
+Navigation lives in `docs.config.ts`. Concept and guide pages are `.mdx` with
+live examples; reference pages are plain Markdown.
+
+| File | Description |
+|---|---|
+| [docs/getting-started.mdx](docs/getting-started.mdx) | Install, a first theme built step by step, four schemes, and export. |
+| [docs/okhst.mdx](docs/okhst.mdx) | The OKHST color model spec — tone math, `REF_EPS`, the T↔L invariant, the scheme pipeline, calibrated window defaults, the contrast metric, and the APCA verification step. Source of truth for the color model. |
+| [docs/schemes.mdx](docs/schemes.mdx) | Light, dark, and high contrast: inversion + tone windows, adaptation modes, dark seed, HC pairs, the manual contrast level. |
+| [docs/contrast.mdx](docs/contrast.mdx) | Contrast solving: WCAG / APCA floors, roles and polarity, `autoFlip`, HC escalation, warnings. |
+| [docs/shadows-and-glows.mdx](docs/shadows-and-glows.mdx) | `shadow` / `glow`: exact tone steps, object influence, state layers, elevation, tuning. |
+| [docs/mixes.mdx](docs/mixes.mdx) | Opaque and transparent mixes, blend spaces, contrast on mixes. |
+| [docs/methodology.mdx](docs/methodology.mdx) | Palette design methodology — building a complete palette step by step, with the palette shown live as it grows. |
+| [docs/exporting.mdx](docs/exporting.mdx) | Choosing an export shape, wiring tokens into [Tasty](https://tasty.style) / CSS / JSON / DTCG / Tailwind, prefix maps, the `primary` alias. |
+| [docs/migration.md](docs/migration.md) | Migrating an existing color system, upgrading between majors (`3.0 — shadows and glows` is referenced by `src/serialize.ts` errors), common pitfalls. |
+| [docs/reference/](docs/reference/index.md) | API reference: `index` (map of every export + conventions), `theme`, `color-definitions`, `contrast`, `color-tokens`, `palette`, `output`, `configuration`, `utilities`. Lookup, not tutorial. |
+
+### `docs-site/` files
+
 | File | Description |
 |---|---|
-| [docs/okhst.md](docs/okhst.md) | The OKHST color model spec — tone math, `REF_EPS`, the T↔L invariant, the scheme pipeline, calibrated window defaults, the contrast metric, and the APCA verification step. Source of truth for the color model. |
-| [docs/api.md](docs/api.md) | Full API reference. Every method, every option, every type. Reads as a lookup, not a tutorial. |
-| [docs/methodology.md](docs/methodology.md) | Palette design methodology — how to build a palette from scratch. Covers naming conventions, surface ladders, the accent anchor pattern, contrast-driven disabled chips, shadows, and `extend` composition. |
-| [docs/migration.md](docs/migration.md) | Migration & integration guide — choosing an export shape, wiring tokens into [Tasty](https://tasty.style) / CSS / JSON, prefix-map strategies, migrating from a legacy color system, and common pitfalls. |
+| [docs-site/index.mdx](docs-site/index.mdx) | Home page. |
+| [docs-site/components/](docs-site/components/README.md) | Live-example components (`Example`, `Swatches`, `UiPreview`, `SchemeGrid`, `ToneRamp`, page-specific folders). They resolve themes from `src/` at build time and pass colors through Tasty `styles` — Cookbook rejects `style` attributes and non-Tasty CSS. See the folder's README before adding one. |
 
 ## Commands
 
@@ -78,6 +100,10 @@ glaze/
 | `pnpm format:check` | Prettier check (no writes). |
 | `pnpm changeset` | Create a changeset entry. |
 | `pnpm release` | Build and publish (used by CI). |
+| `pnpm docs` | Docs site dev server (Astro + Cookbook). |
+| `pnpm build:docs` | Build the docs site into `dist/` (overwrites the library build there). |
+| `pnpm build:site` | Docs site + playground, as deployed to GitHub Pages. |
+| `pnpm docs:doctor` | Cookbook configuration / content checks. |
 
 ## Stack
 
@@ -100,10 +126,10 @@ glaze/
 
 ## Adding a New Color Type
 
-If you need to add a fourth `ColorDef` variant (alongside regular / shadow / mix), touch these files in order:
+If you need to add another `ColorDef` variant (alongside regular / shadow / glow / mix), touch these files in order:
 
 1. [src/types.ts](src/types.ts) — add the new interface and extend the `ColorDef` discriminated union.
-2. [src/shadow.ts](src/shadow.ts) — add a discriminator predicate (`isFooDef`).
+2. [src/lighting.ts](src/lighting.ts) — add a discriminator predicate (`isFooDef`).
 3. [src/validation.ts](src/validation.ts) — extend `validateColorDefs` (missing-reference / cycle handling) and `topoSort` (record the new dependency edges).
 4. [src/resolver.ts](src/resolver.ts) — add a per-scheme `resolveFooForScheme` branch and dispatch from `resolveColorForScheme`.
 5. [src/formatters.ts](src/formatters.ts) — only if the output shape differs (it usually doesn't; the resolver returns a normal `ResolvedColorVariant`).

package/README.md

@@ -25,12 +25,12 @@ contrast floor.
 
 - **OKHST color space** — OKHSL with a contrast-shaped **tone** axis. Equal
   steps give equal WCAG contrast for neutrals and a useful approximation for
-  chromatic colors. See [OKHST in Glaze](docs/okhst.md) and the
+  chromatic colors. See [Tone and OKHST](docs/okhst.mdx) and the
   [full OKHST specification](https://github.com/tenphi/okhst).
 - **WCAG 2 + APCA contrast solving** — automatic tone adjustment to meet a WCAG ratio or APCA Lc floor
 - **Unified dark mode** — one tone space for light, dark, and high-contrast; dark is a single `100 − t` inversion, no fitted curve
 - **Mix colors** — blend two colors with OKHSL or sRGB interpolation, opaque or transparent, with optional contrast solving
-- **Shadow colors** — OKHSL-native shadow computation with automatic alpha, fg/bg tinting, and per-scheme adaptation
+- **Shadows and glows** — translucent overlays whose opacity is solved per surface, so `intensity` is an exact tone step wherever the surface has room for it (a step past black or white is pinned and warns), with object-aware strength
 - **Light + Dark + High-Contrast** — all schemes from one definition
 - **Manual contrast level** — put your normal palette on a `0–100` slider between itself and the high-contrast one; every level in between is solved, not approximated, and the high-contrast tier stays available on top
 - **Per-color hue override** — absolute or relative hue shifts within a theme
@@ -69,48 +69,54 @@ glaze.configure({
   modes: { dark: true, highContrast: true },
 });
 
-const defaultTheme = glaze(280, 80);
+const theme = glaze(280, 80);
 
-defaultTheme.colors({
+theme.colors({
   surface: { tone: 97, saturation: 0.15 },
   'surface-text': {
     base: 'surface',
     tone: '-1',
+    saturation: 0.4,
     contrast: { apca: ['content', 'body'] },
   },
   border: {
     base: 'surface',
     tone: ['-8', '-16'],
+    saturation: 0.2,
     inherit: false,
   },
-  'accent-surface': { tone: 52, mode: 'fixed' },
-  'accent-surface-text': {
-    base: 'accent-surface',
-    tone: '+1',
+  'accent-surface-text': { tone: 100, mode: 'fixed' },
+  'accent-surface': {
+    base: 'accent-surface-text',
+    tone: '-1',
     contrast: 'AA',
     mode: 'fixed',
   },
 });
 
-const dangerTheme = defaultTheme.extend({ hue: 23 });
-const palette = glaze.palette({ default: defaultTheme, danger: dangerTheme });
+const danger = theme.extend({ hue: 23 });
+const palette = glaze.palette({ default: theme, danger });
 
 const tokens = palette.tokens({
   prefix: { default: '', danger: 'danger-' },
 });
 // → {
 //   light: { surface: 'oklch(...)', 'danger-surface': 'oklch(...)', ... },
-//   dark: { surface: 'oklch(...)', 'danger-surface': 'oklch(...)', ... },
+//   dark: { ... },
 //   lightContrast: { ... },
 //   darkContrast: { ... },
 // }
 ```
 
+The accent fill is solved against its white label, not the reverse: the fill
+darkens until the pair meets `'AA'`, or `'AAA'` in high contrast, where a bare
+`'AA'` rises a tier.
+
 ## Concepts at a glance
 
 1. **A theme has one hue/saturation seed.** Create status themes with
    `extend()` so they inherit the same relationships while changing hue.
-2. **A color is a root or a dependency.** Roots use an absolute `tone` or
+2. **A color is a root or a dependent.** Roots use an absolute `tone` or
    `'max'`/`'min'`. Dependent colors name a `base` and may use a signed
    **tone delta** such as `'-8'` plus a `contrast` floor.
 3. **Tone is an authoring axis, not a contrast guarantee.** Equal tone deltas
@@ -123,8 +129,8 @@ const tokens = palette.tokens({
    inversion (`100 - t`), `fixed` keeps the authored side of the tone scale,
    and `static` skips scheme adaptation.
 6. **Tone windows bound ordinary schemes.** `lightTone` and `darkTone`
-   configure the light/dark render ranges. High-contrast variants use the full
-   range. Values that accept `[normal, highContrast]` pairs can tighten
+   configure the light and dark tone windows. High-contrast variants use the
+   full range. Values that accept `[normal, highContrast]` pairs can tighten
    deliberately in HC.
 
 In Glaze, a **scheme variant** is one of `light`, `dark`, `lightContrast`, or
@@ -143,14 +149,27 @@ In Glaze, a **scheme variant** is one of `light`, `dark`, `lightContrast`, or
 
 ## Documentation
 
-- Start with [the methodology](docs/methodology.md) to design a palette.
-- Use [migration and integration](docs/migration.md) to wire it into an
-  application or replace an existing color system.
-- Keep the [API reference](docs/api.md) nearby for every method and option.
-- Read [OKHST in Glaze](docs/okhst.md) for the product-level color model, or
-  the [full OKHST specification](https://github.com/tenphi/okhst) for its math.
-- [`AGENTS.md`](AGENTS.md) — source-tree orientation for contributors.
+The full documentation, with live examples that follow your light / dark and
+contrast preferences, is at [glaze.tenphi.me](https://glaze.tenphi.me). The
+same pages live in [`docs/`](docs):
+
+- [Getting started](docs/getting-started.mdx) — install, build a first theme,
+  and export it.
+- Concepts: [light, dark, and high contrast](docs/schemes.mdx),
+  [contrast solving](docs/contrast.mdx),
+  [shadows and glows](docs/shadows-and-glows.mdx),
+  [mixes and transparency](docs/mixes.mdx), and the color model under them,
+  [tone and OKHST](docs/okhst.mdx).
+- Guides: [designing a palette](docs/methodology.mdx),
+  [exporting and integration](docs/exporting.mdx), and
+  [migration and upgrading](docs/migration.md) (including Glaze 2 → 3).
+- The [API reference](docs/reference/index.md) for every method, option, and
+  type.
+- Explore the tone axis in the [interactive playground](https://glaze.tenphi.me/playground/),
+  or read the [full OKHST specification](https://github.com/tenphi/okhst) for
+  its math.
+- [`AGENTS.md`](https://github.com/tenphi/glaze/blob/main/AGENTS.md) — source-tree orientation for contributors.
 
 ## License
 
-[MIT](LICENSE)
+[MIT](https://github.com/tenphi/glaze/blob/main/LICENSE)