Public: anyone can read this; the crew can change it.

Dark mode: every text and accent token pair meets 4.5:1, enforced in design-lint #13018

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

torque/forge:torque/13008-dark-mode-every-text-and-accent-token-pa → main 2 commits fork

  • Merged. torque/13008-dark-mode-every-text-and-accent-token-pa was merged into main as 15c4aca.

Review

Sign in to review this change.
4 files changed +76 −4
scripts/design-lint.ts +2 −1
@@ -66,6 +66,7 @@
6666 import { readdirSync, readFileSync, writeFileSync } from "node:fs";
6767 import { join, relative } from "node:path";
6868 import { STRANGER_NEVER_SEES } from "../src/design/first_five_minutes.ts";
69 import { contrastFindings } from "../src/design/contrast.ts";
6970 import { compareLayout, layoutCounts, scanLayout } from "../src/design/layout.ts";
7071 import { motionFindings } from "../src/design/motion.ts";
7172 import { cssBlocksAt, scanOverlay, sourceFiles } from "../src/design/overlay.ts";
@@ -591,7 +592,7 @@ if (import.meta.main) {
591592 } else {
592593 const base: Baseline = JSON.parse(readFileSync(join(root, BASELINE), "utf8"));
593594 const debt: QuietDebt = JSON.parse(readFileSync(join(root, QUIET_DEBT), "utf8"));
594 const problems = [...compare(base, now, designText(root), areaFiles(root)), ...compareQuiet(debt, scanQuiet(root)), ...scanBanner(root), ...compareLayout(base.layout ?? {}, scanLayout(root)), ...scanOverlay(root), ...scanCards(root), ...scanStranger(root), ...scanMotion(root)];
595 const problems = [...compare(base, now, designText(root), areaFiles(root)), ...compareQuiet(debt, scanQuiet(root)), ...scanBanner(root), ...compareLayout(base.layout ?? {}, scanLayout(root)), ...scanOverlay(root), ...scanCards(root), ...scanStranger(root), ...scanMotion(root), ...contrastFindings()];
595596 for (const p of problems) console.error(p);
596597 if (problems.length) process.exit(1);
597598 console.log("design: no colour, size or component added outside the system");
src/design/contrast.ts added +52
@@ -0,0 +1,52 @@
1 /**
2 * Contrast (#13008): every text and accent token pair in every theme meets 4.5:1.
3 * Formula: WCAG 2.x relative luminance and contrast ratio,
4 * https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio —
5 * (L1 + 0.05) / (L2 + 0.05), L1 the lighter.
6 */
7 import { THEMES, type Palette } from "./themes.ts";
8
9 export const MIN_CONTRAST = 4.5;
10
11 /** [foreground, background] token pairs that carry text or interaction. */
12 export const PAIRS: readonly (readonly [keyof Palette, keyof Palette])[] = [
13 ["fg", "bg"],
14 ["fg", "card"],
15 ["fg", "muted"],
16 ["muted-fg", "bg"],
17 ["muted-fg", "card"],
18 ["muted-fg", "muted"],
19 ["accent", "bg"],
20 ["accent", "card"],
21 ["accent-fg", "accent"],
22 ["primary-fg", "primary"],
23 ];
24
25 /** WCAG relative luminance of a #rrggbb colour (sRGB channels linearised). */
26 export function luminance(hex: string): number {
27 const m = /^#([0-9a-f]{6})$/i.exec(hex);
28 if (!m) throw new Error(`not a #rrggbb colour: ${hex}`);
29 const [r, g, b] = [0, 2, 4].map((i) => {
30 const c = parseInt(m[1]!.slice(i, i + 2), 16) / 255;
31 return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
32 }) as [number, number, number];
33 return 0.2126 * r + 0.7152 * g + 0.0722 * b;
34 }
35
36 /** Contrast ratio, 1 to 21. */
37 export function contrast(a: string, b: string): number {
38 const [x, y] = [luminance(a), luminance(b)];
39 return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05);
40 }
41
42 /** One line per failing pair, in every theme. */
43 export function contrastFindings(themes: Record<string, { tokens: Palette }> = THEMES): string[] {
44 const out: string[] = [];
45 for (const [name, t] of Object.entries(themes)) {
46 for (const [f, b] of PAIRS) {
47 const r = contrast(t.tokens[f], t.tokens[b]);
48 if (r < MIN_CONTRAST) out.push(`theme ${name}: --${f} ${t.tokens[f]} on --${b} ${t.tokens[b]} is ${r.toFixed(2)}:1, below ${MIN_CONTRAST}:1 (src/design/themes.ts)`);
49 }
50 }
51 return out;
52 }
src/design/themes.ts +3 −3
@@ -79,7 +79,7 @@ const porcelain: Palette = {
7979 fg: "#18181b",
8080 card: "#ffffff",
8181 muted: "#f4f4f5",
82 "muted-fg": "#6b7280",
82 "muted-fg": "#646b78",
8383 faint: "#a1a1aa",
8484 border: "#e4e4e7",
8585 "border-strong": "#d4d4d8",
@@ -177,7 +177,7 @@ const paper: Palette = {
177177 fg: "#100f0f",
178178 card: "#fffcf0",
179179 muted: "#e6e4d9",
180 "muted-fg": "#6f6e69",
180 "muted-fg": "#625f5a",
181181 faint: "#b7b5ac",
182182 border: "#dad8ce",
183183 "border-strong": "#cecdc3",
@@ -226,7 +226,7 @@ const dawn: Palette = {
226226 fg: "#575279",
227227 card: "#fffaf3",
228228 muted: "#f2e9e1",
229 "muted-fg": "#797593",
229 "muted-fg": "#625e7c",
230230 faint: "#9893a5",
231231 border: "#dfdad9",
232232 "border-strong": "#cecacd",
test/contrast.test.ts added +19
@@ -0,0 +1,19 @@
1 import { describe, expect, test } from "bun:test";
2 import { contrast, contrastFindings } from "../src/design/contrast.ts";
3 import { THEMES } from "../src/design/themes.ts";
4
5 describe("contrast (#13008)", () => {
6 test("matches hand calculation: black on white is 21:1, #767676 on white is 4.54:1", () => {
7 expect(contrast("#000000", "#ffffff")).toBeCloseTo(21, 5);
8 expect(contrast("#767676", "#ffffff")).toBeCloseTo(4.54, 2);
9 });
10 test("every theme, light and dark, meets 4.5:1 on every text and accent pair", () => {
11 expect(contrastFindings()).toEqual([]);
12 });
13 test("a failing pair is named with theme, tokens and ratio", () => {
14 const bad = { ...THEMES.dark, tokens: { ...THEMES.dark.tokens, "muted-fg": "#333333" } };
15 const f = contrastFindings({ dark: bad });
16 expect(f.length).toBeGreaterThan(0);
17 expect(f[0]).toMatch(/theme dark: --muted-fg #333333 on --bg .* below 4\.5:1/);
18 });
19 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs