@repobit/dex-system-design 0.25.11 → 0.26.0

package/src/tokens/dark-findings.js

@@ -0,0 +1,197 @@
+/**
+ * The findings of the 🔬 Dark mode study, as data, each with a check that runs
+ * against the code. The numbers are the Figma page's, so the two can be read
+ * side by side; 6 and 7 are observations rather than findings, below.
+ *
+ * What a finding SAYS -- its status, its wording, which commit fixed it -- is a
+ * record of a decision, and is written here by hand. What it CLAIMS about the
+ * code is checked: a fixed finding verifies the fix is still in place, an open
+ * one verifies it still fails. When a check disagrees with the status, the page
+ * says so, which is how a reverted fix or a quietly-resolved finding shows up
+ * instead of lying in prose.
+ *
+ * A check receives { decl, src, row }: the token declarations, the raw source
+ * of the component stylesheets it names, and a lookup into the derived dark
+ * values. It returns { holds, detail } -- holds is whether the status is still
+ * true. Not a story file. Pure, so it runs under Node.
+ */
+
+import { contrast } from './dark-derivation.js';
+
+const has = (s, needle) => (s || '').includes(needle);
+const reads = (decl, token, role) => (decl.get(token) || '').trim() === `var(${role})`;
+const r2 = n => (n == null ? '—' : n.toFixed(2));
+
+export const FINDINGS = [
+  {
+    n      : 1, status : 'fixed', commit : '591c695a', kind   : 'role',
+    title  : 'Button labels borrowed text-inverse',
+    summary: 'Six filled-button labels read --color-text-inverse, which a dark theme flips to near-black on the fill. They read --color-action-on-fill now: white in both themes, 4.53 to 10.51:1.',
+    files  : [],
+    check  : ({ decl }) => {
+      const t = ['primary-text-default', 'accent-text-default', 'secondary-text-default', 'tertiary-text-active', 'ghost-text-active', 'outline-white-text-default'].map(x => `--button-${x}`);
+      const off = t.filter(x => !reads(decl, x, '--color-action-on-fill'));
+      return { holds: !off.length, detail: off.length ? `still borrowing: ${off.join(', ')}` : 'all six label tokens read --color-action-on-fill' };
+    }
+  },
+  {
+    n      : 2, status : 'fixed', kind   : 'palette',
+    title  : 'The dark end of the neutral ramp was too coarse',
+    summary: 'Light has four grounds within 1.29:1 of the page; dark had neutral-950, then 900, then 800, so container and subtle landed on one step. neutral-925 and 850 sit at the light steps, 1.04 and 1.12 off the dark page.',
+    check  : ({ row }) => {
+      const g = ['--color-surface-container', '--color-surface-subtle', '--color-surface-muted'].map(row);
+      const apart = new Set(g.map(r => r.dark)).size === g.length;
+      return { holds: apart, detail: g.map(r => `${r.token.slice(16)} ${r.dark}`).join(', ') + (apart ? '' : ': two share a step again') };
+    }
+  },
+  {
+    n      : 3, status : 'fixed', kind   : 'palette',
+    title  : 'text-subtle had no dark step that kept both its jobs',
+    summary: 'It must stay quieter than text-muted and clear 4.5:1, and no neutral step did both. neutral-450 does: 4.93:1 on the dark page and 4.75 on a dark card, 1.22:1 from muted.',
+    check  : ({ row }) => {
+      const r = row('--color-text-subtle'), m = row('--color-text-muted');
+      const ok = r.ok === true && r.dark !== m.dark;
+      return { holds: ok, detail: `derives to ${r.dark}, ${r2(r.darkRatio)}:1 on the dark page; muted is ${m.dark}` };
+    }
+  },
+  {
+    n      : 4, status : 'decided', kind   : 'design',
+    title  : 'The action ramp darkens in dark too, and the page bar is for the resting fill',
+    summary: 'On the dark page, label-on-fill times fill-on-page is 19.45 for every fill, so a white label at 4.5:1 and a fill at 3:1 leave a band 1.44:1 wide -- accent and secondary have one step in it, so no ramp keeps both bars in three states. Decided: hover and press darken as in light; every state keeps its white label at 4.5:1; a resting fill keeps 3:1 on the page by choice; hover and press are supplemental, as WCAG 1.4.11 says, and a text button needs no boundary at all.',
+    check  : ({ row }) => {
+      const t = ['primary', 'accent', 'secondary'].flatMap(k => ['', '-hover', '-active'].map(s => `--color-action-${k}${s}`)).map(row)
+        .filter(r => r.token);
+      const label = t.filter(r => r.darkRatio < 4.5), rest = t.filter(r => !r.state && r.groundRatio < 3);
+      const ok = t.length === 9 && !label.length && !rest.length;
+      return { holds : ok, detail: ok
+        ? `every label clears 4.5 (weakest ${r2(Math.min(...t.map(r => r.darkRatio)))}:1); resting fills ${t.filter(r => !r.state).map(r => r2(r.groundRatio))
+          .join(', ')}:1 on the page`
+        : [label.length && `label under 4.5: ${label.map(r => r.token.slice(15)).join(', ')}`, rest.length && `resting fill under 3: ${rest.map(r => r.token.slice(15)).join(', ')}`, t.length !== 9 && `${t.length} of 9 fill rows`].filter(Boolean).join(' · ') };
+    }
+  },
+  {
+    n      : 5, status : 'fixed', kind   : 'palette',
+    title  : 'Success and warning tints ran three times heavier than in light',
+    summary: 'green-950 and yellow-950 are not near-black, so those tints sat about 1.55:1 off the dark page against 1.05 in light, and read as coloured bands on an alert. green-975 and yellow-975 sit at 1.04 and 1.03.',
+    check  : ({ row }) => {
+      const g = row('--status-success-surface'), y = row('--status-warning-surface');
+      const light = g.darkRatio / g.lightRatio <= 1.3 && y.darkRatio / y.lightRatio <= 1.3;
+      return { holds: light, detail: `success ${r2(g.lightRatio)} → ${r2(g.darkRatio)}, warning ${r2(y.lightRatio)} → ${r2(y.darkRatio)} off the page` };
+    }
+  },
+  {
+    n      : 8, status : 'fixed', kind   : 'primitive',
+    title  : 'Secondary and pressed ghost buttons read primitives, and vanished on a dark page',
+    summary: 'Their fills were neutral-950/800/1000 from the palette, which has no dark value, and the dark page is neutral-950 too. They read --color-action-secondary now. The white preset mixed a fixed fill with a switching label; its label is a fixed blue-600 now, like its fill.',
+    check  : ({ decl }) => {
+      const t = ['--button-secondary-background-default', '--button-secondary-background-hover', '--button-secondary-background-active', '--button-ghost-background-active'];
+      const prim = t.filter(x => !/var\(--color-action-secondary(-hover|-active)?\)/.test(decl.get(x) || ''));
+      const white = reads(decl, '--button-white-text-default', '--color-blue-600');
+      const ok = !prim.length && white;
+      return { holds: ok, detail: ok ? 'four fills read --color-action-secondary; the white preset label is fixed' : [prim.length && `not on the role: ${prim.join(', ')}`, !white && 'the white preset label switches again'].filter(Boolean).join(' · ') };
+    }
+  },
+  {
+    n      : 9, status : 'fixed', commit : '415fc57c', kind   : 'light-bug',
+    title  : 'outline-white lost AA on hover and press, in light',
+    summary: 'Its white wash lightened the blue under a white label (3.91 and 3.38:1). It darkens now, and the label passes on every ground the preset sits on.',
+    check  : ({ decl }) => {
+      const ok = ['--button-outline-white-background-hover', '--button-outline-white-background-active'].every(t => has(decl.get(t), '--color-neutral-1000'));
+      return { holds: ok, detail: ok ? 'hover and press wash with neutral-1000' : 'a white wash is back' };
+    }
+  },
+  {
+    n      : 10, status : 'fixed', commit : '591c695a', kind   : 'primitive',
+    title  : 'The required mark read a primitive',
+    summary: 'It was red-600 from the palette, 3.57:1 in dark. It reads --status-error-accent now, like the error help text.',
+    check  : ({ decl }) => { const ok = reads(decl, '--form-label-required-color', '--status-error-accent'); return { holds: ok, detail: ok ? '--form-label-required-color reads --status-error-accent' : `reads ${decl.get('--form-label-required-color')}` }; }
+  },
+  {
+    n      : 11, status : 'fixed', commit : '415fc57c', kind   : 'light-bug',
+    title  : 'Placeholders failed on the error and success tints, in light',
+    summary: 'Every placeholder was text-subtle, 4.22 and 4.43:1 on the tints. Error and success fields take text-muted now. The plain field\'s dark placeholder is finding 3.',
+    files  : ['form-field'],
+    check  : ({ src }) => { const ok = has(src['form-field'], '.form-input--error::placeholder'); return { holds: ok, detail: ok ? 'form-field.css.js sets tinted placeholders to text-muted' : 'the tinted-placeholder rule is gone' }; }
+  },
+  {
+    n      : 12, status : 'fixed', commit : '591c695a', kind   : 'role',
+    title  : 'The checkmark, radio dot and switch thumb read the page colour',
+    summary: 'They were --color-surface-default, which is "the page", not "white", and turns near-black on blue in dark. They read --color-action-on-fill now.',
+    files  : ['checkbox', 'radio', 'switch'],
+    check  : ({ src }) => { const off = ['checkbox', 'radio', 'switch'].filter(k => !has(src[k], 'var(--color-action-on-fill)')); return { holds: !off.length, detail: off.length ? `not on action-on-fill: ${off.join(', ')}` : 'all three read --color-action-on-fill' }; }
+  },
+  {
+    n      : 13, status : 'fixed', commit : '591c695a', kind   : 'role',
+    title  : 'A link\'s hover borrowed a button fill as text',
+    summary: 'Primary and bold hovers read --color-action-primary-active; they read --color-text-brand-hover now. The subtle link at rest failed in dark too, until finding 3 gave text-subtle a dark step.',
+    files  : ['link'],
+    check  : ({ src }) => { const ok = !has(src.link, 'action-primary-active') && has(src.link, 'var(--color-text-brand-hover)'); return { holds: ok, detail: ok ? 'link hovers read --color-text-brand-hover' : 'a hover reads an action fill again' }; }
+  },
+  {
+    n      : 14, status : 'decided', kind   : 'primitive',
+    title  : 'Back and Avatar read primitives, and failed in dark',
+    summary: 'Back\'s pressed ground was neutral-200 under a label that switches, 1.48:1 in dark; it reads --color-surface-pressed now. Avatar\'s disc was blue-100 from the palette, 2.68:1 in dark under its initials. Decided: the disc reads --status-brand-surface, chosen for meaning (brand identity), not for value -- the only blue-100 role is info\'s, and an avatar is not info. The initials read 5.72:1 in light and 5.10 in dark; the disc is fainter on the page (1.08:1), and the initials, not the edge, identify it.',
+    files  : ['back', 'avatar'],
+    check  : ({ src }) => {
+      const b = has(src.back, 'var(--color-surface-pressed)'), a = has(src.avatar, 'var(--status-brand-surface)') && !has(src.avatar, 'var(--color-blue-100)');
+      return { holds: b && a, detail: [b ? 'Back reads --color-surface-pressed' : 'Back reads a primitive again', a ? 'Avatar reads --status-brand-surface' : 'Avatar reads a primitive again'].join(' · ') };
+    }
+  },
+  {
+    n      : 15, status : 'decided', kind   : 'design',
+    title  : 'Video and terminal frames used surface-inverse to mean "dark"',
+    summary: 'Inverse means the other polarity, so in dark the frame turned light and its ink dark: a play icon at 3.13:1, and a terminal palette (blue-400, the traffic-light green) that only works on a dark ground. Decided: --color-surface-media, dark in every theme, with --color-text-on-media and -muted fixed alongside it. The tooltip stays on surface-inverse: a bubble that flips is what inverse means.',
+    files  : ['video-player', 'video', 'terminal-message', 'tooltip'],
+    check  : ({ src }) => {
+      const frames = ['video-player', 'video', 'terminal-message'];
+      const off = frames.filter(k => !has(src[k], 'var(--color-surface-media)') || has(src[k], 'var(--color-surface-inverse)') || has(src[k], 'var(--color-text-inverse)'));
+      const tip = has(src.tooltip, 'var(--color-surface-inverse)');
+      const ok = !off.length && tip;
+      return { holds: ok, detail: ok ? 'video, bd-video and the terminal read surface-media and its ink; the tooltip stays inverse' : [off.length && `still on inverse: ${off.join(', ')}`, !tip && 'the tooltip left surface-inverse'].filter(Boolean).join(' · ') };
+    }
+  },
+  {
+    n      : 16, status : 'fixed', commit : '591c695a', kind   : 'primitive',
+    title  : 'The citation reference read the palette',
+    summary: 'blue-600 and blue-700 from the ramp, 3.15 and 2.27:1 in dark. It reads --color-text-brand and --color-text-brand-hover now.',
+    check  : ({ decl }) => { const ok = reads(decl, '--citation-reference-color', '--color-text-brand') && reads(decl, '--citation-reference-hover-color', '--color-text-brand-hover'); return { holds: ok, detail: ok ? 'both citation tokens read brand text roles' : 'a citation token reads a primitive again' }; }
+  },
+  {
+    n      : 17, status : 'decided', commit : '415fc57c', kind   : 'light-bug',
+    title  : 'text-subtle failed on a card, in light, and on bands and tints in both themes',
+    summary: 'neutral-500 moved one step for the card (415fc57c, 4.61:1). On surface-subtle and the status tints it was still 4.29 to 4.46, and no value can be quieter than muted and clear 4.5 on every ground -- on surface-muted it would have to be muted. Decided: subtle text sits on the page or a card; on a band or a tint it steps up to text-muted. neutral-450 is measured on the dark card (4.75), and the compatibility table\'s blue band moved its labels to muted (6.10).',
+    files  : ['compatibility-table'],
+    check  : ({ decl, src }) => {
+      // what the rule is FOR: subtle clears 4.5 on a card in both themes, and the band that broke it no longer carries it
+      const c = t => (decl.get(t) || '').trim();
+      const light = contrast(c('--color-neutral-500'), c('--color-neutral-25')), dark = contrast(c('--color-neutral-450'), c('--color-neutral-925'));
+      const band = has(src['compatibility-table'], ':host([background="blue"]) .bd-compattable-lightlabel');
+      const ok = light >= 4.5 && dark >= 4.5 && band;
+      return { holds: ok, detail: `subtle on a card ${light.toFixed(2)}:1 in light, ${dark.toFixed(2)} in dark${band ? '; the blue-band label reads muted' : '; the blue-band label is subtle again'}` };
+    }
+  },
+  {
+    n      : 18, status : 'fixed', commit : '591c695a', kind   : 'role',
+    title  : 'The list check borrowed its pair',
+    summary: 'Disc and tick read the status accent and text-inverse; they read the badge\'s own fill and on-fill now.',
+    files  : ['list-item'],
+    check  : ({ src }) => { const ok = has(src['list-item'], 'var(--status-success-fill)') && has(src['list-item'], 'var(--status-success-on-fill)'); return { holds: ok, detail: ok ? 'the check reads --status-success-fill and -on-fill' : 'the check borrows again' }; }
+  }
+];
+
+/** Observations from the study that are not defects. Shown, not checked. */
+export const OBSERVATIONS = [
+  { n: 6, title: 'What carries over unchanged', summary: 'muted and disabled share a value in both themes. In light, border-container is surface-muted\'s step, so a card edge disappears on a muted band; in dark it lands on surface-subtle\'s step instead (neutral-850), so the band it disappears on moves from muted to subtle.' },
+  { n: 7, title: 'Badges and tags hold in dark', summary: 'Every part passes in both modes, on the page and on a card. A badge and a tag of one tone read further apart in dark than in light, except brand, which is the same ground in both by design.' }
+];
+
+/** Every check, run. */
+export function runChecks({ decl, src, rows }) {
+  const byToken = new Map(rows.map(r => [r.token, r]));
+  const row = t => byToken.get(t) || {};
+  return FINDINGS.map(f => {
+    let res;
+    try { res = f.check({ decl, src, row }); } catch (e) { res = { holds: false, detail: `check failed to run: ${e.message}` }; }
+    return { ...f, ...res };
+  });
+}

