@cube-dev/ui-kit 0.0.0-canary-2757f7b → 0.0.0-canary-8b6ee8a

package/docs/Theming.md

@@ -0,0 +1,327 @@
+# Theming
+
+The whole palette is generated by [Glaze](https://github.com/tenphi/glaze) from a
+handful of seeds: an accent hue, a base hue, a saturation, and a hue per status
+theme. Those seeds are tunable at runtime — change one and every token re-resolves, in light,
+dark, and high-contrast schemes at once.
+
+```ts
+import { setPaletteConfig } from '@cube-dev/ui-kit';
+
+setPaletteConfig({
+  hue: 210,
+  saturation: 72,
+  themes: { danger: { hue: 12 } },
+});
+```
+
+With no configuration set, the palette is exactly the one the kit ships — the
+defaults below are the shipped seeds, and a snapshot test pins every resolved
+value so this stays true.
+
+## What is tunable
+
+| Option | Scope | Default |
+| --- | --- | --- |
+| `hue` | **Accent** hue in degrees — the brand. Drives the `accent-*` family, `primary` / `purple` / `special`, and the brand-tinted `focus`, loading faces and disabled chip. | `280.3` |
+| `baseHue` | **Base** hue in degrees — the neutral chrome: `surface` and its ladder, the `surface-text*` ramp, `border`, `placeholder`. | inherits `hue` |
+| `saturation` | Seed saturation (0–100) for the `default` theme, and the fallback for every theme that sets none. | `80` |
+| `themes.<status>.hue` | Hue for `success` / `danger` / `warning` / `note`. | `156.9` / `23.1` / `84.3` / `302.3` |
+| `themes.<status>.saturation` | Saturation for that status theme. | inherits `saturation` |
+| `themes.code.saturation` | Saturation for the `code-*` syntax family. Hues are fixed, and this does **not** inherit `saturation`. | `80` |
+| `pastel` | Global. Relaxes the sRGB-safe chroma limit. | `false` |
+| `contrastLevel` | Global. `'auto'`, or a manual `0`–`100` level. | `'auto'` |
+
+Fields merge, like `glaze.configure()` — omitted fields keep their current
+value, and per-theme fields left unset keep inheriting. So this leaves `warning`
+at its explicit saturation while everything else follows the new palette-level
+one:
+
+```ts
+setPaletteConfig({ themes: { warning: { saturation: 95 } } });
+setPaletteConfig({ saturation: 55 }); // warning stays at 95
+```
+
+`resetPaletteConfig()` drops all tuning at once.
+
+### Two hue zones
+
+Hue is split into an **accent** zone and a **base** zone:
+
+- **Accent** (`hue`) — the `accent-*` family on every theme, `primary` / `purple` /
+  `special`, plus `focus`, the loading faces and the disabled chip.
+- **Base** (`baseHue`) — the neutral chrome: `surface` and its ladder, the
+  `surface-text*` ramp, `border`, `placeholder`.
+
+`baseHue` inherits `hue`, so out of the box the chrome carries a faint tint of the
+brand. Set it to decouple them — a warm grey UI under a cool blue brand:
+
+```ts
+setPaletteConfig({ hue: 235, baseHue: 60 });
+```
+
+Only the `default` theme is affected. A colored theme's tinted `surface`
+deliberately follows *its own* hue, because a danger banner should read as red.
+
+### One saturation scale per theme
+
+Saturation is *not* split, deliberately: `saturation` is the theme's **seed**, and
+every color's own `saturation` is a 0–1 factor of it. `surface` sits at `0.12`,
+`border` at `0.175`, the text ramp at `0.2`, the accent family at ~`1.0`.
+
+So the palette has one saturation *scale*, and everything on it keeps its
+proportions: turning `saturation` down mutes the brand fills and the neutral tint
+together, in the ratios the palette was designed around. That is the point — the
+relationship between a subtle surface tint and a saturated accent is part of the
+design, not something to tune per token.
+
+### The `code-*` family is the exception
+
+Syntax colors are their own theme with their own seed, so neither the brand hue nor
+the palette saturation reaches them. Hues are absolute literals — a brand re-seeded
+toward green would otherwise collide `code-string` with `code-number` (156°) — and
+the saturation is fixed at `80` rather than inheriting, so muting the app cannot
+wash out a code block. Tune it on its own:
+
+```ts
+setPaletteConfig({ themes: { code: { saturation: 60 } } });
+```
+
+They are still *adaptive*: each one is anchored to the real `surface` with an
+`['AA','AAA']` floor, so they re-solve for light, dark and high contrast. Only hue
+and saturation are pinned.
+
+That separate seed is also a hard requirement, not a preference: a Glaze colour can
+never exceed its own theme seed, and four of these sit at factor `1.0`. Inside a
+default theme seeded below 80 they simply could not hold their chroma.
+
+### Inherited vs pinned
+
+Every per-theme field starts out **inheriting** the palette-level value, so
+`baseHue` tracks `hue` until something sets it, and `themes.<status>.saturation`
+tracks `saturation`. Moving the accent hue therefore appears to move the base hue
+too — they are not linked, `baseHue` simply has no value of its own yet.
+
+Writing the field pins it; passing `undefined` clears the pin so it inherits again:
+
+```ts
+setPaletteConfig({ baseHue: 60 }); // pin
+setPaletteConfig({ hue: 235 }); // baseHue stays at 60
+setPaletteConfig({ baseHue: undefined }); // inherit again → 235
+```
+
+`getPaletteConfig()` resolves everything, which loses that distinction — it cannot
+tell you whether `80` was chosen or inherited. `getPaletteConfigInput()` returns the
+sparse config as set, which is what a settings UI needs to render an inherited value
+as inherited and offer a way back:
+
+```ts
+const pinned = getPaletteConfigInput().baseHue !== undefined;
+```
+
+Pinning a field to the value it already inherited resolves to the same colors but
+still counts as a change, so a UI reading the sparse config re-renders. Re-applying
+an *already pinned* value is a true no-op and costs nothing.
+
+## Palette playground
+
+Drag the brand hue and watch the accent ramp, the neutral surfaces, the buttons,
+the borders and the shadows move together. Nothing re-renders: every color in the
+kit compiles to a CSS custom property, so re-seeding replaces a single rule on
+`body` and the browser repaints.
+
+Two things worth noticing while you tune:
+
+- The **neutral** surfaces carry saturation factors of 0.10–0.175, so they read
+  as a faint tint of the brand hue. That is where the saturation seed is
+  legible — the solid accents hide it.
+- The **syntax** colors do not move at all — they are their own theme with their
+  own seed, so neither the accent hue nor the saturation reaches them.
+
+## Status themes
+
+Each status theme is a Glaze `extend()` of the default theme with its own hue, so
+tuning one moves only its own `#<theme>-*` family.
+
+## Contrast level
+
+By default contrast is a two-tier switch: normal colors plus a separate
+high-contrast set, selected by `<html data-contrast="high">` or a
+`prefers-contrast: more` preference.
+
+A manual `contrastLevel` replaces both tiers with a single 0–100 slider. Because
+the level already carries the contrast preference, **no separate high-contrast
+variant is emitted** — which means `data-contrast="high"` and
+`prefers-contrast: more` stop having any effect while a level is set. Levels `0`
+and `100` reproduce the normal and high-contrast palettes bit for bit, so the
+slider is a continuous interpolation between exactly what the two tiers ship
+today.
+
+That is a real accessibility trade-off: leave `contrastLevel` at `'auto'` unless
+you are giving users their own contrast control.
+
+## Theme builder
+
+The `Theme Builder` story puts the whole config behind controls and renders the
+result into a single region: pick **Auto / Light / Dark** and **Auto / Normal /
+High** and the preview shows exactly that variant while the page around it stays
+as it is. `Auto` is resolved from the document — a flat token value cannot mean
+"follow the OS", so the story reads `<html data-schema>` / `data-contrast` with the
+matching media query as a fallback, the same two sources `Root` uses.
+
+The preview deliberately shows all three surface levels with their own text ramps
+(`#surface-text`, `#surface-2-text`, `#surface-3-text`), because a theme that looks
+fine on the page surface can fall apart two panels deep.
+
+## Previewing a theme in a region
+
+`setPaletteConfig()` re-themes the whole document, which is no use for a theme
+picker — you want several themes visible at once, or a dark preview inside a light
+page. `renderColorTokens()` does that: it resolves the palette for **one** config
+and **one** scheme and returns flat literal values, ready to apply to a subtree
+through a tasty `tokens` prop.
+
+```tsx
+import { renderColorTokens, tasty } from '@cube-dev/ui-kit';
+
+const Region = tasty({ styles: { fill: '#surface', color: '#surface-text' } });
+
+const preview = useMemo(
+  () => renderColorTokens({ hue: 210, scheme: 'dark' }),
+  [],
+);
+
+<Region tokens={preview}>…everything in here renders in that theme…</Region>;
+```
+
+The reason this needs its own API: the document palette emits **state maps**
+(`{ '': …, '@dark': …, '@hc': … }`), so a page can only ever show one scheme at a
+time — that is what `@dark` means. Collapsing the palette to a chosen scheme
+removes the conditionality, so several themes can coexist.
+
+| Option | Meaning |
+| --- | --- |
+| every `PaletteConfig` field | merged over the **current** config, so `{ scheme: 'dark' }` previews the active theme in dark |
+| `scheme` | `'light'` (default) or `'dark'` |
+| `highContrast` | resolve that scheme's high-contrast variant. Default `false` |
+
+Nothing is applied globally — the live palette and the stored config are
+untouched, so previews are safe to render anywhere.
+
+Notes:
+
+- Real components work inside a region. Every color in the kit compiles to a CSS
+  custom property, so overriding those properties on one element re-colors its
+  whole subtree with no scheme attribute and no second `<Root>`.
+- The legacy aliases come along **by reference** (`'#dark': '#surface-text'`), and
+  so do the shadow tokens and scrollbar colors, whose values embed a palette
+  color. Tasty re-declares them on the region so each `var()` resolves against the
+  region's own values; resolving them up front would freeze them to the outer
+  theme instead.
+- Typography, spacing, sizes and layout are **not** included — nothing in their
+  values references a color, so the region inherits them from `<Root>`.
+- `contrastLevel` works per region, so the whole 0–100 ramp can be shown at once —
+  something a document cannot do, since it is only ever at one level. Level `0`
+  reproduces the normal tier and `100` the high-contrast tier exactly, in both
+  schemes. Because a manual level leaves no separate high-contrast tier,
+  `highContrast: true` correctly returns the same colors as the normal variant.
+  Note that tokens carrying a contrast *floor* (most text) can sit still over part
+  of the ramp — the floor is solved, not approximated, so the value only moves once
+  the interpolated target does. Tokens positioned by a plain tone pair, like
+  `#border`, step at every level.
+- Resolving a palette costs a few milliseconds. The last config is memoized, but
+  `useMemo` on the caller side if you drive it from state.
+
+`renderPaletteTokens()` is the same thing without the aliases and companion
+tokens, if you want only the Glaze palette.
+
+## Reading and reacting to the config
+
+```tsx
+import {
+  DEFAULT_PALETTE_CONFIG,
+  getPaletteConfig,
+  resetPaletteConfig,
+  setPaletteConfig,
+  subscribePaletteConfig,
+  usePaletteConfig,
+} from '@cube-dev/ui-kit';
+
+// In React — `useState`-style, and re-renders on change.
+const [palette, setPalette] = usePaletteConfig();
+
+// Outside React.
+getPaletteConfig(); // every field resolved to a concrete value
+subscribePaletteConfig(() => {
+  /* … */
+});
+```
+
+`getPaletteConfig()` always returns the fully resolved form, so
+`getPaletteConfig().themes.danger.saturation` is a number even if nobody ever set
+it. `DEFAULT_PALETTE_CONFIG` is the shipped baseline in the same shape.
+
+## `<Root palette>`
+
+`<Root>` accepts the same config as a prop, applied during render so the first
+paint is already correct:
+
+```tsx
+<Root palette={{ hue: userAccentHue }}>
+  <App />
+</Root>
+```
+
+This is a convenience wrapper over `setPaletteConfig()`, not a separate scope.
+**The palette is process-global** — Glaze's own config is, and so is the single
+`body` rule the tokens are injected into. One palette per process, not per tree
+and not per request:
+
+- Two `<Root>`s with different `palette` props will fight over the same tokens.
+- Under SSR, apply the palette in code that runs on **both** server and client.
+  A client-only `setPaletteConfig` disposes and replaces the server-rendered
+  token block on the first render, which is visible as a flash. Per-request
+  palettes are not supported.
+
+## Caveats
+
+**`pastel: true` is a redesign, not a filter.** It changes every resolved color.
+The per-color saturation factors in this palette were tuned for the non-pastel
+space — pastel equalizes chroma across hues, so a pastel palette on the shipped
+seeds resolves more saturated than you may expect. Re-tune the seeds alongside
+it.
+
+**Re-seeding costs about 10 ms.** Rebuilding the eight themes and re-solving
+~156 tokens across four scheme variants is not free, though it is inside a frame.
+A manual `contrastLevel` is cheaper, since it skips both high-contrast passes.
+Setting the config to a value it already holds is free — it does not even bump
+the version. If you are driving it from a slider, let the input coalesce to
+frames (a pointer-driven `onChange` already does) rather than writing on every
+event.
+
+**If you call Glaze directly, tell the kit.** `glaze.configure({ darkTone })` and
+friends invalidate Glaze's own caches, but the kit's token maps are memoized
+against the palette config version:
+
+```ts
+import { glaze, invalidatePaletteTokens } from '@cube-dev/ui-kit';
+
+glaze.configure({ darkDesaturation: 0.2 });
+invalidatePaletteTokens(); // only needed once the kit is already mounted
+```
+
+`contrastLevel` is the one field the kit writes to Glaze's global config, and it
+only ever does so if you asked for a level. A host that sets its own
+`glaze.configure({ contrastLevel })` and never passes `contrastLevel` here keeps
+it.
+
+**Some things are not tunable at all.** Tasty locks its configuration on the
+first style injection, so the `@dark` / `@hc` state definitions and the
+`colorSpace` (both set in `Root`) are fixed for the lifetime of the page. Only
+token *values* stay mutable — which is all re-seeding needs.
+
+## See also
+
+- [Colors](./Colors.md) — how to pair surfaces with
+  foregrounds, and what each token family is for.
+- [Usage](./Usage.md) — the full token reference.

package/docs/Usage.md

@@ -94,6 +94,8 @@ All color tokens use `#name` syntax in styles. Opacity variants use `#name.NN` (
 
 The palette is generated by [`@tenphi/glaze`](https://github.com/tenphi/glaze) (see `src/tokens/palette.ts`). Every color token is emitted as a state map with `light`, `@dark`, and `@hc` (high-contrast) variants, so the entire UI Kit adapts to dark / high-contrast schemes automatically.
 
+The seeds it is generated from — brand hue, saturation, per-status hues, `pastel`, `contrastLevel` — are tunable at runtime. See [Theming](./Theming.md).
+
 ### Color Schemes
 
 The `@dark` and `@hc` predefined states are wired up in `src/components/Root.tsx` to support both an attribute opt-in and the user's system preference:
@@ -156,10 +158,12 @@ In the `default` theme these tokens are unprefixed (`#accent-surface`). In color
 
 ### Themed Surfaces
 
-Each colored theme (`primary`, `purple`, `success`, `danger`, `warning`, `note`) also provides its own tinted `<theme>-surface` (banner / chip background) and `<theme>-surface-text` (banner text):
+Each colored theme (`primary`, `purple`, `success`, `danger`, `warning`, `note`) also provides its own tinted `<theme>-surface` (banner / chip background) and `<theme>-surface-text` (banner text).
+
+The hues below are the *defaults*; each is tunable at runtime (see [Theming](./Theming.md)).
 
-| Group | Hue | Purpose |
-|-------|-----|---------|
+| Group | Default hue | Purpose |
+|-------|-------------|---------|
 | `#primary-*` / `#purple-*` | 280.3° | Primary actions, brand color |
 | `#success-*` | 156.9° | Success states, confirmations |
 | `#danger-*` | 23.1° | Errors, destructive actions |
@@ -168,6 +172,29 @@ Each colored theme (`primary`, `purple`, `success`, `danger`, `warning`, `note`)
 
 For example, a success banner uses `fill: '#success-surface'` + `color: '#success-surface-text'`, while a primary button uses `fill: '#primary-accent-surface'` + `color: '#primary-accent-surface-text'`.
 
+### Runtime Theming
+
+`setPaletteConfig()` re-seeds the palette after the kit has mounted; every token re-resolves and `<Root>` re-injects the token block. No component re-render is involved, because every color compiles to a CSS custom property.
+
+```ts
+import { resetPaletteConfig, setPaletteConfig } from '@cube-dev/ui-kit';
+
+setPaletteConfig({ hue: 210, themes: { danger: { hue: 12 } } });
+resetPaletteConfig();
+```
+
+Also available: `getPaletteConfig()`, `subscribePaletteConfig()`, the `usePaletteConfig()` hook, a `<Root palette={…}>` prop, `DEFAULT_PALETTE_CONFIG`, and `invalidatePaletteTokens()` for when you drive `glaze.configure(...)` yourself after mount. The palette is process-global — one palette per process, not per tree or per request.
+
+To theme a *region* instead of the document — a theme preview, or a dark panel inside a light page — use `renderColorTokens()`. It resolves one config and one scheme to flat values you apply via a `tokens` prop, without touching the live palette:
+
+```tsx
+<Block tokens={renderColorTokens({ hue: 210, scheme: 'dark' })} fill="#surface">
+  …
+</Block>
+```
+
+Full contract, caveats and a live playground: [Theming](./Theming.md).
+
 ### Legacy Aliases
 
 The previous token names continue to work as aliases (defined at the bottom of `src/tokens/colors.ts`). New code should prefer the Glaze tokens, but existing components do not need to be migrated:

package/docs/components/Root.md

@@ -13,6 +13,7 @@ The root application wrapper. Provides theme context, global styles, portal cont
 - **`navigation`** `NavigationAdapter` — Custom navigation adapter for routing
 - **`tracking`** `TrackingProps` — Analytics/tracking event configuration
 - **`tokens`** `Record<string, string>` — Custom design tokens (CSS custom properties)
+- **`palette`** `PaletteConfig` — Tune the generated color palette: brand `hue` / `saturation`, per-status theme seeds, `pastel`, `contrastLevel`. Applied during render, so the first paint is already correct. A convenience wrapper over `setPaletteConfig()` — the palette is process-global, not per tree. See [Theming](../Theming.md)
 - **`fonts`** `boolean` — Whether to load default fonts
 - **`font`** `string` — Custom font family name
 - **`monospaceFont`** `string` — Custom monospace font family name

package/docs/glaze/api.md

@@ -10,6 +10,7 @@ Full reference for every public method, option, and type exported by `@tenphi/gl
   - [DTCG Resolver-Module](#themedtcgresolveroptions)
   - [Tailwind CSS](#themetailwindoptions)
 - [High-contrast pairs](#high-contrast-pairs)
+- [Manual contrast level](#manual-contrast-level)
 - [Color definitions](#color-definitions)
   - [Dark seed](#dark-seed-darkhue--darksaturation)
 - [Standalone color tokens](#standalone-color-tokens)
@@ -408,6 +409,144 @@ promotion for that color.
 
 ---
 
+## Manual contrast level
+
+`contrastLevel` turns contrast from a two-tier switch into a `0–100` slider.
+It is a config field, so it works globally, per theme, per token, and through
+`extend()`:
+
+```ts
+glaze.configure({ contrastLevel: 60 });
+const theme = glaze(280, 80, { contrastLevel: 60 });
+glaze.color('#26fcb2', { contrastLevel: 60 });
+```
+
+| Value            | Meaning                                                              |
+| ---------------- | -------------------------------------------------------------------- |
+| `'auto'`         | Default. The two-tier model: normal variants plus a high-contrast tier. |
+| `0`              | Normal contrast, with **no** high-contrast tier.                      |
+| `100`            | The high-contrast scheme as the only scheme.                          |
+| anything between | Resolved *at* that level.                                            |
+
+Levels `0` and `100` reproduce the classic `light` / `dark` and
+`lightContrast` / `darkContrast` output **bit for bit**.
+
+### What the level interpolates
+
+Exactly the three things that make a high-contrast variant differ from its
+normal counterpart:
+
+| Mechanism                                                                    | At level `L`                                                             |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Authored `HCPair`s — `tone`, `contrast`, shadow `intensity`, mix `value`      | the two ends are interpolated                                            |
+| The tone-window bypass                                                       | each endpoint moves toward the full range: light `10→0`, dark `15→0 / 95→100` |
+| Contrast escalation — `AA → AAA`, APCA `+15 Lc`                              | the two numeric targets are interpolated (`AA` at level 50 solves for 5.75) |
+
+The interpolated values are then fed through the ordinary resolve, so a
+contrast floor at any level is **solved**, not approximated, and `autoFlip`
+decides once per level.
+
+Everything that does not vary by high contrast today — hue, saturation,
+`darkDesaturation`, `opacity`, `pastel` — is unaffected by the level.
+
+### Un-interpolable tone pairs switch at 50
+
+Two ends of different kinds have no midpoint, because blending them would
+change *which* resolution rule applies partway up the ramp. These switch from
+the normal entry to the high-contrast one at level 50:
+
+```ts
+tone: [50, 'max']; // absolute vs. extreme
+tone: [50, '+20']; // absolute vs. relative
+tone: ['max', 'min']; // opposite extremes
+```
+
+Same-kind pairs (`[30, 20]`, `['-6', '-12']`, `{ wcag: [4.5, 7] }`,
+`[{ apca: 60 }, { apca: 90 }]`) interpolate smoothly.
+
+A `contrast` pair may **not** switch metric — `[4.5, { apca: 75 }]` throws. A
+WCAG ratio and an APCA Lc are different scales, so no target exists between
+them, and even in `'auto'` mode the two variants would be incomparable. Pair
+values inside one metric instead: `{ wcag: [4.5, 7] }` or `{ apca: [60, 90] }`.
+
+### A color never swaps sides mid-slider
+
+[`autoFlip`](#autoflip) decides per solve, and its tie-break — when both
+directions meet the floor, take the one nearer the authored tone — depends on
+the target. Along a ramp of targets that criterion shifts, so a naive
+implementation lets a color leap across its own base as the slider moves.
+
+Under a manual level the side is instead decided once, from the nearer
+endpoint's target, and preferred at every level in that half of the ramp.
+Consequences:
+
+- A color whose two ends land on the same side of its base **never** changes
+  side, at any level.
+- A color whose ends genuinely disagree — no single side can satisfy both its
+  normal and its high-contrast floor — changes side exactly once, at level 50,
+  the same place un-interpolable tone pairs switch.
+- Flipping is not disabled, only re-ordered, so a side that physically cannot
+  reach the requested contrast still falls back to the opposite one. The floor
+  is met at every level.
+
+The underlying solver option is `preferInitial` on
+[`findToneForContrast`](#contrast-solver), should you need the same behavior
+directly.
+
+### High-contrast output
+
+A manual level already carries the contrast preference, so there is no second
+tier to emit:
+
+- `resolve()` still returns four variants, but `lightContrast` / `darkContrast`
+  **mirror** `light` / `dark`.
+- A **global** level turns high-contrast output off outright, so
+  `tokens()` / `tasty()` / `json()` / `dtcg()` / `dtcgResolver()` / `tailwind()`
+  emit no high-contrast tier. `modes.highContrast` goes inert — it reads as
+  "emit a separate high-contrast set *when* contrast is automatic" — so leaving
+  `highContrast: true` set in a build config while a user switches their
+  preference from auto to manual is fine, and silent.
+- `css()` always returns four strings and ignores `modes`, so its
+  `lightContrast` / `darkContrast` strings repeat the normal declarations —
+  an existing `@media (prefers-contrast: more)` block keeps matching the base
+  block as the level changes, with nothing to rewire.
+- A level on a **single theme or token** does not change which modes are
+  emitted. Sibling themes in a palette keep their real high-contrast tier, and
+  the manual one reports its own resolved values there.
+
+### 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
+slider.oninput = () => {
+  glaze.configure({ contrastLevel: slider.valueAsNumber });
+  apply(theme.css());
+};
+```
+
+Because a manual level skips the two high-contrast passes, a manual resolve is
+also half the work of an `'auto'` one.
+
+### Clearing it, exporting it, base links
+
+- **`configure()` never clears a field by omission.** Pass `'auto'` explicitly
+  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()`) is authored intent and is written to the snapshot;
+  a level merely inherited from the global config is a live user preference and
+  is left out, so a restored theme still follows the current slider. This
+  matches how `modes` and `states` are treated.
+- **Set the level globally, or on both sides of a base link.** A per-token level
+  on a dependent but not on its base anchors the two at different levels — the
+  same caveat as a per-instance `lightTone` override.
+
+`resolveContrastForLevel(spec, level, polarity?)` is exported for advanced use;
+see [Contrast solver](#contrast-solver).
+
+---
+
 ## Color definitions
 
 `ColorDef` is a discriminated union:
@@ -490,7 +629,7 @@ type ContrastSpec =
   | number // bare WCAG ratio
   | ContrastPreset // named WCAG preset
   | { wcag: HCPair<number | ContrastPreset> }
-  | { apca: HCPair<number> }; // APCA Lc target
+  | { apca: HCPair<number | ApcaPreset> }; // APCA Lc target
 ```
 
 | Preset        | WCAG ratio |
@@ -1553,6 +1692,7 @@ glaze.configure({
     alphaMax: 0.6,
     bgHueBlend: 0.2,
   },
+  contrastLevel: 'auto', // or 0–100 for a manual contrast slider
 });
 ```
 
@@ -1565,16 +1705,17 @@ boundaries, not the tone transfer.
 
 | Field                 | Default                                | Description                                                                                                                                                                                                                                                                                                                                                                                                               |
 | --------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `lightTone`           | `[10, 100]`                            | Light scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC.                                                                                                                                                                                                                                                                                                                  |
-| `darkTone`            | `[15, 95]`                             | Dark scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC.                                                                                                                                                                                                                                                                                                                   |
+| `lightTone`           | `[10, 100]`                            | Light scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC; widened continuously by [`contrastLevel`](#manual-contrast-level).                                                                                                                                                                                                                                                |
+| `darkTone`            | `[15, 95]`                             | Dark scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC; widened continuously by [`contrastLevel`](#manual-contrast-level).                                                                                                                                                                                                                                                 |
 | `darkDesaturation`    | `0.1`                                  | Saturation reduction in dark scheme (0–1).                                                                                                                                                                                                                                                                                                                                                                                |
 | `states.dark`         | `'@media(prefers-color-scheme: dark)'` | State alias for dark mode tokens ([Tasty](https://tasty.style) export). Defaults to a media query so tokens react to the OS preference without registering custom states.                                                                                                                                                                                                                                                                        |
 | `states.highContrast` | `'@media(prefers-contrast: more)'`     | State alias for HC tokens ([Tasty](https://tasty.style) export).                                                                                                                                                                                                                                                                                                                                                                                 |
 | `modes.dark`          | `true`                                 | Include dark variants in exports.                                                                                                                                                                                                                                                                                                                                                                                         |
-| `modes.highContrast`  | `false`                                | Include HC variants.                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `modes.highContrast`  | `false`                                | Include HC variants. Inert while a global [`contrastLevel`](#manual-contrast-level) is set — a manual level has no separate HC tier, so this reads as "emit HC variants when contrast is automatic".                                                                                                                                                                                                                                                                                   |
 | `shadowTuning`        | `undefined`                            | Default tuning for all shadow colors. Per-color tuning merges field-by-field.                                                                                                                                                                                                                                                                                                                                             |
 | `autoFlip`            | `true`                                 | Default for each color's `autoFlip`. When solving `contrast` (or applying a relative `tone` that overshoots `[0, 100]`), allow crossing to the opposite side instead of clamping. With `false`, only the requested direction is considered; unmet contrasts pin the tone to that direction's extreme (and emit a warning) and overshooting offsets clamp to the boundary. Override per color via [`autoFlip`](#autoflip). |
 | `inferRole`           | `true`                                 | Infer each color's [`role`](#roles) from its name when no explicit `role` is set. Set to `false` to opt out of name-based inference (the base-opposite and foreground-default fallbacks still apply).                                                                                                                                                                                                                     |
+| `contrastLevel`       | `'auto'`                               | Manual contrast level, `0`–`100`, replacing the two-tier high-contrast model with a slider. `0` reproduces the normal output and `100` the high-contrast output, bit for bit. See [Manual contrast level](#manual-contrast-level).                                                                                                                                                                                          |
 
 | Method                    | Description                                                                         |
 | ------------------------- | ----------------------------------------------------------------------------------- |
@@ -1582,7 +1723,7 @@ boundaries, not the tone transfer.
 | `glaze.getConfig()`       | Snapshot the current resolved config (shallow copy).                                |
 | `glaze.resetConfig()`     | Reset to defaults (also bumps the version counter).                                 |
 
-Themes and standalone color tokens keep a sparse local `GlazeConfigOverride` and merge the live global at resolve time for omitted fields. Authoring `.export(override?)` freezes the effective merge at call time; restored instances pin that freeze. `pastel` is instance-only (theme/token override or per-color) — not set via `configure()`.
+Themes and standalone color tokens keep a sparse local `GlazeConfigOverride` and merge the live global at resolve time for omitted fields. Authoring `.export(override?)` freezes the effective merge at call time; restored instances pin that freeze. `pastel` is instance-only (theme/token override or per-color) — not set via `configure()`. `contrastLevel` is the one field the freeze treats as a live preference: only an instance-authored level is written to the snapshot ([why](#two-rules-worth-knowing)).
 
 ---
 
@@ -1604,9 +1745,12 @@ palette.tokens({ modes: { dark: true, highContrast: true } });
 
 Resolution priority (highest first):
 
-1. Per-call `modes` option on `tokens` / `tasty` / `json`.
-2. `glaze.configure({ modes })` — global config.
-3. Built-in default: `{ dark: true, highContrast: false }`.
+1. A global [`contrastLevel`](#manual-contrast-level) — pins
+   `highContrast: false`, since a manual level leaves no separate high-contrast
+   tier to emit. `highContrast` is inert while it is set.
+2. Per-call `modes` option on `tokens` / `tasty` / `json`.
+3. `glaze.configure({ modes })` — global config.
+4. Built-in default: `{ dark: true, highContrast: false }`.
 
 ---
 
@@ -1621,6 +1765,7 @@ available result.
 | Condition                                           | Behavior                                                                                                 |
 | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
 | `contrast` without `base` in a **theme** color      | Validation error                                                                                         |
+| `contrast` pair switching metric (`[4.5, { apca: 75 }]`) | Validation error — a WCAG ratio and an APCA Lc are different scales                                  |
 | Relative `tone` without `base` in a **theme** color | Validation error                                                                                         |
 | `contrast` without `base` in `glaze.color()`        | Anchors against the literal seed (no error)                                                              |
 | Relative `tone` without `base` in `glaze.color()`   | Anchors against the literal seed (no error)                                                              |
@@ -1732,6 +1877,7 @@ import {
   findToneForContrast,
   findValueForMixContrast,
   resolveContrastForMode,
+  resolveContrastForLevel,
   resolveMinContrast,
   apcaContrast,
 } from '@tenphi/glaze';
@@ -1742,6 +1888,7 @@ import {
 | `findToneForContrast(opts)`                                       | Binary-search for the tone (0–1) that meets a contrast floor (WCAG or APCA) against a base color. Returns `{ tone, contrast, met, branch, flipped? }`.                                                                                                                                                                                                                                 |
 | `findValueForMixContrast(opts)`                                   | Same, but searches for a mix `value` (0–1) that meets a contrast floor between a base and a target.                                                                                                                                                                                                                                                                                    |
 | `resolveContrastForMode(spec, isHC, polarity?, outerExplicitHC?)` | Resolves a `ContrastSpec` to `{ metric: 'wcag' \| 'apca', target }` for the requested mode (picks the normal or HC entry of any pair). In HC, applies the metric's auto-enhancement unless `outerExplicitHC` is set or the inner metric pair carries an explicit HC value: APCA +15 Lc (clamped to 106); WCAG AA → AAA / AA-large → AAA-large (AAA-family and bare numbers unchanged). |
+| `resolveContrastForLevel(spec, level, polarity?)`                  | Resolves a `ContrastSpec` — including its outer `[normal, highContrast]` pair — at a [manual contrast level](#manual-contrast-level) (0–100), interpolating the two numeric targets. Levels 0 / 100 delegate verbatim to `resolveContrastForMode`; a WCAG-vs-APCA metric switch across the pair has no midpoint and switches at 50.                                                        |
 | `resolveMinContrast(value)`                                       | Resolves a `MinContrast` (WCAG preset or number) to a numeric ratio.                                                                                                                                                                                                                                                                                                                   |
 | `apcaContrast(yText, yBg)`                                        | APCA Lc magnitude (0–106) for two relative luminances.                                                                                                                                                                                                                                                                                                                                 |
 
@@ -1761,5 +1908,6 @@ Exported constants: `APCA_PRESETS`, `APCA_HC_ENHANCEMENT` (`15`, the Enhanced Le
 | `maxIterations`    | `18`                 | Max binary-search iterations per branch.                                                                                                                                                               |
 | `initialDirection` | higher-contrast side | Direction to search first (`'lighter'` or `'darker'`).                                                                                                                                                 |
 | `flip`             | `false`              | When `true`, try the opposite direction if the initial one doesn't meet the target. When `false`, only the initial direction is searched — unmet contrasts pin the result to that direction's extreme. |
+| `preferInitial`    | `false`              | With `flip` on and **both** directions meeting the target, keep `initialDirection` instead of taking whichever result lands nearer `preferredTone`. Makes the chosen side independent of the target — what [`contrastLevel`](#manual-contrast-level) uses to keep a color on one side of its base across the ramp. The flip fallback is unaffected. |
 
 Result: `{ tone, contrast, met, branch: 'lighter' | 'darker' | 'preferred', flipped? }`. `flipped: true` indicates the initial direction failed and the opposite direction satisfied the target.