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

package/docs/migration.md

@@ -0,0 +1,278 @@
+---
+title: Migration and upgrading
+description: Move an existing color system to Glaze without renaming tokens, and upgrade between major Glaze versions.
+---
+
+This page covers two kinds of move: bringing an existing CSS, design-token, or
+application color system over to Glaze, and upgrading Glaze itself across a
+major version. For designing a palette from scratch, see
+[Designing a palette](./methodology.mdx); for choosing an export shape and
+wiring it into your app, see [Exporting and integration](./exporting.mdx).
+
+## Migrating from an existing color system
+
+The fastest path is **map first, design second**. Get every existing token name
+producing a Glaze-resolved color (even a rough first pass), wire the new
+palette in, then iterate on the resolved colors without touching component
+code.
+
+### 1. Inventory the existing tokens
+
+Walk your current color system and put every token into one of these buckets:
+
+- **Surfaces**: backgrounds, panels, cards, banners.
+- **Surface text**: body text, headings, captions, labels.
+- **Borders, dividers, focus rings**: neutral structural lines.
+- **Brand fills**: solid CTA backgrounds, badges, status banners.
+- **Brand foregrounds**: link text, status text, icon colors on neutral
+  backgrounds.
+- **Disabled**: disabled chip and its label.
+- **Shadows and overlays**: elevation and state layers (`shadow` / `glow`),
+  and fixed-alpha overlays such as scrims (`opacity`).
+- **One-off colors**: syntax highlighting, charts, illustrations.
+
+Each bucket maps onto one of the patterns in
+[Designing a palette](./methodology.mdx). The bucket decides the _shape_ of the
+Glaze definition (root or dependent, `mode: 'auto'` or `'fixed'`, a contrast
+floor or an absolute tone), not its value.
+
+### 2. Reproduce the existing values
+
+Pick a definition shape that lands the new color _close to_ the legacy value in
+light mode. [Designing a palette](./methodology.mdx) explains the shape per
+bucket; the [Color definitions](./reference/color-definitions.md) reference
+covers the levers (`tone`, `saturation`, `contrast`, `mode`, `hue`).
+
+Three tactics make matching easier:
+
+- **Anchor strong text at the edge** instead of solving for `'AAA'`. The
+  contrast solver stops at the floor, which usually leaves text noticeably
+  softer than the legacy value: on a white surface, a neutral
+  `contrast: 'AAA'` (7:1) solves to tone 36, while a legacy `#1a1a1a` sits at
+  tone 6.2 (17.4:1). An absolute `tone` preserves the look, but author it a
+  little below the measured value: the light
+  [tone window](./schemes.mdx#tone-windows) lifts authored tones (tone 0
+  renders at about 5, tone 2 at 6.9), so a neutral `tone: 1.3` renders
+  `#1a1a1a`. With `lightTone: false` on the theme, light tones render exactly
+  as authored.
+- **Match the metric the old system actually used.** Numeric WCAG ratios are
+  useful when you reproduce a measured legacy ratio. For new content roles,
+  prefer the APCA presets from the methodology. For low-stakes spacing, use a
+  tone delta instead of inventing a contrast target. See
+  [Contrast solving](./contrast.mdx).
+- **Pin values that are a contract with `from`.** A brand color you must honor
+  can be given as a literal: `{ from: '#2f5bff' }` reproduces that exact value
+  in the light scheme whatever the theme's seed saturation, while dark and high
+  contrast still adapt. Add `base` and `contrast` when it must stay legible
+  against something. See [`from`](./reference/color-definitions.md#from).
+
+### 3. Keep the old token names
+
+Use a custom `prefix` map (and [alias themes](./exporting.mdx#alias-themes-for-legacy-names)
+if needed) so the names your components already consume keep working:
+
+```ts
+// Old: components consume `#dark`, `#dark-02`, `#dark-03`.
+// New: define them in Glaze, map the prefix so they emit unchanged.
+
+defaultTheme.colors({
+  dark: { base: 'surface', tone: 2, saturation: 0.475 },
+  'dark-02': {
+    base: 'surface',
+    tone: '-1',
+    saturation: 0.375,
+    contrast: [9, 11],
+  },
+  'dark-03': {
+    base: 'surface',
+    tone: '-1',
+    saturation: 0.24,
+    contrast: [4.5, 5.5],
+  },
+});
+
+palette.tasty({ prefix: { default: '' } });
+// → '#dark', '#dark-02', '#dark-03': components don't change.
+```
+
+Once consumers are off the legacy names, rename the Glaze tokens to match your
+conventions. [Prefix map strategies](./exporting.mdx#prefix-map-strategies)
+shows every naming option with real output.
+
+### 4. Verify dark mode and high contrast before promoting
+
+Glaze gives you light, dark, and high contrast for free, but only the light
+scheme was matched against the legacy palette. Before you promote the
+migration:
+
+- Spot-check every surface, text, accent, and disabled pair in dark mode. The
+  tone inversion plus the per-color `mode` can produce results that look right
+  in light but feel off in dark. The usual fixes: switch a brand color to
+  `mode: 'fixed'`, or anchor a foreground to `surface` instead of the brand
+  fill (see [adaptation modes](./schemes.mdx#adaptation-modes) and
+  [Designing a palette](./methodology.mdx)).
+- If the legacy system had no high-contrast mode, audit the high-contrast
+  variants Glaze emits. Wherever the resolved contrast is too low or a color
+  blows out, add a `[normal, highContrast]` pair (`tone: ['-7', '-20']`,
+  `contrast: [4.5, 7]`, and so on).
+- Run real screens, not just the token grid. The interaction of several Glaze
+  tokens against each other (text on a chip, a hover background against its
+  fill, a disabled label on a disabled chip) is where mismatches show up.
+
+### 5. Trim what `extend()` doesn't need
+
+After the migration, mark every default-only token (borders, shadows, glows,
+the disabled chip, code highlighting, and so on) `inherit: false`. Colored
+sibling themes created with `extend()` only need the accent and tinted-surface
+chain; flagging the rest cuts the token set each theme emits dramatically.
+
+## Upgrading Glaze
+
+### 3.0 — shadows and glows
+
+`shadow` was rebuilt so `intensity` produces the same visible change on every
+surface, and `glow` was added as its mirror. Both emit a translucent pigment
+whose opacity is solved, per surface and per scheme, so the composite lands an
+exact **tone step** away from `bg`: darker for `shadow`, lighter for `glow`.
+See [Shadows and glows](./shadows-and-glows.mdx).
+
+What changed:
+
+- **`intensity` is a tone step.** In 2.x it went through a `tanh` curve in
+  OKHSL lightness, so the same number darkened white by 9 tones, a tone-35
+  surface by 13.9, and a tone-6 surface by 4.4. Now `intensity: 10` is 10 tones
+  on every surface with 10 tones of room. A step past black (or white, for a
+  glow) is pinned to the strongest composite the pigment reaches, and Glaze
+  warns; see [Unreachable steps](./shadows-and-glows.mdx#unreachable-steps).
+- **`fg` is the object, not a contrast reference.** In 2.x, strength scaled
+  with `|l_bg − l_fg|` and the docs pointed `fg` at `text`, which ran opposite
+  to the physics: a white card on a light surface got almost no shadow. Now
+  `fg` is the element casting the shadow; a darker object deepens it, a lighter
+  one softens it, and an object at the surface's tone (or no `fg`) gives
+  exactly `intensity`.
+- **The pigment is neutral by default**: pure black for `shadow`, pure white
+  for `glow`. The surface keeps its hue and the output is clean: `intensity: 10`
+  on a white surface emits `rgb(0 0 0 / 0.1326)`, which composites to tone 90.
+- **The `ShadowTuning` fields were replaced.** `saturationFactor`,
+  `maxSaturation`, `lightnessFactor`, `lightnessBounds`, `minGapTarget`,
+  `alphaMax`, and `bgHueBlend` are gone. The new knobs are `objectInfluence`,
+  `tint`, `reach`, and `hueBleed`, shared by `shadowTuning` and the new
+  `glowTuning`. The type is now `LightingTuning`; `ShadowTuning` and
+  `GlowTuning` remain as aliases of it.
+- **`GLAZE_EXPORT_VERSION` is 2.** A version-1 theme or palette snapshot that
+  contains shadow colors or a `shadowTuning` now throws on restore instead of
+  silently re-rendering every shadow.
+- **`ColorDef` has a fourth member, `GlowColorDef`.** Exhaustive `switch`es
+  over `def.type` need a `'glow'` branch.
+
+How 2.x shadows map onto 3.0 (2.x steps measured with browser compositing):
+
+| 2.x definition | 2.x step for `intensity: 10` | 3.0 equivalent |
+| --- | --- | --- |
+| No `fg`, light surface (tone 97–100) | ≈ 9 tones | `intensity: 9`, or keep `10` (a tone stronger) |
+| No `fg`, mid surface (tone 50) | ≈ 13.6 tones | `intensity: 13.6`, or settle on one value for all surfaces |
+| No `fg`, dark surface (tone 10) | ≈ 7.6 tones, and saturating | `intensity: 7.6`; dark shadows were weaker than authored and now aren't |
+| `fg: 'text'` on a light surface | ≈ 7 tones | Drop `fg` and use `intensity: 7`, or point `fg` at the element and re-tune |
+| `fg` = a near-white card on light | ≈ 0.3 tones (barely visible) | `fg: 'card'`, then pick `intensity` for the look you want |
+
+Then:
+
+1. Replace `fg: 'text'` (or any contrast-reference `fg`) with either no `fg` or
+   the element that casts the shadow.
+2. Pick `intensity` as the number of tones you want. For a ladder, `4` / `8` /
+   `12` reads as evenly spaced on every surface with room for the deepest step.
+   Check the dark schemes: a white `auto` page sits at about tone 9 in dark and
+   at tone 0 in dark high contrast. Shadows on it deeper than about `8`–`9` (a
+   saturated page has a little less room) pin to black and warn in dark, and
+   every shadow on it stays transparent and warns in dark high contrast. Use
+   glows for dark elevation, on a surface that also leaves them room in light
+   ([Dark-mode elevation](./shadows-and-glows.mdx#dark-mode-elevation)). Leaving
+   a shadow token out of the dark schemes hides the pinned result but not the
+   warning: every color resolves in all four schemes.
+3. Delete the old fields inside `tuning` / `shadowTuning` (`saturationFactor`,
+   `alphaMax`, …); TypeScript flags them. A tinted pigment is
+   `tuning: { tint: 0.3, reach: 0.85 }`. There is no opacity cap: lower
+   `intensity` for a lighter overlay.
+4. Replace hand-tuned translucent white mixes (dark-mode elevation, edge
+   highlights, lightening state layers) with
+   `{ type: 'glow', bg, intensity }`. Direction is fixed per type, so a
+   `shadow` darkens and a `glow` lightens in light and dark alike. A glow on a
+   white light-mode surface has nothing to lighten and warns.
+5. Re-export snapshots. A 2.x snapshot with shadows or a `shadowTuning` throws
+   on restore, so re-author it. In code, rebuild the theme with 3.0 shadow defs
+   and call `export()`. In the JSON, fix the shadow defs, drop
+   `config.shadowTuning`, and set `version` to `2` (a palette snapshot has one at
+   the top and one per theme), then load it and export again. Snapshots without
+   shadows load unchanged.
+
+`glaze.shadow()` keeps its signature with the new semantics, and `glaze.glow()`
+takes the same input. See
+[`glaze.shadow()` / `glaze.glow()`](./reference/utilities.md#glazeshadowinput--glazeglowinput).
+
+### 2.0 — `format*` takes 0–1
+
+The `format*` writers (`formatOkhsl`, `formatOkhst`, `formatRgb`, `formatHsl`,
+`formatOklch`) used to take `s` / `l` / `t` on a 0–100 percentage scale, while
+everything that _produces_ those values (`resolve()`, `variantToOkhsl`,
+`srgbToOkhsl`, `oklabToOkhsl`, `okhslToSrgb`) returns them on 0–1. Composing
+the two, which is the obvious thing to do, was off by 100x and failed
+silently: `0.7` is a legal percentage, so you got a valid CSS string naming the
+wrong (near-black) color.
+
+The writers now take the 0–1 factors, so the whole library speaks one scale.
+Drop the `* 100`:
+
+```diff
+- formatOkhsl(v.h, v.s * 100, l * 100);
++ formatOkhsl(v.h, v.s, l);
+
+- formatOkhst(v.h, v.s * 100, v.t * 100);
++ formatOkhst(v.h, v.s, v.t);
+```
+
+Nothing else moves: `h` was always 0–360, `alpha` was always 0–1, and every
+export method (`css()`, `tokens()`, `json()`, `tasty()`, `dtcg()`,
+`tailwind()`, `glaze.format()`) emits the same colors, because they were
+compensating internally. Dropping the redundant `×100 ÷100` round-trip shifts
+float noise by an ULP, which shows up nowhere except the (meaningless) hue term
+of a fully desaturated `hsl()` string. `toTone` / `fromTone` still speak the
+0–100 tone axis the authoring API takes, so divide a tone from them by 100
+before passing it to `formatOkhst`.
+
+A leftover `* 100` is no longer silent: a value above 1 cannot be a factor, so
+the writers `console.warn` once per writer, and you get an obviously broken
+string such as `okhsl(280 7040.68% 5000%)` instead of a plausible wrong color.
+See [format writers](./reference/utilities.md#format-writers).
+
+### 0.14 — `lightness` became `tone`
+
+Colors used to be authored on OKHSL lightness. They are now authored on
+**tone**, a contrast-uniform 0–100 axis (see [Tone and OKHST](./okhst.mdx)):
+
+- The `lightness` prop is gone everywhere (theme colors, `glaze.color()`
+  structured input, tone deltas); use `tone`. Equal tone steps give equal
+  WCAG contrast, so numeric values don't map to the same OKHSL lightness as
+  before. Re-check absolute mid-range values.
+- The config windows `lightLightness` / `darkLightness` became `lightTone` /
+  `darkTone`, and `darkCurve` was removed.
+- `ResolvedColorVariant` stores `{ h, s, t, alpha }` instead of `{ h, s, l }`.
+  Use `variantToOkhsl()` to recover OKHSL lightness.
+- Tone deltas that overshoot `[0, 100]` mirror to the other side of the base
+  by default instead of clamping. Set `autoFlip: false` on the color
+  (or globally) to clamp.
+
+## Common pitfalls
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| A disabled state stops looking disabled in dark mode. | An alpha-tinted overlay on `surface-text` (which inverts) gives asymmetric perceived contrast. | Replace it with an adaptive color anchored to `surface`: a tone delta for visual spacing, or a contrast floor when one is required. See [chips and disabled states](./methodology.mdx#chips-and-disabled-states). |
+| A brand fill turns dark in dark mode and stops reading as the brand. | The default `mode: 'auto'` inverts the tone. | Set `mode: 'fixed'` so the tone is remapped into the dark window, not inverted. See [adaptation modes](./schemes.mdx#adaptation-modes). |
+| Brand text washes out against the dark surface. | The foreground was anchored to `accent-surface` (the brand fill), so contrast was enforced only against that fill, not against the surface it sits on. | Anchor `accent-text` and friends to `surface` with `mode: 'auto'`. |
+| Tokens look right in light but broken in high contrast. | High contrast bypasses the tone window, so absolute tones and deltas land on the full `[0, 100]` range (a white `auto` page is black in dark high contrast), and floors without an explicit high-contrast value rise a tier (`'AA'` → `'AAA'`, APCA +15 Lc). | Add explicit `[normal, highContrast]` pairs to `tone` / `contrast` for the affected tokens. |
+| A tone delta like `'+48'` lands on the _wrong_ (darker) side of its base. | Overshooting tone deltas mirror to the other side of the base by default (a color's `autoFlip` defaults to the global `autoFlip`, which is on). | Set `autoFlip: false` on the color to clamp to the boundary instead, or use `tone: 'max'` / `'min'` to force the extreme. |
+| `palette.tokens()` emits unexpected unprefixed names. | A `primary` was set on the palette (or per call) and duplicates that theme's tokens without a prefix. | Pass `primary: false` to disable it for that export, or change `glaze.palette(themes, { primary })`. See [the `primary` alias](./exporting.mdx#the-primary-alias). |
+| `glaze: token "surface" from theme "danger" collides with theme "default" — skipping.` | Two themes resolved to the same output name under your prefix config. | Adjust the prefix map so each name is unique, or accept first-write-wins. See [Collisions](./exporting.mdx#collisions). |
+| `glaze: formatOkhsl() got a value above 1 …` | Pre-2.0 percentage-scale input to a `format*` writer (a leftover `* 100`). | Pass the 0–1 factors the converters return; see [2.0 — `format*` takes 0–1](#20--format-takes-01). |
+| `glaze: color "X" cannot meet WCAG … in light scheme (got …)` | The contrast target is physically unreachable for the color's hue and saturation against its base. The color pins to the extreme of the side it searched first, which may not be the closer one; see [When a floor can't be met](./contrast.mdx#when-a-floor-cant-be-met). | Lower the floor or change the base. If only the high-contrast schemes fail, give `contrast` an explicit, reachable high-contrast entry (`['AA', 'AA']`). On standalone colors, set `name` so the warning is identifiable; see [`name`](./reference/color-tokens.md#name). |
+| `glaze: shadow "X" cannot reach a 10.0-tone step …` (or `glow`) | The surface has fewer tones of room than `intensity` asks for: a glow on white, a deep shadow on near-black, or any shadow on a light `auto` page in dark high contrast (at or near tone 0 there). The overlay is pinned to its strongest composite (transparent when the surface is already at the pigment's extreme). | Lower `intensity` or give the overlay a surface with room in every scheme, and use glows for dark elevation. Otherwise expect the warning: every color resolves in all four schemes, so not using the token in a scheme doesn't silence it. See [Unreachable steps](./shadows-and-glows.mdx#unreachable-steps). |
+| `glaze.themeFrom: this snapshot is export version 1 (Glaze 2) …` | A 2.x snapshot with shadow colors or `shadowTuning`; shadows changed meaning in 3.0. | Re-author the shadows and export again; see [3.0 — shadows and glows](#30--shadows-and-glows). |

package/docs/mixes.mdx

@@ -0,0 +1,268 @@
+---
+title: Mixes and transparency
+description: Blend two colors into a solid tint or a translucent wash, optionally solved for contrast.
+---
+
+import Example from '../docs-site/components/Example.astro';
+import MixRamp from '../docs-site/components/mixes/MixRamp.tsx';
+import TransparentMix from '../docs-site/components/mixes/TransparentMix.tsx';
+import ContrastMix from '../docs-site/components/mixes/ContrastMix.tsx';
+
+export const washTheme = {
+  hue: 280,
+  saturation: 80,
+  colors: {
+    surface: { tone: 97 },
+    accent: { tone: 45 },
+    'wash-sm': { type: 'mix', base: 'surface', target: 'accent', value: 6, blend: 'transparent' },
+    'wash-md': { type: 'mix', base: 'surface', target: 'accent', value: 15, blend: 'transparent' },
+    'wash-lg': { type: 'mix', base: 'surface', target: 'accent', value: 30, blend: 'transparent' },
+  },
+};
+
+export const contrastTheme = {
+  hue: 280,
+  saturation: 80,
+  colors: {
+    surface: { tone: 95 },
+    accent: { tone: 30 },
+    'accent-border': { type: 'mix', base: 'surface', target: 'accent', value: 20, contrast: 3 },
+    'accent-wash': { type: 'mix', base: 'surface', target: 'accent', value: 4, blend: 'transparent', contrast: 1.25 },
+  },
+};
+
+A mix color blends a `base` color toward a `target` color by `value`, from
+`0` (pure base) to `100` (pure target). An **opaque** mix produces a solid
+color; a **transparent** mix produces the target with an opacity, for the
+browser to composite over the base. Both read `base` and `target` per scheme,
+so they adapt to light, dark, and high contrast automatically.
+
+```ts
+import { glaze } from '@tenphi/glaze';
+
+const theme = glaze(280, 80);
+
+theme.colors({
+  surface: { tone: 95 },
+  accent: { tone: 30 },
+
+  // A solid tint: 30% of the way from surface to accent.
+  'accent-tint': {
+    type: 'mix',
+    base: 'surface',
+    target: 'accent',
+    value: 30,
+  },
+
+  // A translucent wash: accent at 8% opacity, composited over surface.
+  'accent-hover': {
+    type: 'mix',
+    base: 'surface',
+    target: 'accent',
+    value: 8,
+    blend: 'transparent',
+  },
+});
+```
+
+Every field is listed in [Color definitions](./reference/color-definitions.md#mixcolordef).
+
+## Opaque mix
+
+An opaque mix (the default, `blend: 'opaque'`) interpolates between the
+resolved base and target and emits a solid color with alpha 1. `value: 0` is
+the base, `value: 100` is the target. Because base and target are resolved for
+each scheme first, the mix follows them: a tint of the accent over the surface
+in light mode is a tint of the dark-mode accent over the dark-mode surface in
+dark mode.
+
+### Blend space
+
+`space` picks where an opaque mix interpolates:
+
+| `space` | Behavior | Best for |
+| --- | --- | --- |
+| `'okhsl'` (default) | Perceptually uniform OKHSL interpolation: hue, saturation, and lightness each move evenly. | Design token derivation. |
+| `'srgb'` | Linear-light sRGB channel interpolation, like CSS `color-mix(in srgb-linear, …)`. | Physical light mixing. |
+
+The same two colors, mixed at every tenth of the way in each space:
+
+<MixRamp
+  hue={260}
+  saturation={90}
+  colors={{
+    blue: { tone: 40, mode: 'static' },
+    yellow: { tone: 90, hue: 95, mode: 'static' },
+  }}
+  base="blue"
+  target="yellow"
+  caption="Blue (hue 260, tone 40) toward yellow (hue 95, tone 90). Top number: value. Bottom number: the result's tone. OKHSL walks the hue around the wheel through cyan and green; linear sRGB passes through desaturated colors."
+/>
+
+<MixRamp
+  hue={0}
+  saturation={0}
+  colors={{
+    black: { tone: 0, mode: 'static' },
+    white: { tone: 100, mode: 'static' },
+  }}
+  base="black"
+  target="white"
+  caption="Black toward white. OKHSL spaces lightness evenly; linear light gets bright quickly, so most of the ramp sits at high tones."
+/>
+
+### Achromatic colors
+
+When one side of an `okhsl` mix has a saturation of zero (a color defined with
+`saturation: 0`, such as a pure white, black, or gray), its hue carries no
+information, so the mix takes the hue of the color that has saturation. This
+matches the "missing component" behavior of CSS `color-mix()`: a mix from
+such a white toward an accent stays in the accent's hue the whole way instead
+of sweeping through other hues.
+
+Only exactly zero counts. A white or black that keeps any saturation, such as
+`{ tone: 100 }` in a saturated theme, still carries its hue, and a mix toward
+an accent of another hue sweeps between the two. A mix between two
+zero-saturation colors stays gray in either space; the spaces differ only in
+how lightness is spread along the ramp (see black toward white above).
+
+<MixRamp
+  hue={280}
+  saturation={80}
+  colors={{
+    white: { tone: 100, saturation: 0, mode: 'static' },
+    accent: { tone: 40, mode: 'static' },
+  }}
+  base="white"
+  target="accent"
+  spaces={['okhsl']}
+  caption="White toward a hue-280 accent in OKHSL. White has no hue, so every step uses the accent's hue while saturation and lightness move."
+/>
+
+## Transparent mix
+
+With `blend: 'transparent'`, the output is the **target** color (its resolved
+hue, saturation, and tone) with `alpha = value / 100`. Nothing is blended in
+Glaze; the browser composites it over whatever is underneath, which should be
+the `base`.
+
+```ts
+theme.colors({
+  surface: { tone: 95 },
+  black: { tone: 0, saturation: 0 },
+  hover: {
+    type: 'mix',
+    base: 'surface',
+    target: 'black',
+    value: 8,
+    blend: 'transparent',
+  },
+});
+// hover → the resolved `black` with alpha 0.08
+```
+
+The target is resolved like any color first. Here `black` uses the default
+`mode: 'auto'`, so it inverts to a near-white in dark schemes and the same
+`hover` lightens the dark surface instead of darkening it.
+
+`space` is ignored for transparent mixes. Browsers composite `source-over` on
+gamma-encoded sRGB: 50% black over white paints `#808080`, not the `#bcbcbc`
+linear light would give. Glaze's contrast solver for transparent mixes models
+exactly that, so a solved opacity renders at the contrast it was solved for.
+
+<Example {...washTheme} visual="none" />
+
+<TransparentMix
+  {...washTheme}
+  base="surface"
+  show={['wash-sm', 'wash-md', 'wash-lg']}
+  caption="Accent washes over the surface in your current scheme. The big number is the tone step the composite lands; the opacity is value / 100 in every scheme, so the step changes when the surface does."
+/>
+
+A transparent mix keeps the opacity you author. That makes it the right tool
+for a brand-colored wash, but it does not land the same visible step on every
+surface. For an overlay that does, use a
+[`shadow` or `glow`](./shadows-and-glows.mdx), whose opacity is solved per
+surface.
+
+## Contrast on mixes
+
+Mixes take the same `contrast` field as regular colors, with a WCAG ratio or
+preset, or an APCA target (see [Contrast solving](./contrast.mdx)). The floor
+is measured between the mix and its `base`. The solver keeps your `value` when
+it already meets the floor; otherwise it moves the mix ratio (opaque) or the
+opacity (transparent) toward the target until it does, staying as close to
+your `value` as it can.
+
+<Example {...contrastTheme} visual="none" />
+
+<ContrastMix
+  {...contrastTheme}
+  show={['accent-border', 'accent-wash']}
+  caption="Each mix as authored (no floor) and with its floor, over the surface in your current scheme. The big number is the WCAG ratio against the surface; below it, the value or opacity the mix ended up with."
+/>
+
+- Both `value` and `contrast` accept `[normal, highContrast]` pairs, and
+  `value` follows a manual contrast level like other pairs. Contrast presets
+  escalate in high contrast as they do for regular colors
+  ([high contrast](./contrast.mdx#high-contrast)).
+- For APCA floors, `role` sets the polarity of the mix against its `base`,
+  exactly as on a regular color ([roles](./contrast.mdx#roles-and-apca-polarity)).
+- When even the pure target cannot meet the floor, the mix settles at the
+  pure target for any `value` below 100. A `value` of 100 (including a
+  high-contrast entry of 100) has no room above, so it falls back to
+  `value: 0`: the base itself, and a transparent mix vanishes. Keep `value`
+  below 100 when you set a floor. Unlike a regular color, a mix does not warn
+  when its floor is unmet.
+
+## Mix chaining
+
+A mix can use another mix as its `base` or `target`:
+
+<Example
+  hue={0}
+  saturation={0}
+  colors={{
+    white: { tone: 100, saturation: 0 },
+    black: { tone: 0, saturation: 0 },
+    gray: {
+      type: 'mix',
+      base: 'white',
+      target: 'black',
+      value: 50,
+      space: 'srgb',
+    },
+    'gray-light': {
+      type: 'mix',
+      base: 'white',
+      target: 'gray',
+      value: 50,
+      space: 'srgb',
+    },
+  }}
+  scheme="light"
+  caption="Light scheme, where the auto black sits at the light tone window's floor rather than tone 0. gray is halfway from white to black in linear sRGB; gray-light is halfway from white to gray. In dark schemes white and black invert, so the whole chain mirrors."
+/>
+
+A mix **cannot** reference a `shadow` or `glow` color, as `base` or as
+`target`; Glaze throws when the theme resolves. The same restriction applies to
+a regular color's `base`.
+
+Other translucent colors are accepted but lose their alpha. A transparent mix
+or a color with `opacity`, used as a mix's `base` or `target` (or as a shadow's
+`bg`), counts as its opaque color: a mix toward a 10% accent wash comes out the
+same as a mix toward the accent. Chain off opaque colors.
+
+## Mix, shadow, glow, or opacity?
+
+| You want | Use |
+| --- | --- |
+| The same visible darkening or lightening on any surface: state layers, elevation, drop shadows | [`shadow` / `glow`](./shadows-and-glows.mdx) |
+| A solid color part of the way from one color to another | Opaque mix |
+| A translucent color over a known base, such as a brand-colored wash | Transparent mix |
+| A translucent color with a contrast floor against its base | Transparent mix with `contrast` |
+| One fixed alpha everywhere, such as a 50% scrim | A regular color with [`opacity`](./shadows-and-glows.mdx#fixed-opacity) |
+
+Shadows and glows solve opacity for a tone step, transparent mixes keep (or
+solve, with `contrast`) an opacity against their base, and `opacity` is never
+solved.