frontend-agents-design-system-validator

name

frontend-agents-design-system-validator

description

Use when auditing a CSS codebase for design-system compliance, reviewing a pull request that touches `.css` / `.scss` / `.ts` / `.tsx` / `.vue` / `.svelte` files with style declarations, hunting for hardcoded color / spacing / font-size / radius values that bypass the design-token layer, validating that components consume semantic tokens (not primitive tokens directly), confirming the three-tier token chain (primitive -> semantic -> component) is intact, verifying the `@layer tokens, theme, base, components, utilities;` cascade-layer order is declared at the project root, checking that animatable custom properties are `@property`- registered for proper interpolation, sweeping for orphaned tokens (defined but never referenced) or dangling references (`var(--undefined)` with no `@property` default), and confirming WCAG 1.4.3 / 1.4.11 contrast ratios hold for every text-on- background and UI-component pair in both light and dark variants. Use as a checklist agents and reviewers apply BEFORE merging UI changes, not as a runtime feature. Prevents the six dominant design-system-drift failure modes : hardcoded color values (`#3b82f6`, `rgb(...)`, `oklch(...)`) outside the `@layer tokens` block where authors slip raw values into components, components reaching directly into primitive tokens (`var(--brand-blue-500)`) instead of going through a semantic layer (`var(--color-action-primary)`) so a brand color change propagates to every consumer, non-namespaced custom- property names (`--color-1`, `--my-thing`) that drift over time because they lack a discoverable convention, animatable tokens that are not `@property`-registered so transitions snap instead of interpolate, semantic tokens defined for light mode only with no dark-mode variant (the design system has a "dark mode" feature that breaks the moment a new token is introduced), and `!important` declarations leaking out of the `utilities` layer because the cascade-layer discipline was abandoned. Covers the deterministic validation checklist (token usage, three- tier chain, naming convention, `@layer` order, `@property` registration, orphan detection, dark / light parity), the canonical audit-report shape (path : line : severity : violation : suggested fix, with severity = error / warning / info), the grep recipes for raw color hunting (`#[0-9a-f]{3,8}`, `rgb\\(`, `rgba\\(`, `hsl\\(`, `oklch\\(`, `oklab\\(` outside the token layer), the orphan-token detection methodology (extract all `--*:` declarations, extract all `var(--*)` references, diff), the WCAG 1.4.3 Contrast (Minimum) thresholds (4.5:1 normal, 3:1 large text where large = 18 pt or 14 pt bold), the WCAG 1.4.11 Non-Text Contrast threshold (3:1 for UI components and graphical objects), and the suggested-fix pattern for each violation class. Keywords: design system, design system validator, design tokens, token validator, token audit, audit tokens, design system review, design system drift, design system lint, hardcoded color audit, primitive token, semantic token, component token, three-tier tokens, three-tier chain, var, custom property, css custom property, --color-, --space-, --font-size-, --radius-, --shadow-, cascade layers, @layer tokens, @property, @property registration, WCAG 1.4.3, WCAG 1.4.11, contrast ratio, 4.5:1, 3:1, orphan token, dangling reference, theme coherence, light dark parity, dark mode parity, hex color in component, magic spacing number, magic value, hardcoded color sneaking in, brand color override, tokens not loaded, palette inconsistent, contrast failing, dark mode broken, design system drift, how to validate design system, how to audit tokens, how to find hardcoded colors in CSS, design system review checklist, design token linting, how do I enforce tokens, PR design system review.