fix(ui): make every colour token meet the contrast the spec has always required

docs/06 §5 has said "≥ 4.5:1 in both themes (tokens chosen accordingly)" since
the spec was written. Nothing enforced it, and the tokens were not chosen
accordingly. Measured:

  white on dark --accent      3.67:1   (fixed in Phase 4)
  white on dark --danger      2.74:1   Button/ConfirmDialog .danger
  light --warn on --bg-raised 3.40:1   WarningList summary
  light --success  "     "    3.26:1   TreePreviewNode badge, DuplicatePanel
  light --danger   "     "    4.27:1   DuplicatePanel count
  dark --accent    "     "    4.40:1   links inside raised panels

Adds --danger-fg, which like --accent-fg must be redefined in the dark block in
the OPPOSITE direction: dark mode lightens the colour for contrast against the
page, and that is exactly what breaks white ink sitting on it.

The light status colours are now darker than an eyeball would pick, because all
three are rendered as text on --bg-raised. Adjustments preserve hue and were
solved for numerically rather than guessed; each clears 4.5 with margin.

The real deliverable is tests/unit/styles/contrast.test.ts, which parses
tokens.css and fails on any text pair below 4.5:1 — verified to actually fail
by restoring the old --warn and watching it report 3.40:1. It also pins the two
dark blocks (explicit override and prefers-color-scheme) against each other,
because they already drifted once when --accent-fg was added to only one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-07-26 13:59:42 +07:00
1 parent 72e7c29428
commit 1589ea4209
5 files changed
+148 -12

No files matched your search

