// The CSS rules scripts/check-design-system.ts runs over the token files and // the style sheets. 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. They turn // into spaces, newlines kept, so a reported line number stays the file's. // 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, (comment) => comment.replace(/[^\n]/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. // A gradient interpolates the same way (`linear-gradient(90deg in oklch, // …)`), and an inline style in TSX is CSS too (1101/12-03). const HUE_MIX = /(?:color-mix\(\s*|(?:repeating-)?(?:linear|radial|conic)-gradient\([^,()]*?)\bin\s+(oklch|lch|hsl|hwb)\b/gi; export function hueMixFailures({ file, source }: CssSource): string[] { const mixes = withoutComments(source).matchAll(HUE_MIX); 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[], layer: "component" | "semantic" = "component", ): 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) => `${layer} token ${token} is defined but no style reads it`); } // UI-03 (contract). A component token outside REQUIRED_COMPONENT_TOKENS is // outside UI-03 too: the reader check only walks the contract list, so a // token defined in component.css and read by nothing passed (1112/04-12). // Only the @theme block counts: the forced-colors block redefines semantic // roles, not component tokens. export function undeclaredComponentTokenFailures( { file, source }: CssSource, contract: readonly string[], ): string[] { const theme = /@theme\s*\{([\s\S]*?)\n\}/.exec(withoutComments(source))?.[1] ?? ""; return [...theme.matchAll(/(--[a-z0-9-]+)\s*:/g)] .map((match) => match[1]) .filter((token) => !contract.includes(token)) .map( (token) => `${file} defines ${token}, which REQUIRED_COMPONENT_TOKENS in token-contract.ts does not list`, ); } // 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`, ]; } // UI-07. The semantic layer names roles and reads its colours from the // palette in primitive.css. A colour written straight into semantic.css is // out of reach of a rebrand that edits the palette: 36 such values kept the // status colours, the focus ring and most of the dark theme as they were // (1112/04-13). const RAW_COLOUR = /#[0-9a-f]{3,8}\b|\b(?:oklch|oklab|lch|lab|rgba?|hsla?|hwb|color)\(/i; export function rawSemanticColourFailures({ file, source }: CssSource): string[] { return [...withoutComments(source).matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/gi)] .filter((match) => RAW_COLOUR.test(match[2])) .map( (match) => `${file} ${match[1]} is the raw colour ${match[2].trim()}; name it in primitive.css and read it with var()`, ); } // UI-06. A style that writes a spacing, type, radius, layer or shadow value // by hand does not move when the token does: changing --space-*, --layer-*, // --elevation-panel or --radius-modal left the shell, the page templates and // the cards as they were (1112/04-08). Allowed: a token read (var()), 0, // auto, keywords, %, viewport units, a 1px hairline in margin or padding, // line-height 1, z-index 0 or -1, and em sizes relative to the parent font. const LENGTH = /(? !["1px", "-1px"].includes(length)); if (property === "font-size") return lengths.filter((length) => !/(? item !== "1"); if (/^border(?:-[a-z]+)*-radius$/.test(property)) return lengths; if (property === "z-index") return numbers.filter((item) => !["0", "-1"].includes(item)); if (property === "box-shadow") return [...lengths, ...numbers]; return []; } export function rawStyleValueFailures({ file, source }: CssSource): string[] { const css = withoutComments(source); const failures: string[] = []; for (const match of css.matchAll(/(? !match[1].startsWith("--") && RAW_COLOUR.test(match[2])) .map((match) => `${file} ${match[1]}: ${match[2].trim()} is a raw colour; read a colour token`); } export function tokenRedefinitionFailures( { file, source }: CssSource, tokens: ReadonlySet, ): string[] { return [...withoutComments(source).matchAll(/(? tokens.has(match[1])) .map((match) => `${file} redefines the token ${match[1]}; change it in the token files`); } export function focusOffsetFailures({ file, source }: CssSource): string[] { return [...withoutComments(source).matchAll(/outline-offset\s*:\s*([^;{}]+);/g)] .filter((match) => /^(?:-|0(?:\.0*)?(?:px|rem|em)?\s*$)/.test(match[1].trim())) .map( (match) => `${file} outline-offset: ${match[1].trim()} draws the focus ring on the control; UI-01 measures it against the surface around the control`, ); } // 1112/04-14 (decision 2026-11-12). Primitives keep `className` and `style` // open, so a screen can lay a raw colour or spacing over a primitive. An // inline style may place things and read tokens; a colour or a spacing, // type, radius, layer or shadow value written by hand is refused. // The scale values are judged as UI-06 judges a style sheet: an inline // style is the same declaration written in camelCase, and React writes a bare // number as px except for the unitless properties. const INLINE_COLOUR_KEYWORDS = new Set(["transparent", "currentcolor", "inherit", "initial", "unset", "none"]); const INLINE_COLOUR_PROPERTY = /^(?:color|background|fill|stroke)$|Color$/; const INLINE_UNITLESS = new Set(["zIndex", "fontWeight", "lineHeight", "opacity", "flex", "flexGrow", "flexShrink", "order"]); export function inlineStyleFailures({ file, source }: CssSource): string[] { const failures: string[] = []; for (const style of source.matchAll(/style=\{\{([\s\S]*?)\}\}/g)) { for (const entry of style[1].matchAll(/([A-Za-z]+)\s*:\s*(`[^`]*`|"[^"]*"|'[^']*'|-?[\d.]+)/g)) { const [, property, written] = entry; const value = written.replace(/^[`"']|[`"']$/g, "").trim(); const colour = INLINE_COLOUR_PROPERTY.test(property) && !/^var\(/.test(value) && !INLINE_COLOUR_KEYWORDS.has(value.toLowerCase()); const css = /^-?[\d.]+$/.test(written) && !INLINE_UNITLESS.has(property) && Number(value) !== 0 ? `${value}px` : value; const scale = handWrittenValues(property.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`), css).length > 0; if (colour || scale) { failures.push(`${file} style ${property}: ${written} is written by hand; read a token or use a primitive variant`); } } } return failures; }