CSS Design Token Contrast Matrix — Audit All fg/bg Pairs for WCAG AA / AAA

Real-world use cases

• A designer audits a full token set before handing it off to engineering

  You've built a 30-color design system palette and are about to hand tokens to the development team. Paste your CSS :root block, select text tokens as fg and surface tokens as bg, and the matrix immediately flags six failing pairs — including the muted label color on the card background. You fix the lightness of three tokens, re-paste, and hand engineering a set where every real-world pair is already AA compliant instead of leaving failures to be discovered in QA.

• A developer validates dark-mode token contracts against WCAG AA

  Your design system ships both light and dark theme JSON files. You paste the dark theme tokens, select foreground text tokens vs background surface tokens, and read the matrix in one glance. Most pairs clear AAA. The secondary text on the elevated surface just hits 3.8:1 — AA-large only. You darken the token one step, copy the new hex, update the JSON file, and commit a fix before the next design review.

• An accessibility consultant audits a client's token file for a VPAT report

  A client sends a Figma-Tokens JSON export before an accessibility audit. You paste it directly into this tool — the nested `{"value": "#hex"}` format is auto-detected — and get a matrix of every color token combination. You screenshot the failing cells (red), note which WCAG criterion each violates (AA normal, AA-large, AAA), and drop the matrix into your VPAT report as evidence. The whole analysis takes under a minute instead of checking pairs manually.

Common pitfalls

• Selecting every token as both fg and bg creates a noisy N×N matrix where many cells (e.g., two background surfaces against each other) are semantically meaningless — pre-filter by role so text tokens go in fg and surface tokens go in bg.

• Trusting a hex from a Figma export that uses opacity or composited layers. This tool grades flat hex-on-hex contrast; if your actual rendered color is a semi-transparent layer, the real contrast may be lower than the raw token value suggests.

• Fixing only the direct-fail cells and ignoring AA-large (orange) cells. AA-large passes for headings 24px+ but fails for body text at 16px — a pair the matrix grades orange is only safe if you can guarantee it is never used on small text.

Privacy