@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/tokens/color-responsibilities.stories.js

@@ -0,0 +1,227 @@
+import { html } from 'lit';
+import { contrast, docsPage, refSection, resolve } from './story-chrome.js';
+
+export default {
+  title: 'Foundations/Color/Responsibilities',
+  tags : ['autodocs']
+};
+
+/* Measured as the page renders, so a palette change moves the numbers. */
+const ratio = (a, b) => {
+  try {
+    return Math.round(contrast(a, b) * 100) / 100;
+  } catch {
+    return null;
+  }
+};
+
+const chain = (primitive, role, component, ui) => html`
+  <div style="display:flex;flex-wrap:wrap;align-items:center;gap:var(--spacing-8);font-family:var(--typography-fontFamily-mono);font-size:var(--typography-fontSize-xs)">
+    <code>${primitive}</code><span style="color:var(--color-text-muted)">→</span>
+    <code>${role}</code><span style="color:var(--color-text-muted)">→</span>
+    <code>${component}</code><span style="color:var(--color-text-muted)">→</span>
+    <span>${ui}</span>
+  </div>`;
+
+const OWNERS = [
+  ['Text hierarchy', '--color-text-*', 'primary, secondary, muted, subtle, disabled, inverse, muted-inverse'],
+  ['Surfaces', '--color-surface-*', 'default, container, subtle, muted, brand, inverse, info'],
+  ['Borders', '--color-border-*', 'container, subtle, default, strong, brand, disabled, container-inverse'],
+  ['Actions', '--color-action-*', 'primary, -hover, -active; accent ramp for conversion; on-fill, the ink on any of them'],
+  ['Status / feedback', '--status-{tone}-*', 'text, surface, surface-strong (not brand), border, accent, fill, on-fill'],
+  ['Focus', '--focus-outline-*', 'one ring, never a border role'],
+  ['Indicators', '--indicator-*', 'what marks the current item: the tab and nav underline, and the carousel dot']
+];
+
+export const Responsibilities = () =>
+  docsPage({
+    title: 'Colour responsibilities',
+    lede : `Which family owns which job, and how a colour gets from the palette to the screen.
+            Foundations/Surfaces answers "what does this surface mean"; this page answers the
+            question one level up — which vocabulary should you be asking at all.`,
+    note: html`<b>Do not choose a token because its numeric colour is closest to what you
+            want. Choose the role whose responsibility matches the UI.</b><br />
+            Fourteen primitives in this system serve more than one live role, and
+            <code>#006dff</code> alone serves six. A value tells you nothing about a job.`,
+    children: html`
+      ${refSection({
+        name    : 'The chain',
+        meta    : 'primitive → responsibility → component → rendered UI',
+        children: html`
+        <p style="max-width:70ch">
+          Every colour that carries meaning should travel the whole chain. A component reaching
+          straight past the middle is not a style error — it is a missing sentence about what
+          the colour is <i>for</i>, and it is why the same job ends up spelled four ways.
+        </p>
+        <div style="display:grid;gap:var(--spacing-12);background:var(--color-surface-muted);padding:var(--spacing-24);border-radius:var(--radius-lg);overflow-x:auto">
+          ${chain('--color-blue-500', '--color-action-primary', '--button-primary-background-default', 'a primary button')}
+          ${chain('--color-neutral-0', '--color-text-inverse', '(used directly)', 'footer text on the masthead')}
+          ${chain('--color-green-800', '--status-success-text', '(used directly)', 'a "supported" table cell')}
+          ${chain('--color-neutral-300', '--color-text-muted-inverse', '--bd-terminalmsg-subdued', 'terminal dim text')}
+        </div>
+        <p style="max-width:70ch;margin-top:var(--spacing-24)">
+          The middle step is the only one that survives a redesign. Primitives get retuned and
+          components get rewritten; the responsibility is the thing that stays true.
+        </p>`
+      })}
+
+      ${refSection({
+        name    : 'Who owns what',
+        meta    : `${OWNERS.length} families`,
+        children: html`
+        <div class="table-scroll">
+          <table>
+            <caption>Each family answers one question. Reaching into another family's
+              vocabulary is how a status colour ends up meaning "blue".</caption>
+            <thead><tr><th scope="col">Responsibility</th><th scope="col">Family</th><th scope="col">Roles</th></tr></thead>
+            <tbody>
+              ${OWNERS.map(([r, f, roles]) => html`
+                <tr><td><b>${r}</b></td><td><code>${f}</code></td><td>${roles}</td></tr>`)}
+            </tbody>
+          </table>
+        </div>`
+      })}
+
+      ${refSection({
+        name    : 'General vs status',
+        meta    : 'two systems, one seam',
+        children: html`
+        <p style="max-width:70ch">
+          <b>The general <code>--color-*</code> family owns neutral hierarchy, surfaces and
+          actions. The <code>--status-*</code> family owns feedback state.</b> That split was
+          not designed; it is what adoption settled on, and measuring it is how it became a
+          rule. The feedback members of the general family —
+          <code>--color-surface-error</code>, <code>-success</code>, <code>-warning</code> —
+          have no component consumers at all, while their status counterparts have two or
+          three each.
+        </p>
+        <p style="max-width:70ch">
+          <b>They are not deleted, and value equality is not the reason.</b>
+          <code>--color-surface-info</code> and <code>--status-info-surface</code> both resolve
+          to the same tint, and consolidating them would be wrong: <code>bd-highlight</code>
+          uses the first one for decorative emphasis, which is not feedback. Two roles that
+          happen to share a value are still two roles.
+        </p>
+        <p style="max-width:70ch">
+          <code>--color-text-success</code> and <code>--color-text-warning</code> look unused
+          in CSS and are not: <code>shared/token-scales.js</code> exposes them as
+          <code>color="success"</code> and <code>color="warning"</code> on every
+          <code>bd-h</code> and <code>bd-p</code>. Everything in <code>tokens.css</code> also
+          ships to consuming pages, so an unused-looking token may simply have consumers this
+          repository cannot see.
+        </p>`
+      })}
+
+      ${refSection({
+        name    : 'Action vs brand',
+        meta    : 'a ramp, not a colour',
+        children: html`
+        <p style="max-width:70ch">
+          <code>--color-action-primary</code> → <code>-hover</code> → <code>-active</code> is a
+          state ramp. Brand blue is an identity. They overlap in value at the first step and
+          diverge immediately after, which is why "use the brand colour" is not an answer to
+          "what should hover look like".
+        </p>
+        <p style="max-width:70ch">
+          <b>Let the state pick the token.</b> There is no hover-blue role and there should not
+          be one — the question is what the element is doing, not what colour it is going.
+          <code>bd-link</code>'s resting colour is <code>--color-text-brand</code> rather than
+          <code>--color-action-primary</code> deliberately: blue-500 measures
+          ${ratio(resolve('--color-action-primary'), resolve('--color-surface-default')) ?? '—'}:1
+          on white and fails on any tint, so links start one step down the ramp.
+        </p>`
+      })}
+
+      ${refSection({
+        name    : 'Subtle, muted, disabled',
+        meta    : 'two are hierarchy, one is a state',
+        children: html`
+        <div class="table-scroll">
+          <table>
+            <caption>Measured on --color-surface-default as this page renders</caption>
+            <thead><tr><th scope="col">Role</th><th scope="col">Kind</th><th scope="col">On white</th><th scope="col">Use it for</th></tr></thead>
+            <tbody>
+              ${[
+                ['--color-text-secondary', 'hierarchy', 'supporting copy under a title'],
+                ['--color-text-muted', 'hierarchy', 'metadata, captions, timestamps'],
+                ['--color-text-subtle', 'hierarchy', 'the quietest readable step'],
+                ['--color-text-disabled', 'STATE', 'a control the user cannot operate']
+              ].map(([t, kind, use]) => html`
+                <tr>
+                  <td><code>${t.replace('--color-text-', '')}</code></td>
+                  <td>${kind === 'STATE' ? html`<b>${kind}</b>` : kind}</td>
+                  <td class="num">${ratio(resolve(t), resolve('--color-surface-default')) ?? '—'}</td>
+                  <td>${use}</td>
+                </tr>`)}
+            </tbody>
+          </table>
+        </div>
+        <p style="max-width:70ch">
+          <b>Disabled is a state, not a step on the hierarchy.</b> Reaching for a hierarchy role
+          to paint a disabled control makes disabled content indistinguishable from ordinary
+          quiet content, and it is what <code>bd-checkbox</code>, <code>bd-radio</code> and
+          <code>bd-switch</code> currently do. They are left alone on purpose: the value they
+          chose is the <i>more</i> legible one, and correcting the name at the cost of contrast
+          would be the wrong trade. That is a design decision about
+          <code>--color-text-disabled</code>'s value, recorded rather than made here.
+        </p>`
+      })}
+
+      ${refSection({
+        name    : 'Inverse',
+        meta    : 'two steps, and why not three',
+        children: html`
+        <p style="max-width:70ch">
+          On an inverse surface only two text roles exist:
+          <code>--color-text-inverse</code> for high emphasis and
+          <code>--color-text-muted-inverse</code> for everything subordinate. The light-side
+          hierarchy cannot be reused — <code>-secondary</code>, <code>-muted</code> and
+          <code>-subtle</code> measure
+          ${ratio(resolve('--color-text-secondary'), resolve('--color-surface-inverse')) ?? '—'},
+          ${ratio(resolve('--color-text-muted'), resolve('--color-surface-inverse')) ?? '—'} and
+          ${ratio(resolve('--color-text-subtle'), resolve('--color-surface-inverse')) ?? '—'}
+          against <code>--color-surface-inverse</code>.
+        </p>
+        <div style="background:var(--color-surface-inverse);padding:var(--spacing-24);border-radius:var(--radius-lg);max-width:52ch">
+          <p style="margin:0 0 var(--spacing-8);color:var(--color-text-inverse)">
+            High emphasis — <code>--color-text-inverse</code>,
+            ${ratio(resolve('--color-text-inverse'), resolve('--color-surface-inverse')) ?? '—'}:1
+          </p>
+          <p style="margin:0;color:var(--color-text-muted-inverse);font-size:var(--typography-fontSize-sm)">
+            Subordinate — <code>--color-text-muted-inverse</code>,
+            ${ratio(resolve('--color-text-muted-inverse'), resolve('--color-surface-inverse')) ?? '—'}:1
+          </p>
+        </div>
+        <p style="max-width:70ch;margin-top:var(--spacing-16)">
+          There is no third step, and the reason is worth keeping: one component wanted one, and
+          measurement showed its value was a contrast failure rather than a tier. A
+          responsibility needs independent consumers <i>and</i> a value that survives the
+          grounds it will be used on. Do not build inverse counterparts for symmetry — build
+          them when two components have already built them separately.
+        </p>`
+      })}
+
+      ${refSection({
+        name    : 'When a primitive is the right answer',
+        meta    : 'not every colour has a responsibility',
+        children: html`
+        <p style="max-width:70ch">
+          Zero primitive references is not the goal. A primitive is right when the value
+          genuinely has no semantic job:
+        </p>
+        <ul style="max-width:70ch">
+          <li><b>Artwork.</b> The terminal's window dots are red, amber and green because that
+            is what a terminal looks like. They are not status.</li>
+          <li><b>Illustration and brand marks.</b> A logo's colours belong to the logo.</li>
+          <li><b>Product-specific comparison colours.</b> The compare bars name competitors, not
+            states.</li>
+          <li><b>A deliberate local visual API</b> a consuming page is meant to set.</li>
+        </ul>
+        <p style="max-width:70ch">
+          The test is not "is this a token" but <b>"does this colour communicate something the
+          system has a word for"</b>. If it does, use the word. If it does not, say so in a
+          comment so the next person does not have to work it out.
+        </p>`
+      })}
+    `
+  });

