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
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/13008-dark-mode-every-text-and-accent-token-pa → main 2 commits fork
4 files
changed +76
−4
scripts/design-lint.ts +2 −1
| @@ -66,6 +66,7 @@ | ||
| 66 | 66 | import { readdirSync, readFileSync, writeFileSync } from "node:fs"; |
| 67 | 67 | import { join, relative } from "node:path"; |
| 68 | 68 | import { STRANGER_NEVER_SEES } from "../src/design/first_five_minutes.ts"; |
| 69 | import { contrastFindings } from "../src/design/contrast.ts"; | |
| 69 | 70 | import { compareLayout, layoutCounts, scanLayout } from "../src/design/layout.ts"; |
| 70 | 71 | import { motionFindings } from "../src/design/motion.ts"; |
| 71 | 72 | import { cssBlocksAt, scanOverlay, sourceFiles } from "../src/design/overlay.ts"; |
| @@ -591,7 +592,7 @@ if (import.meta.main) { | ||
| 591 | 592 | } else { |
| 592 | 593 | const base: Baseline = JSON.parse(readFileSync(join(root, BASELINE), "utf8")); |
| 593 | 594 | 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()]; | |
| 595 | 596 | for (const p of problems) console.error(p); |
| 596 | 597 | if (problems.length) process.exit(1); |
| 597 | 598 | 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 = { | ||
| 79 | 79 | fg: "#18181b", |
| 80 | 80 | card: "#ffffff", |
| 81 | 81 | muted: "#f4f4f5", |
| 82 | "muted-fg": "#6b7280", | |
| 82 | "muted-fg": "#646b78", | |
| 83 | 83 | faint: "#a1a1aa", |
| 84 | 84 | border: "#e4e4e7", |
| 85 | 85 | "border-strong": "#d4d4d8", |
| @@ -177,7 +177,7 @@ const paper: Palette = { | ||
| 177 | 177 | fg: "#100f0f", |
| 178 | 178 | card: "#fffcf0", |
| 179 | 179 | muted: "#e6e4d9", |
| 180 | "muted-fg": "#6f6e69", | |
| 180 | "muted-fg": "#625f5a", | |
| 181 | 181 | faint: "#b7b5ac", |
| 182 | 182 | border: "#dad8ce", |
| 183 | 183 | "border-strong": "#cecdc3", |
| @@ -226,7 +226,7 @@ const dawn: Palette = { | ||
| 226 | 226 | fg: "#575279", |
| 227 | 227 | card: "#fffaf3", |
| 228 | 228 | muted: "#f2e9e1", |
| 229 | "muted-fg": "#797593", | |
| 229 | "muted-fg": "#625e7c", | |
| 230 | 230 | faint: "#9893a5", |
| 231 | 231 | border: "#dfdad9", |
| 232 | 232 | "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 | }); |
new above
offline