// The four CSS rules scripts/check-design-system.ts runs over the token // files and src/presentation/styles/**. Each rule takes file contents and // returns failure messages, so a test can hand it a violation directly. import { contrastRatio, resolveColor, resolveValue } from "./oklch-contrast.ts"; export interface CssSource { readonly file: string; readonly source: string; } // Comments keep old code around, and the browser never draws it. // Limit: a "/*" inside a quoted string would start a false comment. No // CSS here has one; switch to a CSS tokenizer if that changes. function withoutComments(css: string): string { return css.replace(/\/\*[\s\S]*?\*\//g, ""); } // 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. export 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; // A colour-mix() or translucent value depends on what is drawn beneath it, // so the rule refuses it rather than guess (12-04). The message says which // token and which form it can compute. export function focusContrastFailures( theme: string, properties: ReadonlyMap, ): string[] { const unreadable = (token: string) => `${theme} ${token} is ${resolveValue(token, properties) ?? "not defined"}; ` + "contrast needs an opaque oklch(L C H), hue in degrees with or without deg"; const focus = resolveColor("--color-focus", properties); if (!focus) return [unreadable("--color-focus")]; const failures: string[] = []; for (const background of FOCUS_RING_BACKGROUNDS) { const surface = resolveColor(background, properties); if (!surface) { failures.push(unreadable(background)); 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`, ); } } return failures; } // UI-02. Hue-based spaces interpolate the hue angle, and an achromatic // stop such as oklch(1 0 0) carries hue 0: 14% blue into white came out // pink. oklab mixes on straight lines and has no hue to drag. CSS // function names and keywords ignore ASCII case, so OKLCH counts too. export function hueMixFailures({ file, source }: CssSource): string[] { const mixes = withoutComments(source).matchAll( /color-mix\(\s*in\s+(oklch|lch|hsl|hwb)\b/gi, ); return [...mixes].map((match) => `${file} mixes colours in ${match[1]}; use oklab`); } // UI-03. A component token nobody reads is a second copy of a decision: // the style that should use it repeats the formula instead, and a product // that rebrands through the token sees nothing change. // A read is var(--name) or var(--name, fallback) with the whole name: a // prefix match took var(--field-border-invalid) for a read of // --field-border (12-01). "var" ignores case; custom property names don't. export function unreadTokenFailures( tokens: readonly string[], styles: readonly CssSource[], ): string[] { const read = new Set( styles.flatMap(({ source }) => [...withoutComments(source).matchAll(/var\(\s*(--[^\s,)]+)\s*[,)]/gi)] .map((match) => match[1]), ), ); return tokens .filter((token) => !read.has(token)) .map((token) => `component token ${token} is defined but no style reads it`); } // UI-05. --font-sans named Inter first, but nothing loads Inter, so most // machines drew another font and Hangul never came from Inter at all. // The first family must be a generic keyword, a browser name for the // system font, one this repo ships, or one the product declares it loads // (PRODUCT_LOADED_FONT_FAMILIES in token-contract.ts, 12-04). const GENERIC_FONT_FAMILIES = new Set([ "system-ui", "-apple-system", "BlinkMacSystemFont", "ui-sans-serif", "ui-serif", "ui-monospace", "sans-serif", "serif", "monospace", ]); export function firstFontFamilyFailures( fontSans: string, styles: readonly CssSource[], productLoaded: readonly string[] = [], ): string[] { const shipped = new Set([ ...productLoaded, ...styles.flatMap(({ source }) => [...source.matchAll(/@font-face\s*\{[^}]*font-family:\s*["']?([^;"']+)/g)] .map((match) => match[1].trim()), ), ]); const first = fontSans.split(",")[0]?.trim().replace(/^["']|["']$/g, "") ?? ""; if (GENERIC_FONT_FAMILIES.has(first) || shipped.has(first)) return []; return [ `--font-sans starts with "${first}", which is neither a generic family, loaded by @font-face, nor listed in PRODUCT_LOADED_FONT_FAMILIES`, ]; }