+20 -2
View File
@@ -11,7 +11,8 @@ framework.
--bg: #ffffff; --bg-raised: #f6f7f9; --border: #e2e5ea;
--fg: #1b1e24; --fg-muted: #5b6472;
--accent: #6d4aff; --accent-fg: #ffffff; /* violet — "magic" identity */
--danger: #d8384a; --success: #1f9d55; --warn: #b7791f;
--danger: #ce3547; --danger-fg: #ffffff;
--success: #198045; --warn: #99651a;
--radius: 10px; --radius-sm: 6px;
--font: system-ui, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
--fs-0: 12px; --fs-1: 13.5px; --fs-2: 15px; --fs-3: 18px; --fs-4: 24px;
@@ -20,10 +21,27 @@ framework.
[data-theme="dark"] {
--bg: #16181d; --bg-raised: #1e2128; --border: #2b3039;
--fg: #e8eaee; --fg-muted: #9aa3b0;
--accent: #8b6dff; --danger: #ff6b7d; --success: #3ecf8e; --warn: #e2b93b;
--accent: #8f72ff; --accent-fg: #16181d;
--danger: #ff6b7d; --danger-fg: #16181d;
--success: #3ecf8e; --warn: #e2b93b;
}
```
⚠️ **`--accent-fg` and `--danger-fg` must be redefined in the dark block, in the
opposite direction to the colour they sit on.** Dark mode lightens `--accent`
and `--danger` for contrast against `--bg`, which is exactly what breaks white
ink on them — the original palette measured 3.67:1 and 2.74:1 there, against
the 4.5:1 §5 requires.
The light `--danger`/`--success`/`--warn` are darker than an eyeball would pick
because all three are rendered as **text** on `--bg-raised` (DuplicatePanel
counts, TreePreviewNode badges, WarningList's summary), where the original
values measured 4.27, 3.26 and 3.40.
None of these numbers is a matter of taste: `tests/unit/styles/contrast.test.ts`
parses `tokens.css` and fails the build if any text pair drops below 4.5:1, or
if the two dark blocks drift apart. Re-run it after changing a colour.
Theme: `data-theme` on `<html>`; default follows `prefers-color-scheme`,
manual override persisted in Settings. Focus rings always visible
(`:focus-visible` outline in accent).
+3 -1
View File
@@ -44,6 +44,8 @@
.danger {
background: var(--danger);
border-color: var(--danger);
color: #fff;
/* Not #fff: dark mode lightens --danger, where white ink measures 2.74:1
against the 4.5:1 docs/06 §5 requires. */
color: var(--danger-fg);
}
</style>
+1 -1
View File
@@ -77,6 +77,6 @@
.danger {
background: var(--danger);
border-color: var(--danger);
color: #fff;
color: var(--danger-fg);
}
</style>
+19 -8
View File
@@ -1,5 +1,10 @@
/* Design tokens — docs/06 §1. Theme via data-theme on <html>; default follows
prefers-color-scheme, manual override persisted in Settings. */
prefers-color-scheme, manual override persisted in Settings.
Every `*-fg`/`*` pair and every token used as TEXT clears 4.5:1 against both
--bg and --bg-raised, in both themes (docs/06 §5). The numbers are not a
matter of taste: tests/unit/styles/contrast.test.ts parses this file and
fails the build if any pair drops below. Re-run it after changing a colour. */
:root {
--bg: #ffffff;
@@ -9,9 +14,13 @@
--fg-muted: #5b6472;
--accent: #6d4aff; /* violet — "magic" identity */
--accent-fg: #ffffff;
--danger: #d8384a;
--success: #1f9d55;
--warn: #b7791f;
/* danger/success/warn are darker than an eyeball would pick, because all
three are used as text on --bg-raised: at the original values they measured
4.27, 3.26 and 3.40 against a 4.5 requirement. */
--danger: #ce3547;
--danger-fg: #ffffff;
--success: #198045;
--warn: #99651a;
--radius: 10px;
--radius-sm: 6px;
@@ -37,12 +46,13 @@
--border: #2b3039;
--fg: #e8eaee;
--fg-muted: #9aa3b0;
--accent: #8b6dff;
--accent: #8f72ff;
/* Dark mode lightens --accent for contrast against --bg, which drops white
ink on it to 3.67:1 — under the 4.5:1 docs/06 §5 requires. --accent-fg must
be redefined alongside it; dark ink on #8b6dff measures 4.84:1. */
ink on it under the 4.5:1 docs/06 §5 requires. --accent-fg must be
redefined alongside it, in the opposite direction. */
--accent-fg: #16181d;
--danger: #ff6b7d;
--danger-fg: #16181d;
--success: #3ecf8e;
--warn: #e2b93b;
}
@@ -54,10 +64,11 @@
--border: #2b3039;
--fg: #e8eaee;
--fg-muted: #9aa3b0;
--accent: #8b6dff;
--accent: #8f72ff;
/* Keep in step with the [data-theme='dark'] block above. */
--accent-fg: #16181d;
--danger: #ff6b7d;
--danger-fg: #16181d;
--success: #3ecf8e;
--warn: #e2b93b;
}
+105
View File
@@ -0,0 +1,105 @@
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { describe, expect, it } from 'vitest';
/**
* docs/06 §5 requires ≥ 4.5:1 contrast "in both themes (tokens chosen
* accordingly)". Nothing enforced that, and they were not: shipping code had
* white ink on the dark-theme accent at 3.67:1 and three status colours used as
* text between 3.26 and 4.27 in light theme.
*
* Parsing the stylesheet rather than hardcoding the palette is the point — the
* test fails when someone edits a colour, which is exactly when it matters.
*/
const TOKENS = readFileSync(join(process.cwd(), 'src/styles/tokens.css'), 'utf8');
const REQUIRED_RATIO = 4.5;
function blockOf(pattern: RegExp): Record<string, string> {
const match = TOKENS.match(pattern);
if (match?.[1] === undefined) throw new Error(`tokens.css: no block matching ${pattern}`);
const out: Record<string, string> = {};
for (const declaration of match[1].matchAll(/(--[a-z-]+):\s*(#[0-9a-f]{6})\b/gi)) {
const [, name, value] = declaration;
if (name !== undefined && value !== undefined) out[name] = value;
}
return out;
}
function relativeLuminance(hex: string): number {
const channels = [1, 3, 5].map((i) => Number.parseInt(hex.slice(i, i + 2), 16) / 255);
const [r, g, b] = channels.map((c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));
return 0.2126 * (r ?? 0) + 0.7152 * (g ?? 0) + 0.0722 * (b ?? 0);
}
function contrast(a: string, b: string): number {
const [lighter, darker] = [relativeLuminance(a), relativeLuminance(b)].sort((x, y) => y - x);
return ((lighter ?? 0) + 0.05) / ((darker ?? 0) + 0.05);
}
const light = blockOf(/:root\s*\{([\s\S]*?)\n\}/);
// The dark block overrides a subset; everything else inherits from :root.
const dark = { ...light, ...blockOf(/\[data-theme='dark'\]\s*\{([\s\S]*?)\n\}/) };
const darkMedia = {
...light,
...blockOf(/:root:not\(\[data-theme='light'\]\)\s*\{([\s\S]*?)\n\s{2}\}/),
};
/** [foreground, background] — every pair where the fg is rendered as TEXT. */
const TEXT_PAIRS: [fg: string, bg: string][] = [
['--fg', '--bg'],
['--fg', '--bg-raised'],
['--fg-muted', '--bg'],
['--fg-muted', '--bg-raised'],
// base.css colours every <a> with --accent, and rows/links sit on both.
['--accent', '--bg'],
['--accent', '--bg-raised'],
// Rendered as text: DuplicatePanel counts, TreePreviewNode badges,
// WarningList's summary.
['--danger', '--bg-raised'],
['--success', '--bg-raised'],
['--warn', '--bg-raised'],
// Ink on a filled control: Button .primary/.danger, ConfirmDialog .danger,
// ThemeToggle .selected.
['--accent-fg', '--accent'],
['--danger-fg', '--danger'],
];
const THEMES: [name: string, tokens: Record<string, string>][] = [
['light', light],
['dark (data-theme)', dark],
['dark (prefers-color-scheme)', darkMedia],
];
describe('token contrast', () => {
it.each(THEMES)('%s meets 4.5:1 on every text pair', (_name, tokens) => {
const failures: string[] = [];
for (const [fg, bg] of TEXT_PAIRS) {
const fgValue = tokens[fg];
const bgValue = tokens[bg];
if (fgValue === undefined || bgValue === undefined) {
failures.push(`${fg} or ${bg} is undefined in this theme`);
continue;
}
const ratio = contrast(fgValue, bgValue);
if (ratio < REQUIRED_RATIO) {
failures.push(`${fg} (${fgValue}) on ${bg} (${bgValue}) = ${ratio.toFixed(2)}:1`);
}
}
expect(failures).toEqual([]);
});
it('keeps the two dark blocks identical', () => {
// tokens.css carries the dark palette twice — once for the explicit
// override and once for prefers-color-scheme. They drifted once already:
// --accent-fg was added to one and not the other.
expect(darkMedia).toEqual(dark);
});
it('defines an explicit ink for every token used as a filled background', () => {
for (const pair of ['accent', 'danger']) {
expect(dark[`--${pair}-fg`], `--${pair}-fg missing from the dark block`).toBeDefined();
expect(light[`--${pair}-fg`], `--${pair}-fg missing from :root`).toBeDefined();
}
});
});