package/src/tokens/dark-derivation.js

@@ -0,0 +1,309 @@
+/**
+ * A dark value for every semantic colour role, derived from the light theme's
+ * own measurements. This is the method behind the 🔬 Dark mode study page in
+ * the Figma foundation file, and the data behind Foundations/Theming/Dark mode.
+ *
+ * Code has no dark theme. These are proposals, computed from tokens.css each
+ * time they are read, so they follow the palette instead of describing it.
+ *
+ * The method is the point: a dark value is chosen to KEEP what the light value
+ * measures, not to look like a dark theme.
+ *
+ *   text      keeps its contrast against the ground it is read on: the step
+ *             whose ratio is nearest the light ratio, never below 4.5 where
+ *             light clears 4.5, with the hierarchy order kept.
+ *   grounds   keep their tonal step from the page, matched by a step LIGHTER
+ *             than the dark page (on dark, a container is one step lighter).
+ *   edges     keep their ratio class against the page: under 3:1 stays
+ *             decorative, 3:1 and over stays a boundary.
+ *   status    tints sit at the dark end of the tone's ramp; ink is the
+ *             nearest-to-light step that clears 4.5 on the tint; accent clears
+ *             3:1 on the page AND on its own tint; a fill keeps its light pair
+ *             unless it would vanish into the dark page, then the chip inverts.
+ *   action    fills are self-contained, so they keep their light value, and
+ *             their ink (--color-action-on-fill) stays white. The label
+ *             clears 4.5:1 in every state; a RESTING fill also clears 3:1 on
+ *             the page, kept by choice. Hover and press are exempt from the
+ *             page bar: WCAG 1.4.11 treats a hover treatment as supplemental,
+ *             and a button with a text label needs no boundary at all. On the
+ *             dark page no ramp could keep it anyway -- label-on-fill times
+ *             fill-on-page is 19.45 for every fill, so both bars leave a band
+ *             only 1.44:1 wide (decision 4, decided 2026-10-02).
+ *
+ * A role is measured on every ground code draws it on, not only the page --
+ * the first version measured accent and brand text on the page alone, and the
+ * Alert atom is what showed it. Only existing primitives are used: where no
+ * step meets a rule, the nearest is returned and the row fails, because adding
+ * a primitive is its own decision.
+ *
+ * Not a story file: Storybook only globs *.stories.js. Pure, so it runs under
+ * Node too -- the parity check against the original script did.
+ */
+
+const RAMP = /^--color-(blue|red|green|yellow|neutral)-(\d+)$/;
+
+export const blank = text => text.replace(/\/\*[\s\S]*?\*\//g, '');
+
+/** name -> declared value, first declaration wins. */
+export function declarations(cssText) {
+  const out = new Map();
+  for (const m of blank(cssText).matchAll(/(?:^|[\s;{])(--[A-Za-z0-9-]+)\s*:\s*([^;]*);/g)) {
+    if (!out.has(m[1])) out.set(m[1], m[2]);
+  }
+  return out;
+}
+
+export function luminance(hex) {
+  const c = [1, 3, 5].map(i => parseInt(hex.slice(i, i + 2), 16) / 255)
+    .map(x => (x <= 0.03928 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
+}
+
+export function contrast(a, b) {
+  const [x, y] = [luminance(a), luminance(b)].sort((p, q) => q - p);
+  return (x + 0.05) / (y + 0.05);
+}
+
+const f2 = n => n.toFixed(2);
+const f3 = n => n.toFixed(3);
+
+export function derive(cssText) {
+  const decl = declarations(cssText);
+  const RAMPS = {};
+  for (const [k, v] of decl) {
+    const m = k.match(RAMP);
+    if (m) (RAMPS[m[1]] ??= {})[Number(m[2])] = v.trim().toLowerCase();
+  }
+  const prim = ref => {
+    const m = ref.trim().match(/^var\(\s*--color-(blue|red|green|yellow|neutral)-(\d+)\s*\)$/);
+    return m ? [m[1], Number(m[2])] : null;
+  };
+  const hexof = p => RAMPS[p[0]][p[1]];
+  const steps = ramp => Object.keys(RAMPS[ramp]).map(Number)
+    .sort((a, b) => a - b);
+  const lightOf = t => (decl.has(t) ? prim(decl.get(t)) : null);
+  const same = (a, b) => a && b && a[0] === b[0] && a[1] === b[1];
+  const lum = luminance, ratio = contrast;
+
+  function nearest(ramp, ground, target, { floor = null, lighterThan = null, exclude = [], also = [] } = {}) {
+    let best = null;
+    for (const s of steps(ramp)) {
+      if (exclude.some(e => same(e, [ramp, s]))) continue;
+      const h = RAMPS[ramp][s];
+      if (lighterThan && lum(h) <= lum(lighterThan)) continue;
+      const r = ratio(h, ground);
+      if (floor && (r < floor || also.some(g => ratio(h, g) < floor))) continue;
+      const d = Math.abs(r - target);
+      if (best === null || d < best[0]) best = [d, [ramp, s]];
+    }
+    return best && best[1];
+  }
+
+  const rows = [];
+  const row = (token, dark, against, againstLight, againstDark, rule, need = null) => {
+    const lp = lightOf(token);
+    const lightRatio = lp ? ratio(hexof(lp), againstLight) : null;
+    const darkRatio = dark ? ratio(hexof(dark), againstDark) : null;
+    const ok = need === null ? null : darkRatio !== null && darkRatio >= need;
+    rows.push({ token, light: lp, lightRatio, dark, darkRatio, against, rule, need, ok });
+    return dark;
+  };
+
+  const WHITE = RAMPS.neutral[0];
+  const L = {};
+  for (const t of decl.keys()) { const p = lightOf(t); if (p) L[t] = hexof(p); }
+
+  // ---------------------------------------------------------------- grounds --
+  const PAGE = ['neutral', 950];                // near-black, so a lighter container step exists
+  const page = hexof(PAGE);
+  row('--color-surface-default', PAGE, 'itself', L['--color-surface-default'], page,
+    'the dark page: near-black rather than pure black, so a lighter container step exists above it');
+  // in light order, each further from the page than the last: a ground that
+  // lands on its neighbour's step has lost the step it exists for. Two grounds
+  // that share a value in light (muted and disabled) share it in dark.
+  const groundOf = {};
+  let prevGround = PAGE;
+  for (const t of ['--color-surface-container', '--color-surface-subtle', '--color-surface-muted', '--color-surface-disabled', '--color-surface-pressed']) {
+    if (!L[t]) continue;
+    const twin = Object.keys(groundOf).find(k => L[k] === L[t]);
+    const target = ratio(L[t], L['--color-surface-default']);
+    const d = twin ? groundOf[twin] : nearest('neutral', page, target, { lighterThan: hexof(prevGround) });
+    groundOf[t] = d;
+    prevGround = d;
+    row(t, d, 'surface-default', L['--color-surface-default'], page,
+      twin ? `shares ${twin.slice(16)}'s value in light, so shares it in dark` : `keeps its tonal step from the page (light ${f3(target)}), further out than the ground before it`);
+  }
+  row('--color-surface-inverse', ['neutral', 50], 'surface-default', L['--color-surface-default'], page,
+    'flips: on a dark theme the inverse ground is the light one (Foundations/Surfaces)');
+  row('--color-surface-brand', lightOf('--color-surface-brand'), 'surface-default', L['--color-surface-default'], page,
+    'follows the brand, not the neutral ramp: unchanged');
+
+  // ------------------------------------------------------------------- text --
+  let prev = null;
+  for (const t of ['--color-text-primary', '--color-text-secondary', '--color-text-muted', '--color-text-subtle']) {
+    const target = ratio(L[t], WHITE);
+    const floor = target >= 4.5 ? 4.5 : null;
+    let d = nearest('neutral', page, target, { floor, lighterThan: page });
+    if (prev && lum(hexof(d)) >= lum(hexof(prev))) {            // keep the hierarchy strictly ordered
+      const cands = steps('neutral').filter(s => lum(RAMPS.neutral[s]) < lum(hexof(prev)) && (!floor || ratio(RAMPS.neutral[s], page) >= floor));
+      if (cands.length) d = ['neutral', Math.min(...cands)];
+      else {                                                      // nothing clears the floor: the nearest, and the row fails
+        const darker = steps('neutral').filter(s => lum(RAMPS.neutral[s]) < lum(hexof(prev)) && lum(RAMPS.neutral[s]) > lum(page));
+        d = ['neutral', darker.reduce((a, s) => (Math.abs(ratio(RAMPS.neutral[s], page) - target) < Math.abs(ratio(RAMPS.neutral[a], page) - target) ? s : a))];
+      }
+    }
+    prev = d;
+    row(t, d, 'surface-default', WHITE, page, `keeps its contrast on the page (light ${f2(target)}:1)`, floor);
+  }
+  {
+    const t = '--color-text-disabled';
+    const target = ratio(L[t], WHITE);
+    row(t, nearest('neutral', page, target, { lighterThan: page }), 'surface-default', WHITE, page,
+      `STATE, exempt from the minimum: keeps its light ratio (${f2(target)}:1)`);
+  }
+  const invDark = hexof(['neutral', 50]);
+  for (const t of ['--color-text-inverse', '--color-text-muted-inverse']) {
+    const target = ratio(L[t], L['--color-surface-inverse']);
+    row(t, nearest('neutral', invDark, target, { floor: 4.5 }), 'surface-inverse', L['--color-surface-inverse'], invDark,
+      `keeps its contrast on the inverse ground (light ${f2(target)}:1)`, 4.5);
+  }
+  // feedback pairs: tint first, then the ink measured on it
+  for (const [tone, ramp] of [['success', 'green'], ['warning', 'yellow'], ['error', 'red'], ['info', 'blue']]) {
+    const st = `--color-surface-${tone}`;
+    const step = ratio(L[st], L['--color-surface-default']);
+    const tint = nearest(ramp, page, step, { lighterThan: page });
+    row(st, tint, 'surface-default', L['--color-surface-default'], page, `a tint one step off the page, like light (${f3(step)})`);
+    const tt = `--color-text-${tone}`;
+    if (L[tt]) {
+      const target = ratio(L[tt], L[st]);
+      row(tt, nearest(ramp, hexof(tint), target, { floor: 4.5 }), `surface-${tone}`, L[st], hexof(tint),
+        `keeps its contrast on its paired tint (light ${f2(target)}:1)`, 4.5);
+    }
+  }
+
+  // ------------------------------------------------------------------ edges --
+  for (const t of ['--color-border-subtle', '--color-border-default', '--color-border-strong', '--color-border-disabled', '--color-border-container']) {
+    const target = ratio(L[t], WHITE);
+    const floor = target >= 3 ? 3 : null;
+    row(t, nearest('neutral', page, target, { floor, lighterThan: page }), 'surface-default', WHITE, page,
+      `keeps its ratio class on the page (light ${f2(target)}:1)`, floor);
+  }
+  {
+    const t = '--color-border-brand';
+    const target = ratio(L[t], WHITE);
+    row(t, nearest('blue', page, target, { floor: 3 }), 'surface-default', WHITE, page, `keeps its boundary contrast (light ${f2(target)}:1)`, 3);
+  }
+
+  // ----------------------------------------------------------------- action --
+  const FILLS = ['--color-action-primary', '--color-action-primary-hover', '--color-action-primary-active',
+    '--color-action-accent', '--color-action-accent-hover', '--color-action-accent-active'];
+  const isState = t => /-(hover|active)$/.test(t);
+  const fillRow = (t, lp, dk, label, ground, lead) => {
+    const state = isState(t);
+    rows.push({ token      : t, light      : lp, lightRatio : ratio(WHITE, hexof(lp)), dark       : dk, darkRatio  : label, against    : 'white label',
+      rule       : `${lead}: the white label keeps ${f2(label)}:1; against the dark page it measures ${f2(ground)}:1${state ? ', a state, so supplemental' : ', a resting fill, kept at 3:1'}`,
+      need       : 4.5, ok         : label >= 4.5 && (state || ground >= 3), groundRatio: ground, state });
+  };
+  for (const t of FILLS) {
+    const lp = lightOf(t);
+    fillRow(t, lp, lp, ratio(WHITE, hexof(lp)), ratio(hexof(lp), page), 'self-contained fill');
+  }
+
+  // the neutral fill cannot keep its light value: neutral-950 IS the dark page.
+  // Rest takes the step that clears 3:1 on the page and keeps the white label
+  // at 4.5; hover and press step away from the label's side of the ramp, the
+  // direction light's primary and accent ramps already go (decision 4).
+  if (decl.has('--color-action-secondary')) {
+    const usable = steps('neutral').filter(s => ratio(WHITE, RAMPS.neutral[s]) >= 4.5);
+    const rest = usable.filter(s => ratio(RAMPS.neutral[s], page) >= 3).reduce((a, s) => (ratio(RAMPS.neutral[s], page) > ratio(RAMPS.neutral[a], page) ? s : a), usable[0]);
+    const after = usable.filter(s => s > rest);
+    const pick = { '--color-action-secondary': rest, '--color-action-secondary-hover': after[0], '--color-action-secondary-active': after[1] };
+    for (const [t, step] of Object.entries(pick)) {
+      if (!decl.has(t) || step == null) continue;
+      const hex = RAMPS.neutral[step];
+      fillRow(t, lightOf(t), ['neutral', step], ratio(WHITE, hex), ratio(hex, page), 'the neutral fill moves off the dark page');
+    }
+  }
+
+  // ----------------------------------------------------------------- status --
+  const TINTS = {};
+  const TONES = { neutral: 'neutral', brand: 'blue', info: 'blue', success: 'green', warning: 'yellow', error: 'red' };
+  for (const [tone, ramp] of Object.entries(TONES)) {
+    const p = `--status-${tone}-`;
+    const hasStrong = decl.has(`${p}surface-strong`);
+    const sTarget = ratio(L[`${p}surface`], WHITE);
+    const surf = nearest(ramp, page, sTarget, { lighterThan: page });
+    row(`${p}surface`, surf, 'surface-default', WHITE, page, `the light tint: one step off the page, like light (${f3(sTarget)})`);
+    let strong = null;
+    if (hasStrong) {
+      const ssTarget = ratio(L[`${p}surface-strong`], WHITE);
+      strong = nearest(ramp, page, ssTarget, { lighterThan: hexof(surf), exclude: [surf] });
+      row(`${p}surface-strong`, strong, 'surface-default', WHITE, page,
+        `the heavier tint: further from the page than -surface, like light (${f3(ssTarget)})`);
+    }
+    const inkGround = hexof(strong || surf);
+    const inkOn = hasStrong ? 'surface-strong' : 'surface';
+    const tTarget = ratio(L[`${p}text`], L[p + inkOn]);
+    row(`${p}text`, nearest(ramp, inkGround, tTarget, { floor: 4.5 }), inkOn, L[p + inkOn], inkGround,
+      `ink on the heavier tint a badge uses, keeping light (${f2(tTarget)}:1)`, 4.5);
+    const bTarget = ratio(L[`${p}border`], L[`${p}surface`]);
+    row(`${p}border`, nearest(ramp, hexof(surf), bTarget, { lighterThan: hexof(surf) }), 'surface', L[`${p}surface`], hexof(surf),
+      `the tag hairline on its own tint, keeping light (${f2(bTarget)}:1)`);
+    TINTS[tone] = hexof(surf);
+    const aTarget = ratio(L[`${p}accent`], WHITE);
+    const accent = nearest(ramp, page, aTarget, { floor: 3, also: [hexof(surf)] });
+    row(`${p}accent`, accent, 'surface-default', WHITE, page,
+      `the badge dot on the page AND the alert icon on its own tint: clears 3:1 on both (${f2(ratio(hexof(accent), hexof(surf)))}:1 on the tint; light ${f2(aTarget)}:1 on the page)`, 3);
+    let fill = lightOf(`${p}fill`), onfill = lightOf(`${p}on-fill`), why = 'self-contained chip: unchanged';
+    if (ratio(hexof(fill), page) < 3) {                          // would vanish into the page: invert the chip
+      fill = nearest(ramp, page, ratio(L[`${p}fill`], WHITE), { floor: 3 });
+      onfill = ['neutral', steps('neutral').reduce((a, s) => (ratio(RAMPS.neutral[s], hexof(fill)) > ratio(RAMPS.neutral[a], hexof(fill)) ? s : a))];
+      why = 'the light fill vanishes into the dark page, so the chip inverts';
+    }
+    row(`${p}fill`, fill, 'surface-default', WHITE, page, why, 3);
+    row(`${p}on-fill`, onfill, 'fill', L[`${p}fill`], hexof(fill), 'ink on the fill', 4.5);
+  }
+
+  // ------------------------------------------------- brand text, every ground --
+  const tints = Object.values(TINTS);
+  const brandTarget = ratio(L['--color-text-brand'], WHITE);
+  const brand = nearest('blue', page, brandTarget, { floor: 4.5, also: tints });
+  const brandWorst = Math.min(...tints.map(g => ratio(hexof(brand), g)));
+  row('--color-text-brand', brand, 'surface-default', WHITE, page,
+    `keeps its contrast on the page (light ${f2(brandTarget)}:1) AND clears 4.5:1 on every status tint, where an alert sets its action link (${f2(brandWorst)}:1 on the weakest)`, 4.5);
+
+  // ------------------------------------------- roles added by 591c695a --
+  if (decl.has('--color-text-brand-hover')) {
+    const sep = ratio(L['--color-text-brand-hover'], L['--color-text-brand']);
+    const cands = steps('blue').filter(s => lum(RAMPS.blue[s]) > lum(hexof(brand)) && [page, ...tints].every(g => ratio(RAMPS.blue[s], g) >= 4.5));
+    const hover = ['blue', cands.reduce((a, s) => (Math.abs(ratio(RAMPS.blue[s], hexof(brand)) - sep) < Math.abs(ratio(RAMPS.blue[a], hexof(brand)) - sep) ? s : a))];
+    row('--color-text-brand-hover', hover, 'surface-default', WHITE, page,
+      `one step past the rest colour, away from the page as in light (${f2(ratio(hexof(hover), hexof(brand)))}:1 from it; light ${f2(sep)})`, 4.5);
+  }
+  if (decl.has('--color-action-on-fill')) {
+    const worst = Math.min(...FILLS.map(t => ratio(WHITE, hexof(lightOf(t)))));
+    rows.push({ token     : '--color-action-on-fill', light     : lightOf('--color-action-on-fill'), lightRatio: worst, dark      : lightOf('--color-action-on-fill'), darkRatio : worst,
+      against   : 'action fills', rule      : `white in both themes: the fills do not change, so neither does their ink (weakest ${f2(worst)}:1)`, need      : 4.5, ok        : worst >= 4.5 });
+  }
+
+  // ------------------------------------------ the media frame, decision 15 --
+  // fixed in every theme: a letterbox and a terminal are dark whatever the page
+  // is, and their ink is fixed with them. Measured on the frame, not the page.
+  if (decl.has('--color-surface-media')) {
+    const frame = lightOf('--color-surface-media');
+    row('--color-surface-media', frame, 'surface-default', L['--color-surface-default'], page,
+      'fixed: the frame around media is dark in every theme, so it keeps its light value');
+    for (const t of ['--color-text-on-media', '--color-text-on-media-muted']) {
+      if (!decl.has(t)) continue;
+      row(t, lightOf(t), 'surface-media', hexof(frame), hexof(frame),
+        `fixed with its ground: ${f2(ratio(L[t], hexof(frame)))}:1 on the frame in either theme`, 4.5);
+    }
+  }
+
+  const name = p => (p ? `${p[0]}/${p[1]}` : null);
+  return {
+    page : hexof(PAGE),
+    ramps: RAMPS,
+    rows : rows.map(r => ({ ...r, light: name(r.light), dark: name(r.dark), lightHex: r.light ? hexof(r.light) : null, darkHex: r.dark ? hexof(r.dark) : null }))
+  };
+}