Design Token Contrast

Design Token Contrast checks CSS custom properties to locate contrast problems at the token level. Its Node checker pairs text colors with backgrounds, measures each pair in light and dark themes, and proposes a color with the same hue and the nearest lightness that passes. It also proposes one value per token that passes across every background measured for that token, allowing a shared token change to address its uses together.

The checker applies WCAG 2.2 AA minimums of 4.5:1 for normal text and 3:1 for large text under 1.4.3. UI components and graphics, including input borders, icons, and focus rings, use 3:1 under 1.4.11. Each pair receives an OK or NO result with its ratio, required minimum, and suggested correction.

Use the skill when changing a palette, adding a color, approving a light or dark theme, checking whether text is readable against a background, or responding to an accessibility audit that flagged contrast. Both themes need checking before declaring the palette passing.

Token measurements cannot establish the contrast of rendered pixels over images or gradients. Those cases require a capture and a check of the worst spot. Text opacity, hard-coded colors outside the token system, hover states, and informative placeholders also need inspection. Disabled states are exempt from the threshold but should remain distinguishable. The skill does not replace environment-specific validation, testing, or expert review.

The checker is supplied as JavaScript source in references/contraste-checker.md. Save that block as contraste.mjs in a scratch directory and run it with Node 18+; it requires no dependencies.

node contraste.mjs --tokens src/styles/tokens.css

Without an explicit tokens argument, it checks common locations including src/styles/tokens.css. It reads --color-* variables expressed as hex, rgb(), hsl(), or oklch(), resolves var(--other), and distinguishes the default theme from prefers-color-scheme: dark, .dark, or [data-theme=dark] blocks. Incorrectly placed dark variables can make a dark pair appear to pass against a light background.

Automatic pairing recognizes text, foreground, link, and focus names alongside background, bg, surface, card, and canvas names. Spanish names such as texto, fondo, superficie, and tarjeta are recognized too. For unconventional names, a JSON file supplied with --pares defines explicit pairs using texto, fondo, and tipo keys; tipo is texto or ui.

The --todos option compares every color with every other color for palette exploration. The --json option writes results for further processing. Console output is Spanish, while ratios and token names remain directly readable.

The final report lists each pair, its current ratio, minimum, suggestion, and where it is used. Finding classes and var(--color-...) references supplies the usage locations. Proposed remedies include darkening a token, reserving it for large text, or introducing --color-accent-text for small text while retaining the original for fills and borders. Changes, including brand-color changes, require user approval, followed by another measurement.

The checker reads the specified CSS or JSON file and writes a file only when --json is requested. It makes no network requests, installs nothing, and never edits tokens automatically. The related @wcag-audit-patterns skill covers broader WCAG 2.2 auditing beyond color contrast.