From 35b183b64f50d3a235710ee93c708e81c981391c Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 18:34:28 +0900 Subject: [PATCH] =?UTF-8?q?fix(design-system):=20=EB=9D=BC=EC=9D=B4?= =?UTF-8?q?=ED=8A=B8=20=ED=8F=AC=EC=BB=A4=EC=8A=A4=20=EB=A7=81=EC=9D=B4=20?= =?UTF-8?q?=EB=AA=A8=EB=93=A0=20=ED=91=9C=EB=A9=B4=EC=97=90=EC=84=9C=203:1?= =?UTF-8?q?=EC=9D=84=20=EB=84=98=EA=B2=8C=20=ED=95=9C=EB=8B=A4=20(UI-01)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 라이트 --color-focus가 흰 패널에서 2.33:1, surface-muted에서 1.95:1로 WCAG 1.4.11 기준(3:1)에 못 미쳤다. 포커스 링은 컨트롤에서 3px 떨어져 그려지므로, 대비를 따질 인접색은 컨트롤 뒤의 표면이다. 라이트 포커스를 oklch(0.52 0.15 230)으로 바꿨다. 가장 낮은 대비가 4.24:1이다. 다크는 그대로다. check:design-system이 두 테마에서 포커스 토큰과 표면 토큰 8종의 대비를 계산하고, 3:1 미만이면 실패한다. 안팎 이중 링은 버렸다. 한 색으로 충분하고 링 모양이 바뀌지 않는다. 위험: 포커스 링 색이 진해져 시각 골든이 바뀐다(별도 커밋에서 갱신). 검증: 토큰을 바꾸기 전 검사가 라이트 표면 8종 모두에서 실패했고, 바꾼 뒤 통과했다. 계산식은 브라우저 실측값 2.33:1과 일치한다 (tests/unit/oklch-contrast.test.ts). --- scripts/check-design-system.ts | 42 ++++++++++++ scripts/lib/oklch-contrast.ts | 66 +++++++++++++++++++ .../design-system/tokens/semantic.css | 2 +- tests/unit/oklch-contrast.test.ts | 43 ++++++++++++ 4 files changed, 152 insertions(+), 1 deletion(-) create mode 100644 scripts/lib/oklch-contrast.ts create mode 100644 tests/unit/oklch-contrast.test.ts diff --git a/scripts/check-design-system.ts b/scripts/check-design-system.ts index b5f76f8f..c3ef2b39 100644 --- a/scripts/check-design-system.ts +++ b/scripts/check-design-system.ts @@ -5,6 +5,7 @@ import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts"; import path from "node:path"; import { REQUIRED_COMPONENT_TOKENS, REQUIRED_PRIMITIVE_TOKENS, REQUIRED_SEMANTIC_TOKENS } from "../src/presentation/design-system/tokens/token-contract.ts"; +import { contrastRatio, readCustomProperties, resolveColor } from "./lib/oklch-contrast.ts"; const fixtureMode = process.argv.includes("--fixture"); const failures: string[] = []; @@ -77,6 +78,47 @@ for (const token of [ failures.push(`dark theme token is missing: ${token}`); } } +// UI-01. The focus ring is drawn 3px away from its control, so the colour +// next to it is the surface behind the control, not the control itself. +// WCAG 1.4.11 asks 3:1 against that neighbour, in both themes. +const FOCUS_RING_BACKGROUNDS = [ + "--color-surface", + "--color-surface-muted", + "--color-panel", + "--color-surface-elevated", + "--color-info-surface", + "--color-success-surface", + "--color-warning-surface", + "--color-danger-surface", +] as const; +const lightProperties = new Map([ + ...readCustomProperties(await readFile(tokenFiles.primitive, "utf8")), + ...readCustomProperties(semanticSource.split(':root[data-theme="dark"]')[0]), +]); +const darkProperties = new Map([ + ...lightProperties, + ...readCustomProperties(darkSource), +]); +for (const [theme, properties] of [ + ["light", lightProperties], + ["dark", darkProperties], +] as const) { + const focus = resolveColor("--color-focus", properties); + for (const background of FOCUS_RING_BACKGROUNDS) { + const surface = resolveColor(background, properties); + if (!focus || !surface) { + failures.push(`${theme} --color-focus or ${background} is not a plain oklch() value`); + continue; + } + const ratio = contrastRatio(focus, surface); + if (ratio < 3) { + failures.push( + `${theme} --color-focus contrast ${ratio.toFixed(2)}:1 against ${background} is below 3:1`, + ); + } + } +} + const componentSource = await readFile(tokenFiles.component, "utf8"); if (!componentSource.includes("@media (forced-colors: active)")) { failures.push("forced-colors token fallback is missing"); diff --git a/scripts/lib/oklch-contrast.ts b/scripts/lib/oklch-contrast.ts new file mode 100644 index 00000000..6cf468fa --- /dev/null +++ b/scripts/lib/oklch-contrast.ts @@ -0,0 +1,66 @@ +// WCAG contrast for design tokens written as oklch(). The conversion is +// OKLab -> linear sRGB (Björn Ottosson's matrices) with a plain clip to the +// sRGB gamut, which is what the browser draws for every token we ship. + +export interface Oklch { + readonly l: number; + readonly c: number; + readonly h: number; +} + +export function parseOklch(value: string): Oklch | null { + const match = + /^oklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+([\d.]+|none)\s*\)$/.exec( + value.trim(), + ); + if (!match) return null; + return { + l: Number(match[1]) / (match[2] === "%" ? 100 : 1), + c: Number(match[3]), + h: match[4] === "none" ? 0 : Number(match[4]), + }; +} + +export function relativeLuminance({ l, c, h }: Oklch): number { + const hue = (h * Math.PI) / 180; + const a = c * Math.cos(hue); + const b = c * Math.sin(hue); + const long = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3; + const medium = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3; + const short = (l - 0.0894841775 * a - 1.291485548 * b) ** 3; + const clip = (channel: number) => Math.min(1, Math.max(0, channel)); + const red = clip(4.0767416621 * long - 3.3077115913 * medium + 0.2309699292 * short); + const green = clip(-1.2684380046 * long + 2.6097574011 * medium - 0.3413193965 * short); + const blue = clip(-0.0041960863 * long - 0.7034186147 * medium + 1.707614701 * short); + return 0.2126 * red + 0.7152 * green + 0.0722 * blue; +} + +export function contrastRatio(first: Oklch, second: Oklch): number { + const [lighter, darker] = [relativeLuminance(first), relativeLuminance(second)] + .sort((x, y) => y - x); + return (lighter + 0.05) / (darker + 0.05); +} + +export function readCustomProperties(css: string): Map { + return new Map( + [...css.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)].map( + (match) => [match[1], match[2].trim()] as const, + ), + ); +} + +// Follows var(--x) chains. Returns null for anything that is not a plain +// oklch() at the end of the chain (color-mix, keywords), so callers fail +// loudly instead of guessing. +export function resolveColor( + token: string, + properties: ReadonlyMap, +): Oklch | null { + let value = properties.get(token); + for (let depth = 0; value !== undefined && depth < 8; depth += 1) { + const reference = /^var\((--[a-z0-9-]+)\)$/.exec(value); + if (!reference) return parseOklch(value); + value = properties.get(reference[1]); + } + return null; +} diff --git a/src/presentation/design-system/tokens/semantic.css b/src/presentation/design-system/tokens/semantic.css index fe8bd768..19174cff 100644 --- a/src/presentation/design-system/tokens/semantic.css +++ b/src/presentation/design-system/tokens/semantic.css @@ -14,7 +14,7 @@ --color-danger: var(--palette-red-600); --color-danger-hover: var(--palette-red-700); --color-on-action: var(--palette-white); - --color-focus: oklch(0.72 0.16 225); + --color-focus: oklch(0.52 0.15 230); --color-disabled-content: color-mix(in oklch, var(--color-content) 55%, transparent); --color-disabled-surface: var(--color-surface-muted); --color-info-content: oklch(0.38 0.16 255); diff --git a/tests/unit/oklch-contrast.test.ts b/tests/unit/oklch-contrast.test.ts new file mode 100644 index 00000000..e6b0fffb --- /dev/null +++ b/tests/unit/oklch-contrast.test.ts @@ -0,0 +1,43 @@ +import { describe, expect, it } from "vitest"; + +import { + contrastRatio, + parseOklch, + readCustomProperties, + resolveColor, +} from "../../scripts/lib/oklch-contrast.ts"; + +const color = (value: string) => { + const parsed = parseOklch(value); + if (!parsed) throw new Error(`not an oklch value: ${value}`); + return parsed; +}; + +describe("oklch contrast", () => { + it("gives 21:1 for white on black", () => { + expect(contrastRatio(color("oklch(1 0 0)"), color("oklch(0 0 0)"))).toBeCloseTo(21, 1); + }); + + // UI-01: the old light focus ring measured 2.33:1 on white in Chromium. + it("matches the ratio the browser measured for the old focus ring", () => { + expect( + contrastRatio(color("oklch(0.72 0.16 225)"), color("oklch(1 0 0)")), + ).toBeCloseTo(2.33, 1); + }); + + it("reads percentages and a missing hue", () => { + expect(parseOklch("oklch(50% 0.1 none)")).toEqual({ l: 0.5, c: 0.1, h: 0 }); + expect(parseOklch("color-mix(in oklab, red, blue)")).toBeNull(); + }); + + it("follows var() chains and refuses values it cannot draw", () => { + const properties = readCustomProperties(` + --palette-white: oklch(1 0 0); + --color-panel: var(--palette-white); + --color-mixed: color-mix(in oklab, var(--palette-white) 50%, transparent); + `); + expect(resolveColor("--color-panel", properties)).toEqual({ l: 1, c: 0, h: 0 }); + expect(resolveColor("--color-mixed", properties)).toBeNull(); + expect(resolveColor("--color-missing", properties)).toBeNull(); + }); +});