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:
5 files changed
+148
-12
No files matched your search
+20
-2
@@ -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).
|
||||
|
||||
@@ -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>
|
||||
@@ -77,6 +77,6 @@
|
||||
.danger {
|
||||
background: var(--danger);
|
||||
border-color: var(--danger);
|
||||
color: #fff;
|
||||
color: var(--danger-fg);
|
||||
}
|
||||
</style>
|
||||
+19
-8
@@ -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;
|
||||
}
|
||||
|
||||
@@ -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();
|
||||
}
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user