package/src/tokens/dark-mode.stories.js

@@ -0,0 +1,207 @@
+import { html, unsafeCSS } from 'lit';
+import { copyToken, docsPage, refSection } from './story-chrome.js';
+import { declarations, derive } from './dark-derivation.js';
+import { OBSERVATIONS, runChecks } from './dark-findings.js';
+/* The generated stylesheet itself, not a copy: every value on this page is
+   derived from it when the page opens, so the page follows the palette. */
+import tokensCss from './tokens.css?raw';
+
+import '../components/alert/alert.js';
+import '../components/badge/badge.js';
+import '../components/button/button.js';
+import '../components/checkbox/checkbox.js';
+import '../components/heading/heading.js';
+import '../components/input/input.js';
+import '../components/link/link.js';
+import '../components/paragraph/paragraph.js';
+import '../components/radio/radio.js';
+import '../components/switch/switch.js';
+import '../components/tag/tag.js';
+
+export default {
+  title: 'Foundations/Theming/Dark mode',
+  tags : ['autodocs']
+};
+
+/* The stylesheets the findings' checks read. Lazy, so they only load here. */
+const SOURCES = {
+  'form-field'         : () => import('../components/shared/form-field.css.js?raw'),
+  checkbox             : () => import('../components/checkbox/checkbox.css.js?raw'),
+  radio                : () => import('../components/radio/radio.css.js?raw'),
+  switch               : () => import('../components/switch/switch.css.js?raw'),
+  link                 : () => import('../components/link/link.css.js?raw'),
+  'list-item'          : () => import('../components/list/list-item/list-item.css.js?raw'),
+  back                 : () => import('../components/back/back.css.js?raw'),
+  avatar               : () => import('../components/avatar/avatar.css.js?raw'),
+  'video-player'       : () => import('../components/video-player/video-player.css.js?raw'),
+  video                : () => import('../components/video/video.css.js?raw'),
+  'terminal-message'   : () => import('../components/terminal/terminal-message.css.js?raw'),
+  tooltip              : () => import('../components/tooltip/tooltip.css.js?raw'),
+  'compatibility-table': () => import('../components/compatibility-table/compatibility-table.css.js?raw')
+};
+
+async function load() {
+  const src = Object.fromEntries(await Promise.all(Object.entries(SOURCES).map(async ([k, f]) => [k, (await f()).default])));
+  const decl = declarations(tokensCss);
+  const derived = derive(tokensCss);
+  return { decl, derived, findings: runChecks({ decl, src, rows: derived.rows }) };
+}
+
+/* A container that re-declares the WHOLE token sheet, with each semantic
+   colour role swapped for its derived dark value. Component tokens are
+   re-declared too, so a --button-* that reads a role re-resolves inside the
+   container -- and one that reads a primitive stays put, exactly as it would
+   under a real dark theme. Custom properties inherit into shadow roots, so
+   the real components below render with it. */
+function darkScope(decl, rows) {
+  const dark = new Map(rows.filter(r => r.darkHex).map(r => [r.token, r.darkHex]));
+  dark.set('--color-border-container-inverse', 'color-mix(in srgb, var(--color-neutral-1000) 12%, transparent)');
+  const body = [...decl].map(([k, v]) => `${k}: ${dark.get(k) ?? v};`).join('\n');
+  return unsafeCSS(`.dm-dark { ${body} }`);
+}
+
+const STATUS = {
+  'fixed'       : ['Fixed', 'text/success'],
+  'partly fixed': ['Partly fixed', 'text/warning'],
+  'open'        : ['Open', 'text/error'],
+  'decision'    : ['Needs a decision', 'text/brand'],
+  'decided'     : ['Decided', 'text/success']
+};
+const chip = s => html`<span style="font-size:var(--typography-fontSize-xxs);font-weight:var(--typography-fontWeight-semibold);letter-spacing:var(--typography-letterSpacing-wide);text-transform:uppercase;color:var(--color-${STATUS[s][1].replace('/', '-')})">${STATUS[s][0]}</span>`;
+
+const finding = f => html`
+  <div style="padding:var(--spacing-12) 0;border-top:var(--border-width-1) solid var(--color-border-subtle);max-width:80ch">
+    <div style="display:flex;gap:var(--spacing-12);align-items:baseline">
+      <b>${f.n}</b><b>${f.title}</b>${chip(f.status)}${f.commit ? html`<code class="muted">${f.commit}</code>` : ''}
+    </div>
+    <p style="margin:var(--spacing-4) 0">${f.summary}</p>
+    <p style="margin:0;font-size:var(--typography-fontSize-xs);color:${f.holds ? 'var(--color-text-muted)' : 'var(--color-text-error)'}">
+      ${f.holds ? html`<b>Checked against the code:</b> ${f.detail}.` : html`<b>The code disagrees with this status:</b> ${f.detail}. Update the finding.`}
+    </p>
+  </div>`;
+
+/* the same set of real components, rendered twice */
+const specimen = () => html`
+  <div style="display:grid;gap:var(--spacing-16)">
+    <bd-h as="h3" visual-level="h4">A section title</bd-h>
+    <bd-p>Body copy on the page ground, the primary ink.</bd-p>
+    <div style="display:flex;gap:var(--spacing-16);flex-wrap:wrap">
+      <!-- The ink is inline because bd-p has no colour API: its properties are
+           variant and the deprecated kind, both typographic. color="muted" set
+           nothing, so this row -- the one place the page shows the text roles --
+           rendered all four in primary, and check:attributes failed on it. -->
+      ${['muted', 'subtle', 'brand', 'error'].map(r => html`<bd-p style="color:var(--color-text-${r})">${r}</bd-p>`)}
+    </div>
+    <div style="display:flex;gap:var(--spacing-8);flex-wrap:wrap">
+      <bd-button variant="primary" label="Primary"></bd-button>
+      <bd-button variant="secondary" label="Secondary"></bd-button>
+      <bd-button variant="tertiary" label="Tertiary"></bd-button>
+      <bd-button variant="ghost" label="Ghost"></bd-button>
+      <bd-button variant="accent" label="Buy now"></bd-button>
+    </div>
+    <div style="display:flex;gap:var(--spacing-8);flex-wrap:wrap;align-items:center">
+      ${['neutral', 'brand', 'info', 'success', 'warning', 'error'].map(t => html`<bd-badge tone=${t}>${t}</bd-badge>`)}
+      ${['neutral', 'success', 'error'].map(t => html`<bd-tag tone=${t}>${t}</bd-tag>`)}
+    </div>
+    ${['info', 'success', 'warning', 'error'].map(t => html`<bd-alert tone=${t} heading=${`${t[0].toUpperCase()}${t.slice(1)} alert`}>The description stays the primary ink.</bd-alert>`)}
+    <div style="display:flex;gap:var(--spacing-24);flex-wrap:wrap">
+      <bd-checkbox label="Checked" checked></bd-checkbox>
+      <bd-radio label="Selected" checked></bd-radio>
+      <bd-switch checked>On</bd-switch>
+      <bd-link href="#" variant="primary">A primary link</bd-link>
+    </div>
+    <bd-custom-input label="Work email" placeholder="you@example.com"></bd-custom-input>
+    <bd-custom-input label="Work email" placeholder="you@example.com" invalid></bd-custom-input>
+  </div>`;
+
+const valueRow = r => html`<tr>
+  <td>${copyToken(r.token)}</td>
+  <td class="num"><span style="display:inline-block;width:var(--dimension-12);height:var(--dimension-12);margin-right:var(--spacing-6);vertical-align:middle;border-radius:var(--radius-sm);border:var(--border-width-1) solid var(--color-border-subtle);background:${r.lightHex ?? 'transparent'}"></span>${r.light ?? '—'}</td>
+  <td class="num">${r.lightRatio == null ? '—' : r.lightRatio.toFixed(2)}</td>
+  <td class="num"><span style="display:inline-block;width:var(--dimension-12);height:var(--dimension-12);margin-right:var(--spacing-6);vertical-align:middle;border-radius:var(--radius-sm);border:var(--border-width-1) solid var(--color-border-subtle);background:${r.darkHex ?? 'transparent'}"></span>${r.dark ?? '—'}</td>
+  <td class="num" style="${r.ok === false ? 'color:var(--color-text-error)' : ''}">${r.darkRatio == null ? '—' : r.darkRatio.toFixed(2)}</td>
+  <td>${r.against}</td>
+  <td>${r.ok === null ? html`<span class="muted">—</span>` : r.ok ? 'ok' : html`<b style="color:var(--color-text-error)">fails</b>`}</td>
+  <td style="max-width:44ch">${r.rule}</td>
+</tr>`;
+
+export const DarkMode = (_args, { loaded: { data } }) => {
+  const { decl, derived, findings } = data;
+  const count = s => findings.filter(f => f.status === s).length;
+  const disagree = findings.filter(f => !f.holds);
+  const fails = derived.rows.filter(r => r.ok === false).length;
+  return docsPage({
+    title: 'Dark mode',
+    lede : `There is no dark theme in code. This page is the evidence for one: what each colour role would
+            become, measured; what that would break, and what has already been fixed so it will not.
+            Everything here is computed from tokens.css when the page opens, and every finding is checked
+            against the code, so the page cannot describe a palette that has moved on.`,
+    note: html`<b>Where this came from.</b> The 🔬 Dark mode study page in the Figma foundation file
+      measured every atom in both modes. The method and the derived values now live in
+      <code>dark-derivation.js</code>, the findings in <code>dark-findings.js</code>, and this page reads
+      both. <b>A proposal, not a theme:</b> nothing here ships until the open findings are decided —
+      adding these values to tokens.js today would ship the failures listed below.`,
+    children: html`
+      ${refSection({
+        name    : 'Findings',
+        meta    : `${count('fixed')} fixed · ${count('partly fixed')} partly · ${count('open')} open · ${count('decision')} need a decision · ${count('decided')} decided`,
+        children: html`
+          ${disagree.length
+            ? html`<p style="color:var(--color-text-error);max-width:70ch"><b>${disagree.length} finding${disagree.length === 1 ? '' : 's'}
+            no longer match${disagree.length === 1 ? 'es' : ''} the code</b> — a fix was reverted, or an open finding was resolved without
+            updating it. Each one says which below.</p>`
+            : ''}
+          ${['open', 'decision', 'partly fixed', 'decided', 'fixed'].map(s => findings.filter(f => f.status === s).map(finding))}
+          ${OBSERVATIONS.map(o => html`
+            <div style="padding:var(--spacing-12) 0;border-top:var(--border-width-1) solid var(--color-border-subtle);max-width:80ch">
+              <div style="display:flex;gap:var(--spacing-12)"><b>${o.n}</b><b>${o.title}</b><span class="muted">observation</span></div>
+              <p style="margin:var(--spacing-4) 0 0">${o.summary}</p>
+            </div>`)}`
+      })}
+
+      ${refSection({
+        name    : 'Real components, both ways',
+        meta    : 'the shipped tokens, and the derived dark values',
+        children: html`
+          <style>${darkScope(decl, derived.rows)}</style>
+          <p style="max-width:70ch">These are the library's own components, not drawings. On the right, a container
+            re-declares the whole token sheet with each semantic colour role swapped for its derived dark value.
+            Whatever reads a role switches; whatever reads a primitive does not — which is why the secondary button
+            disappeared there until it read --color-action-secondary (finding 8), and why Avatar's disc still stays
+            light (finding 14). Text styles, shadows and focus rings are not derived, and keep their values.</p>
+          <div style="display:grid;grid-template-columns:repeat(auto-fit, minmax(min(100%, 30rem), 1fr));gap:var(--spacing-24)">
+            <div style="padding:var(--spacing-24);border-radius:var(--radius-xl);border:var(--border-width-1) solid var(--color-border-subtle);background:var(--color-surface-default)">
+              <p class="muted" style="margin:0 0 var(--spacing-16)">Shipped tokens</p>${specimen()}
+            </div>
+            <div class="dm-dark" style="padding:var(--spacing-24);border-radius:var(--radius-xl);background:var(--color-surface-default);color:var(--color-text-primary)">
+              <p style="margin:0 0 var(--spacing-16);color:var(--color-text-muted)">Derived dark values</p>${specimen()}
+            </div>
+          </div>`
+      })}
+
+      ${refSection({
+        name    : 'How each dark value is chosen',
+        meta    : 'keep what the light value measures',
+        children: html`<ul style="max-width:72ch;line-height:var(--typography-lineHeight-normal)">
+          <li><b>Text</b> keeps its contrast on the ground it is read on — the step nearest its light ratio, never under 4.5:1 where light clears it, in hierarchy order.</li>
+          <li><b>Grounds</b> keep their tonal step from the page, with a step lighter than the dark page (neutral-950, near-black so a lighter container exists).</li>
+          <li><b>Edges</b> keep their ratio class: under 3:1 stays decorative, 3:1 and over stays a boundary.</li>
+          <li><b>Status</b> tints sit at the dark end of the tone's ramp; ink clears 4.5:1 on the tint a badge uses; accent clears 3:1 on the page and on its own tint; a fill inverts only if it would vanish into the page.</li>
+          <li><b>Action</b> fills keep their value; their ink, --color-action-on-fill, stays white and clears 4.5:1 in every state. A resting fill keeps 3:1 on the page; hover and press are supplemental (finding 4).</li>
+          <li>A role is measured on every ground code draws it on, not only the page. Only existing primitives are used: where no step meets a rule, the nearest is shown and the row fails.</li>
+        </ul>`
+      })}
+
+      ${refSection({
+        name    : 'Every proposed value',
+        meta    : `${derived.rows.length} roles · ${fails} fail their rule`,
+        children: html`<div class="table-scroll"><table>
+          <caption>Each semantic colour role, its light value and the derived dark value, with WCAG contrast against the named ground</caption>
+          <thead><tr><th scope="col">Role</th><th scope="col">Light</th><th scope="col">ratio</th><th scope="col">Dark</th><th scope="col">ratio</th><th scope="col">Against</th><th scope="col">Verdict</th><th scope="col">Why this value</th></tr></thead>
+          <tbody>${derived.rows.map(valueRow)}</tbody>
+        </table></div>`
+      })}`
+  });
+};
+DarkMode.storyName = 'Dark mode';
+DarkMode.loaders = [async () => ({ data: await load() })];