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

package/docs/contrast.mdx

@@ -0,0 +1,702 @@
+---
+title: Contrast solving
+description: Give a color a WCAG or APCA floor against its base and Glaze finds the tone that meets it in every scheme.
+---
+
+import { Callout } from '@tenphi/cookbook/components';
+import ContrastExample from '../docs-site/components/contrast/ContrastExample.astro';
+import TokenExample from '../docs-site/components/contrast/TokenExample.astro';
+
+Tone deltas space colors evenly; a **contrast floor** guarantees that a pair is
+readable. Give a color a `base` and a `contrast` spec, and Glaze measures the
+pair in light, dark, and both high-contrast schemes, then moves the color's
+tone only when the measurement falls short.
+
+```ts
+theme.colors({
+  surface: { tone: 97 },
+  'surface-text': {
+    base: 'surface',
+    tone: '-60',
+    contrast: 'AA',
+  },
+});
+```
+
+The floor is a minimum, not a target: a color that already clears it keeps its
+authored tone. Use tone for the relationship you want and `contrast` as the
+safety net under it. The tone can be a delta from the base or an absolute tone:
+a `base` with an absolute `tone` is a valid way to get a contrast guarantee
+without a tone relationship.
+
+## Floors at a glance
+
+Each text color below asks for a soft tone, `'-20'` from the surface, and lets
+its floor decide how far to move. The numbers are measured from the resolved
+colors in the scheme you are viewing; switch the site's appearance to see the
+other three.
+
+<ContrastExample
+  hue={280}
+  saturation={80}
+  colors={{
+    surface: { tone: 97, saturation: 0.1 },
+    'aa-text': { base: 'surface', tone: '-20', saturation: 0.4, contrast: 'AA' },
+    'aaa-text': { base: 'surface', tone: '-20', saturation: 0.4, contrast: 'AAA' },
+    'content-text': {
+      base: 'surface',
+      tone: '-20',
+      saturation: 0.4,
+      contrast: { apca: 'content' },
+    },
+    'body-text': {
+      base: 'surface',
+      tone: '-20',
+      saturation: 0.4,
+      contrast: { apca: 'body' },
+    },
+    'preferred-text': {
+      base: 'surface',
+      tone: '-20',
+      saturation: 0.4,
+      contrast: { apca: 'preferred' },
+    },
+  }}
+  rows={['aa-text', 'aaa-text', 'content-text', 'body-text', 'preferred-text']}
+  caption="Each row is measured against surface in the active scheme. The first number is the floor's own metric; tone is the color's resolved tone (0–100)."
+/>
+
+Compare the WCAG and APCA rows across light and dark: the two metrics disagree
+most about light text on a dark background, which is why the choice of metric
+matters.
+
+## WCAG and APCA
+
+Glaze solves two metrics. Pick one per color.
+
+### WCAG 2 ratios
+
+The WCAG 2 contrast ratio compares the relative luminance of two colors on a
+scale from `1:1` to `21:1`. It is symmetric: swapping text and background gives
+the same ratio. A bare number or a preset name means WCAG.
+
+| Preset        | Ratio | Use                                      |
+| ------------- | ----- | ---------------------------------------- |
+| `'AA-large'`  | 3     | Large or bold text (WCAG SC 1.4.3)       |
+| `'AA'`        | 4.5   | Body text (WCAG SC 1.4.3)                |
+| `'AAA-large'` | 4.5   | Large or bold text, enhanced (SC 1.4.6)  |
+| `'AAA'`       | 7     | Body text, enhanced (SC 1.4.6)           |
+
+### APCA lightness contrast
+
+APCA (the Accessible Perceptual Contrast Algorithm) reports a lightness
+contrast, Lc, from 0 to about 106. It models how text actually reads, so it is
+**polarity-aware**: dark text on a light background and light text on a dark
+background score differently for the same pair of colors. Glaze takes the
+magnitude and needs to know which color is the text; see
+[Roles and APCA polarity](#roles-and-apca-polarity).
+
+| Preset        | Lc  | Use                                                   |
+| ------------- | --- | ----------------------------------------------------- |
+| `'preferred'` | 90  | Preferred body and column text                        |
+| `'body'`      | 75  | Minimum for body and column text                      |
+| `'content'`   | 60  | Readable non-body content (about WCAG AA)             |
+| `'large'`     | 45  | Large or bold headlines, fine icons and outlines      |
+| `'non-text'`  | 30  | Solid icons and controls, placeholder or disabled text |
+| `'min'`       | 15  | Dividers and decoration; APCA's point of invisibility |
+
+The presets are APCA's Bronze Simple Mode conformance levels and do not depend
+on the role. You can also pass a raw Lc number.
+
+### Which one to use
+
+- Prefer **APCA presets** for text, icons, and other content when perceptual
+  readability is the goal: `contrast: { apca: 'content' }`, or with an explicit
+  high-contrast step, `contrast: { apca: ['content', 'body'] }`.
+- Use **WCAG** when compliance, policy, or a migration requires a WCAG ratio:
+  `contrast: 4.5`, `contrast: 'AAA'`, `contrast: { wcag: [4.5, 7] }`.
+- Add a floor only where readability or recognizability needs a measured
+  guarantee. Low-stakes relationships — surface ladders, hover steps, subtle
+  fills — read better as tone deltas than as fake contrast floors.
+
+## Writing a contrast spec
+
+```ts
+type ContrastPreset = 'AA' | 'AAA' | 'AA-large' | 'AAA-large';
+type ApcaPreset =
+  | 'preferred'
+  | 'body'
+  | 'content'
+  | 'large'
+  | 'non-text'
+  | 'min';
+type HCPair<T> = T | [T, T];
+
+type ContrastSpec =
+  | number // WCAG ratio
+  | ContrastPreset // WCAG preset
+  | { wcag: HCPair<number | ContrastPreset> }
+  | { apca: HCPair<number | ApcaPreset> };
+
+// On a regular or mix color:
+// contrast?: HCPair<ContrastSpec>;
+```
+
+`HCPair<T>` is either one value for every scheme or a
+`[normal, highContrast]` pair. The pair can wrap the whole spec or sit inside
+the metric:
+
+```ts
+contrast: 4.5; // WCAG 4.5
+contrast: 'AAA'; // WCAG 7
+contrast: { wcag: 6 }; // WCAG 6
+contrast: [4.5, 7]; // WCAG 4.5 normal / 7 high contrast
+contrast: { wcag: [4.5, 7] }; // the same pair, inside the metric
+contrast: { apca: 60 }; // Lc 60 normal / 75 high contrast (automatic)
+contrast: { apca: 'content' }; // the same, by preset
+contrast: { apca: [45, 60] }; // Lc 45 / 60 high contrast (explicit)
+contrast: { apca: ['content', 'body'] }; // Lc 60 / 75 (explicit)
+```
+
+A WCAG number below 1 is treated as 1, and a negative APCA number uses its
+magnitude.
+
+Two definitions are rejected before anything resolves:
+
+- `contrast` without `base` on a theme color — there is nothing to measure
+  against:
+  `glaze: color "text" has "contrast" without "base".`
+- A pair that switches metric, such as `[4.5, { apca: 75 }]`. A ratio and an Lc
+  are different scales, so Glaze cannot pick between them or interpolate them.
+  The error starts with
+  `glaze: color "text" has a "contrast" pair that switches metric (wcag → apca).`
+  and suggests the fix: use one metric for both entries, e.g.
+  `{ wcag: [4.5, 7] }`.
+
+Every form, preset, and escalation rule is listed in the API reference under
+[Contrast and high contrast](./reference/contrast.md).
+
+## How the solver finds a tone
+
+For each scheme, Glaze resolves the base first, then the dependent color:
+
+1. **Preferred tone.** The color's authored tone is placed for this scheme and
+   clamped into the scheme's [tone window](./schemes.mdx#tone-windows). An
+   absolute tone is mapped through the scheme. A tone delta is applied to the
+   base's tone in that scheme, except in dark under the default
+   `mode: 'auto'`: there it is applied to the base's light tone and the result
+   is inverted and remapped like an absolute tone, so the dark step is about
+   0.87× the delta on a light base and uneven on lower ones; high contrast
+   keeps it exact
+   ([How relative tone adapts](./schemes.mdx#how-relative-tone-adapts)). With
+   no `tone`, the color starts at the base's own tone.
+2. **Keep it if it passes.** The pair is measured with the chosen metric. If
+   it clears the floor (with a small safety margin), the preferred tone is the
+   result.
+3. **Search one side.** Otherwise the solver searches on the side the authored
+   tone points to: darker when the preferred tone is below the base, lighter
+   when it is above. A color with no tone of its own starts on whichever side
+   reaches higher contrast. For WCAG, the search starts from the gray tone that
+   gives exactly the ratio — tone is contrast-uniform for neutrals, so this
+   seed is closed-form — and a binary search along tone then measures the real,
+   chromatic color. The passing tone nearest the preferred one wins.
+4. **Cross over if needed.** With [`autoFlip`](#autoflip-crossing-to-the-other-side)
+   on (the default), the opposite side is searched too.
+
+The solver aims slightly above the target — 1% over a WCAG ratio, 0.5 Lc over
+an APCA target — so rounding in the output formats cannot push the final color
+under the floor. Measured values therefore sit at or just above the floor, and
+a chromatic color can land a little higher when the gray seed already clears it.
+
+<ContrastExample
+  hue={280}
+  saturation={80}
+  colors={{
+    surface: { tone: 97, saturation: 0.1 },
+    'muted-text': {
+      base: 'surface',
+      tone: '-30',
+      saturation: 0.4,
+      contrast: 'AA',
+    },
+    'strong-text': {
+      base: 'surface',
+      tone: '-85',
+      saturation: 0.4,
+      contrast: 'AA',
+    },
+  }}
+  rows={['muted-text', 'strong-text']}
+  compare="unsolved"
+  caption="“Without the floor” is the same theme with contrast removed. muted-text is moved only as far as AA requires; strong-text already clears it and keeps its authored tone."
+/>
+
+The preferred tone is clamped into the scheme's tone window, but the search
+covers the full `0–100` tone range. A demanding floor can therefore push a color
+past the window edge — for example, dark-scheme text that needs a very high Lc.
+
+<Callout kind="note">
+Tone is exactly contrast-uniform only for neutrals. Because the solver measures
+the actual chromatic color, a saturated color still meets its floor; it just
+ends at a different tone than a gray would. See
+[Tone and OKHST](./okhst.mdx) for the model behind this.
+</Callout>
+
+## autoFlip: crossing to the other side
+
+Sometimes the authored side cannot reach the floor at all — a light label on a
+mid-tone button, for instance. `autoFlip` decides what happens then:
+
+- **On (default):** the solver also searches the opposite side of the base and
+  takes the passing tone nearest the preferred one. The light label becomes a
+  dark one.
+- **Off:** only the authored side is searched. When it falls short, the color
+  pins to that side's extreme (tone `0` or `100`) and Glaze warns.
+
+<ContrastExample
+  hue={280}
+  saturation={80}
+  colors={{
+    button: { tone: 68, saturation: 0.6 },
+    'button-label': { base: 'button', tone: '+25', contrast: 'AA' },
+    'button-label-pinned': {
+      base: 'button',
+      tone: '+25',
+      contrast: 'AA',
+      autoFlip: false,
+    },
+  }}
+  rows={['button-label', 'button-label-pinned']}
+  scheme="light"
+  sample="Publish"
+  caption="Light scheme. Both labels are authored lighter than the button. With autoFlip the first crosses to the darker side to meet AA; the pinned one stays on the lighter side and misses it. In dark the scheme inverts the authored direction, so the two swap sides."
+/>
+
+The same switch governs **tone-delta overshoot**. When `base + delta` falls
+outside `0–100`, `autoFlip` mirrors the delta to the other side of the base
+(`'+30'` on a tone-90 surface becomes `'-30'`) instead of clamping at the
+boundary. If the mirrored tone is also out of range, the original delta is
+kept and clamped on the authored side.
+
+```ts
+theme.colors({
+  surface: { tone: 90 },
+  // '+30' overshoots 100: mirrored to '-30'
+  raised: { base: 'surface', tone: '+30' },
+  // clamped at 100 instead
+  'raised-pinned': {
+    base: 'surface',
+    tone: '+30',
+    autoFlip: false,
+  },
+});
+```
+
+Set it per color, per theme, or globally:
+
+```ts
+// one color
+theme.colors({
+  'fill-label': { base: 'fill', contrast: 'AA', autoFlip: false },
+});
+
+// one theme
+const strict = glaze(280, 80, { autoFlip: false });
+
+// every theme and token
+glaze.configure({ autoFlip: false });
+```
+
+Use `autoFlip: false` when a color must stay on its side of the base — a
+tone delta that should never cross over, or an unmet floor you would rather
+see pinned to one extreme. A mix color has no per-color field; it follows the
+theme's (or global) `autoFlip`.
+
+`autoFlip` is unrelated to dark-mode inversion. A color swapping ends between
+light and dark is its [adaptation mode](./schemes.mdx#adaptation-modes) at
+work; `autoFlip` only reverses a delta or a contrast search around the base.
+
+When both sides pass, "nearest wins" can pick a different side as the target
+grows. Under a [manual contrast level](#manual-contrast-level), Glaze therefore
+decides the side once per half of the slider, so a color changes side at most
+once, at level 50, instead of jumping back and forth.
+
+## Roles and APCA polarity
+
+APCA is asymmetric — the Lc of `a` on `b` differs from `b` on `a` — so Glaze
+needs to know which of the pair is the foreground. A color's **role** decides
+it. WCAG is symmetric and ignores roles.
+
+| Role (polarity)          | Name keywords                                                     |
+| ------------------------ | ----------------------------------------------------------------- |
+| `'text'` (foreground)    | `text`, `fg`, `foreground`, `content`, `ink`, `label`, `stroke`   |
+| `'border'` (foreground)  | `border`, `divider`, `outline`, `separator`, `hairline`, `rule`   |
+| `'surface'` (background) | `surface`, `bg`, `background`, `fill`, `canvas`, `paper`, `layer` |
+
+A foreground color — text, icons, and other content, or a border, divider, or
+outline — is measured as text over its base. A surface color — a background or
+fill — is measured as the background, with its base as the text on top.
+
+Below, two colors share one definition. The only difference is the name:
+`accent-text` resolves as text and `accent-fill` as a surface, so the solver
+measures them in opposite directions and lands on different tones.
+
+<ContrastExample
+  hue={280}
+  saturation={80}
+  colors={{
+    surface: { tone: 97, saturation: 0.1 },
+    'accent-text': { base: 'surface', tone: '-30', contrast: { apca: 'body' } },
+    'accent-fill': { base: 'surface', tone: '-30', contrast: { apca: 'body' } },
+  }}
+  rows={['accent-text', 'accent-fill']}
+  scheme="light"
+  showRole
+  caption="Light scheme, where the difference is largest. accent-text is drawn as text on surface; accent-fill as a fill with surface on top. Lc is measured in the direction each role implies; roles swapped is the Lc the same pair would score used the other way round."
+/>
+
+### How a role is chosen
+
+For each color, the first rule that applies wins:
+
+1. An explicit `role` (a role name or any keyword above as an alias).
+2. Inference from the color's name, when `inferRole` is on (the default). The
+   name is split on non-alphanumerics and camelCase humps, and the **last**
+   recognized keyword wins: `button-text` is text, `input-bg` is a surface,
+   `card-outline` is a border.
+3. The opposite of the base's role: a color on a surface is text; a color on
+   text or a border is a surface.
+4. `'text'` — the base is treated as the background.
+
+```ts
+const theme = glaze(280, 60);
+
+theme.colors({
+  surface: { tone: 90 },
+  // role 'text', from the name
+  text: { base: 'surface', contrast: { apca: 'content' } },
+  // role 'border', from the name
+  border: { base: 'surface', tone: '-10' },
+  // a fill with no keyword in its name would resolve as text
+  // (rule 3), so set the role explicitly
+  badge: {
+    base: 'surface',
+    contrast: { apca: 'content' },
+    role: 'surface',
+  },
+});
+```
+
+<Callout kind="tip" title="Name the pair">
+A root color with no keyword in its name resolves as `'text'` (rule 4), so a
+dependent of it that also has no keyword resolves as `'surface'` (rule 3). If
+`brand` is a fill and `on-brand` is its label, name them `brand-fill` /
+`brand-label`, or set `role` explicitly.
+</Callout>
+
+Turn name inference off with `glaze.configure({ inferRole: false })` or per
+theme with `glaze(hue, saturation, { inferRole: false })`; rules 1, 3, and 4
+still apply. Shadows and glows always resolve as surfaces. Mix colors take the
+same chain and the same `role` field. Good token names do double duty: they
+describe the palette and give APCA the right polarity without any `role`
+fields.
+
+## High contrast
+
+High-contrast variants (`lightContrast`, `darkContrast`) escalate the floor
+automatically, so most colors need no high-contrast entry at all:
+
+| Authored floor                     | Normal | High contrast                    |
+| ---------------------------------- | ------ | -------------------------------- |
+| `'AA'`                             | 4.5    | 7 (`'AAA'`)                      |
+| `'AA-large'`                       | 3      | 4.5 (`'AAA-large'`)              |
+| `'AAA'`, `'AAA-large'`             | as is  | unchanged — already the top tier |
+| a bare WCAG number                 | as is  | unchanged — no successor tier    |
+| any APCA target                    | Lc     | Lc + 15, capped at 106           |
+| an explicit pair, outer or inner   | first  | second — no escalation           |
+
+The WCAG step follows the spec's own Enhanced level (SC 1.4.3 → SC 1.4.6). The
+APCA step is the Lc analog of AAA over AA. An explicit high-contrast value, in
+either the outer `contrast` pair or the inner `wcag` / `apca` pair, replaces the
+automatic step. Use one to hold a ceiling: for large or bold text, where APCA
+caps useful contrast at Lc 90 to avoid glare, `{ apca: ['preferred', 'preferred'] }`
+keeps high contrast at Lc 90 instead of boosting it past the cap.
+
+The automatic step can also outrun what a surface allows. An escalated
+`'preferred'` becomes Lc 105, which dark text reaches only on a surface within
+about a tone of white. On an off-white or tinted surface it pins to black and
+warns in `lightContrast` — the `preferred-text` row in
+[Floors at a glance](#floors-at-a-glance) does this. Give it an explicit,
+reachable high-contrast entry there, such as `{ apca: [90, 95] }`.
+
+High-contrast variants also ignore the [tone windows](./schemes.mdx#tone-windows): both the
+placement and the search use the full `0–100` range, which gives the escalated
+floors room to land.
+
+<ContrastExample
+  hue={280}
+  saturation={80}
+  colors={{
+    surface: { tone: 97, saturation: 0.1 },
+    'aa-text': { base: 'surface', tone: '-20', saturation: 0.4, contrast: 'AA' },
+    'large-text': {
+      base: 'surface',
+      tone: '-20',
+      saturation: 0.4,
+      contrast: 'AA-large',
+    },
+    'aaa-text': { base: 'surface', tone: '-20', saturation: 0.4, contrast: 'AAA' },
+    'ratio-text': { base: 'surface', tone: '-20', saturation: 0.4, contrast: 4.5 },
+    'content-text': {
+      base: 'surface',
+      tone: '-20',
+      saturation: 0.4,
+      contrast: { apca: 'content' },
+    },
+    'explicit-text': {
+      base: 'surface',
+      tone: '-20',
+      saturation: 0.4,
+      contrast: { apca: ['content', 'content'] },
+    },
+  }}
+  rows={[
+    'aa-text',
+    'large-text',
+    'aaa-text',
+    'ratio-text',
+    'content-text',
+    'explicit-text',
+  ]}
+  compare="hc"
+  caption="Normal and high-contrast variants of each color, in your current light or dark setting. The floor shown is the one the solver used for that variant."
+/>
+
+Any other value that takes an `HCPair` — `tone`, shadow and glow `intensity`,
+mix `value` — can tighten the high-contrast variant the same way; see
+[High-contrast pairs](./schemes.mdx#high-contrast-pairs).
+
+### Manual contrast level
+
+With [`contrastLevel`](./reference/contrast.md#manual-contrast-level) set to a number, the normal
+variants solve for a target between the normal and high-contrast floors. Both
+ends are resolved with the rules above first, so `'AA'` ramps from 4.5 at level
+`0` to 7 at level `100`, and an explicit pair ramps between its two entries. A
+pair that switches metric has no midpoint, which is one reason validation
+rejects it. Under a level, the side of the base a color sits on is decided once
+per half of the ramp, so it changes side at most once — at level 50 — instead of
+jumping back and forth. The high-contrast variants are not affected by the
+level. The concept is covered in
+[Light, dark, and high contrast](./schemes.mdx#manual-contrast-level); the full
+rules are in
+[Contrast and high contrast](./reference/contrast.md#manual-contrast-level).
+
+## When a floor can't be met
+
+Some floors are physically out of reach. A mid-gray badge has no tone of text
+that reaches 7:1 — not black, not white. When neither side passes, the color
+pins to the extreme of the side it searched first, and Glaze warns.
+
+<ContrastExample
+  hue={0}
+  saturation={0}
+  colors={{
+    badge: { tone: 50 },
+    'badge-text': { base: 'badge', contrast: 'AAA' },
+    'badge-text-light': { base: 'badge', tone: '+10', contrast: 'AAA' },
+  }}
+  rows={['badge-text', 'badge-text-light']}
+  scheme="light"
+  caption="Light scheme. Neither color can reach 7:1 on a mid-gray badge. badge-text has no tone of its own, so it starts on the stronger side; badge-text-light keeps its authored direction and pins to that side's extreme. In dark the inverted '+10' points darker, so both pin to black."
+/>
+
+The side matters: the solver pins to the side it searched first, even when the
+other extreme would get closer. A color with no tone of its own starts on the
+stronger side; a color with an authored direction keeps that direction.
+
+The warning names the color, the scheme, the target, and what was reached:
+
+```text
+glaze: color "badge-text" cannot meet WCAG 7.00 in light scheme
+  (got 4.94).
+Try widening the tone window, lowering the contrast target, or picking a
+  base color further from this color's tone.
+```
+
+It fires when the result is more than 2% under a WCAG target or more than
+1.5 Lc under an APCA target. Each distinct warning prints once per session (the
+dedupe cache holds 256 entries and starts over when full), so a dev server that
+re-resolves a theme on every change does not flood the console. For a
+standalone `glaze.color()`, pass `name` so the warning says which token it is.
+
+To fix one:
+
+- **Lower the target**, or give the high-contrast variant an explicit, reachable
+  entry: `contrast: ['AA', 'AA']` instead of letting AA escalate to AAA.
+- **Move the base** further from the middle of the tone range.
+- **Widen the tone window** when the normal scheme is clamping the base.
+  High-contrast variants already use the full range.
+
+### Chromatic drift advisory
+
+After every scheme is resolved, Glaze re-measures each regular color that has a
+floor against its base in that metric and emits an advisory when the measured value
+is under the target by the same margin:
+
+```text
+glaze: color "badge-text" drifts below WCAG 7.00 in light scheme
+  (measured 4.94).
+Chromatic luminance differs from the gray tone; nudge the tone or
+  saturation if the floor matters.
+```
+
+It is a safety net for the gap between tone and a chromatic color's real
+luminance. Because the solver itself measures the chromatic color, you will
+mostly see this advisory next to a "cannot meet" warning for the same color and
+scheme rather than on its own. The model behind it is in
+[Tone and OKHST](./okhst.mdx#the-drift-check).
+
+### Contrast and opacity
+
+A color with both `contrast` and `opacity` resolves, but Glaze warns:
+
+```text
+glaze: color "text" has both "contrast" and "opacity".
+Opacity makes perceived tone unpredictable.
+```
+
+The floor is solved for the opaque color; what the reader sees depends on what
+shows through. For a translucent color with a floor, use a
+[transparent mix](./mixes.mdx#transparent-mix), whose solver models the
+browser's compositing.
+
+## Literal colors with a floor
+
+A [`from`](./reference/color-definitions.md#from) color reproduces an exact value in
+the light, normal-contrast scheme. A floor on it is still a floor: a value that
+already clears it is emitted untouched, and one that misses moves only as far as
+the floor requires. Dark and high contrast adapt as usual, and the floor is
+solved in each of them.
+
+<ContrastExample
+  hue={280}
+  saturation={80}
+  colors={{
+    surface: { tone: 100, saturation: 0.12 },
+    brand: { from: '#2f5bff', base: 'surface', contrast: 3 },
+    sky: { from: '#7cc8ff', base: 'surface', contrast: 3 },
+  }}
+  rows={['brand', 'sky']}
+  compare="unsolved"
+  sample={{ brand: 'Brand', sky: 'Sky' }}
+  caption="In light, brand already clears 3:1 on white and keeps its exact value; sky does not, so it darkens just enough."
+/>
+
+A `from` color works as a base like any other color. Here the label is solved
+against whatever the brand resolves to in each scheme:
+
+```ts
+theme.colors({
+  surface: { tone: 100, saturation: 0.12 },
+  brand: { from: '#2f5bff', base: 'surface', contrast: 3 },
+  'brand-label': {
+    base: 'brand',
+    tone: 100,
+    contrast: 'AA-large',
+  },
+});
+```
+
+## Pairing standalone colors
+
+[`glaze.color()`](./reference/color-tokens.md) tokens use the same solver. Give
+a token a `base` — another token, or a raw color value that Glaze wraps with
+`glaze.color(value)` — and its `contrast` is solved against the base's resolved
+variant in every scheme.
+
+<TokenExample
+  base="#1a1a2e"
+  color={{ from: '#ffffff', contrast: 'AA' }}
+  caption="White text paired with a dark navy token, measured in the active scheme. In dark, the navy base inverts and the text follows it."
+/>
+
+With a `base`:
+
+- `contrast` is solved per scheme against the base's `light`, `dark`,
+  `lightContrast`, and `darkContrast` variants.
+- A tone delta (`tone: '+N'` / `'-N'`) is measured from the base. Under the
+  default `mode: 'auto'`, the dark variant is derived from the base's light
+  tone, so the step flips direction and comes out about 0.87× the delta on
+  every base. A token's base has no light-window lift, so unlike a theme color
+  ([How relative tone adapts](./schemes.mdx#how-relative-tone-adapts)) the dark
+  step is even. A relative `hue` still anchors to the token's own seed value.
+- Pairs chain: a paired token can be the base of the next one.
+
+```ts
+const page = glaze.color('#ffffff');
+const button = glaze.color({
+  from: '#1e40af',
+  base: page,
+  contrast: 3,
+  name: 'button-fill',
+});
+const label = glaze.color({
+  from: '#ffffff',
+  base: button,
+  contrast: 'AA',
+  name: 'button-label',
+});
+```
+
+In light all three keep their exact values, since each already clears its floor.
+In dark they invert, and the label is solved against the inverted button.
+
+Without a `base`, a token's `contrast` (and a tone delta) is measured
+against the token's own literal value, held fixed in every scheme. Base
+resolution timing, structured-base linking, and the `name` label are covered in
+[Color tokens](./reference/color-tokens.md#pairing-colors).
+
+## Contrast on mixes
+
+Mix colors take the same `contrast` field. Instead of a tone, the solver adjusts
+the mix ratio of an opaque mix or the opacity of a transparent one, against the
+mix's `base`:
+
+```ts
+theme.colors({
+  tint: {
+    type: 'mix',
+    base: 'surface',
+    target: 'accent',
+    value: 10,
+    contrast: 'AA',
+  },
+  overlay: {
+    type: 'mix',
+    base: 'surface',
+    target: 'accent',
+    value: 5,
+    blend: 'transparent',
+    contrast: 3,
+  },
+});
+```
+
+Both `value` and `contrast` accept `[normal, highContrast]` pairs. When even the
+pure target can't meet the floor, the mix settles at the pure target. A `value`
+of 100 has no room above, so it falls back to the pure base instead, and a
+transparent mix ends at alpha 0; that includes a high-contrast entry of 100, as
+in `value: [80, 100]`. Either way the mix resolves **without a warning**; the
+drift advisory skips mixes too. Measure a mix yourself when its floor matters. See
+[Contrast on mixes](./mixes.mdx#contrast-on-mixes).
+
+## Using the solver directly
+
+The solver is exported for tools that work outside a theme:
+`findToneForContrast`, `findValueForMixContrast`, `resolveContrastForMode`,
+`resolveContrastForLevel`, `resolveMinContrast`, `resolveApcaTarget`,
+`apcaContrast`, and the constants `APCA_PRESETS`, `APCA_HC_ENHANCEMENT` (15),
+and `APCA_MAX_LC` (106). The role helpers — `normalizeRole`,
+`inferRoleFromName`, `roleToPolarity`, `oppositeRole` — are exported too. Their
+signatures and options are in the API reference under
+[Utilities](./reference/utilities.md#contrast-solver).