Design Token Contrast
Overview
Measures contrast on the tokens, not on screens: a problem fixed in a token is fixed
everywhere it is used. A Node checker, shipped as source in
references/contraste-checker.md, reads the CSS custom properties
of the project, pairs text tokens with background tokens, measures each pair in the light theme
and in dark mode, and, for every pair that fails, proposes the color with the same hue and the
nearest lightness that passes. It also proposes one value per token that passes against every
background it is measured on, so the fix is a single change.
WCAG 2.2 AA minimums it applies: normal text 4.5:1 (1.4.3), large text 3:1, and UI
components and graphics such as input borders, icons and focus rings 3:1 (1.4.11).
When to Use This Skill
- Use when the palette changes, a color is added, or a light or dark theme is about to be approved.
- Use when the user asks whether a text color is readable on its background.
- Use when an accessibility audit flags contrast and you want the fix at the token level.
How It Works
Step 1: Run the measurement
The checker ships as source, not as a committed script: save the JavaScript block in
references/contraste-checker.md as contraste.mjs in a
scratch directory (no dependencies, Node 18+), then run it:
node contraste.mjs --tokens src/styles/tokens.css
Without --tokens it looks for src/styles/tokens.css and other common locations. The script:
- Reads
--color-* variables in hex, rgb(), hsl() or oklch(), resolves var(--other), and
separates the default theme from dark mode (prefers-color-scheme: dark, .dark or
[data-theme=dark]).
- Pairs tokens by name: text tokens (
text, foreground, link, focus…) over background tokens
(background, bg, surface, card, canvas…). Spanish token names (texto, fondo,
superficie, tarjeta) are recognized too.
- Prints
OK or NO per pair, with the ratio, the minimum and the suggestion.
If token names do not follow that pattern, write the real pairs to a JSON file and pass it with
--pares (the keys are texto, fondo and tipo, where tipo is texto or ui):
[{"texto": "--color-gray-500", "fondo": "--color-white", "tipo": "texto"},
{"texto": "--color-input-border", "fondo": "--color-white", "tipo": "ui"}]
To explore a new palette, --todos measures every color against every other. --json out.json
writes the results for further processing. The script's output is in Spanish; ratios and token
names read the same in any language.
Step 2: Check what the script cannot see
- Text over images or gradients: capture the section and check the worst spot.
- Text with opacity, or colors hard-coded outside the tokens (search for
#[0-9a-fA-F]{3,8},
rgb(, text-[#).
- States:
hover, disabled (exempt, but still distinguishable), and placeholders that carry
information.
Step 3: Report and propose
| Pair |
Now |
Minimum |
Suggestion |
Where it is used |
Search for the classes and var(--color-...) references to fill "where it is used".
Examples
Example 1: A gray that fails on white
== tema claro (por defecto): 4 colores leídos ==
NO 3.54:1 (mín. 4.5) --color-text #888888 sobre --color-background #ffffff
sugerencia para --color-text: oklch(56.2% 0.000 89.9) (#757575) → 4.62:1
Propose #767676 for --color-text (the single value that passes on all its backgrounds), apply
it only after the user agrees, and run the script again to show it passes.
Best Practices
- ✅ Fix the token once instead of patching each screen.
- ✅ Offer options: darken the token, keep the color only for large text, or add a new token
(
--color-accent-text) for small text and keep the original for fills and borders.
- ❌ Don't change brand colors without asking.
- ❌ Don't report a theme as passing without checking dark mode too.
Limitations
- It measures tokens, not rendered pixels: images, gradients and opacity need a visual check.
- Pairing by name is a heuristic; use
--pares when names are unconventional.
- This skill does not replace environment-specific validation, testing, or expert review.
Security & Safety Notes
- The script only reads the CSS or JSON file you point it to and writes a file only with
--json.
It makes no network requests and installs nothing. Requires Node 18+.
- It never edits tokens by itself; changes are proposed and applied after the user approves.
Common Pitfalls
- Problem: A dark-mode pair shows
OK against the light background.
Solution: Make sure dark-mode variables live in a prefers-color-scheme: dark, .dark or
[data-theme=dark] block so the script can separate the themes.
Related Skills
@wcag-audit-patterns - For a full WCAG 2.2 audit beyond color contrast.
1---2name: design-token-contrast3description: "Checks WCAG 2.2 contrast between the color tokens of a project (light and dark theme) and suggests the closest passing color that keeps the hue."4category: frontend5risk: safe6source: community7source_repo: Clagoss/claude-code-para-disenadores8source_type: community9date_added: "2026-10-19"10author: Clagoss11tags: [accessibility, wcag, contrast, design-tokens, css, dark-mode]12tools: [claude, cursor, gemini]13license: "MIT"14license_source: "https://github.com/Clagoss/claude-code-para-disenadores/blob/main/LICENSE"15metadata:16 source: https://skillmd.com/skills/iradoweck/design-token-contrast17---1819# Design Token Contrast2021## Overview2223Measures contrast on the **tokens**, not on screens: a problem fixed in a token is fixed24everywhere it is used. A Node checker, shipped as source in25[references/contraste-checker.md](references/contraste-checker.md), reads the CSS custom properties26of the project, pairs text tokens with background tokens, measures each pair in the light theme27and in dark mode, and, for every pair that fails, proposes the color with the same hue and the28nearest lightness that passes. It also proposes **one value per token** that passes against every29background it is measured on, so the fix is a single change.3031WCAG 2.2 AA minimums it applies: normal text **4.5:1** (1.4.3), large text **3:1**, and UI32components and graphics such as input borders, icons and focus rings **3:1** (1.4.11).3334## When to Use This Skill3536- Use when the palette changes, a color is added, or a light or dark theme is about to be approved.37- Use when the user asks whether a text color is readable on its background.38- Use when an accessibility audit flags contrast and you want the fix at the token level.3940## How It Works4142### Step 1: Run the measurement4344The checker ships as source, not as a committed script: save the JavaScript block in45[references/contraste-checker.md](references/contraste-checker.md) as `contraste.mjs` in a46scratch directory (no dependencies, Node 18+), then run it:4748```bash49node contraste.mjs --tokens src/styles/tokens.css50```5152Without `--tokens` it looks for `src/styles/tokens.css` and other common locations. The script:5354- Reads `--color-*` variables in hex, `rgb()`, `hsl()` or `oklch()`, resolves `var(--other)`, and55 separates the default theme from dark mode (`prefers-color-scheme: dark`, `.dark` or56 `[data-theme=dark]`).57- Pairs tokens by name: text tokens (`text`, `foreground`, `link`, `focus`…) over background tokens58 (`background`, `bg`, `surface`, `card`, `canvas`…). Spanish token names (`texto`, `fondo`,59 `superficie`, `tarjeta`) are recognized too.60- Prints `OK` or `NO` per pair, with the ratio, the minimum and the suggestion.6162If token names do not follow that pattern, write the real pairs to a JSON file and pass it with63`--pares` (the keys are `texto`, `fondo` and `tipo`, where `tipo` is `texto` or `ui`):6465```json66[{"texto": "--color-gray-500", "fondo": "--color-white", "tipo": "texto"},67 {"texto": "--color-input-border", "fondo": "--color-white", "tipo": "ui"}]68```6970To explore a new palette, `--todos` measures every color against every other. `--json out.json`71writes the results for further processing. The script's output is in Spanish; ratios and token72names read the same in any language.7374### Step 2: Check what the script cannot see7576- Text over **images or gradients**: capture the section and check the worst spot.77- Text with **opacity**, or colors hard-coded outside the tokens (search for `#[0-9a-fA-F]{3,8}`,78 `rgb(`, `text-[#`).79- States: `hover`, `disabled` (exempt, but still distinguishable), and placeholders that carry80 information.8182### Step 3: Report and propose8384| Pair | Now | Minimum | Suggestion | Where it is used |85|---|---|---|---|---|8687Search for the classes and `var(--color-...)` references to fill "where it is used".8889## Examples9091### Example 1: A gray that fails on white9293```text94== tema claro (por defecto): 4 colores leídos ==95 NO 3.54:1 (mín. 4.5) --color-text #888888 sobre --color-background #ffffff96 sugerencia para --color-text: oklch(56.2% 0.000 89.9) (#757575) → 4.62:197```9899Propose `#767676` for `--color-text` (the single value that passes on all its backgrounds), apply100it only after the user agrees, and run the script again to show it passes.101102## Best Practices103104- ✅ Fix the token once instead of patching each screen.105- ✅ Offer options: darken the token, keep the color only for large text, or add a new token106 (`--color-accent-text`) for small text and keep the original for fills and borders.107- ❌ Don't change brand colors without asking.108- ❌ Don't report a theme as passing without checking dark mode too.109110## Limitations111112- It measures tokens, not rendered pixels: images, gradients and opacity need a visual check.113- Pairing by name is a heuristic; use `--pares` when names are unconventional.114- This skill does not replace environment-specific validation, testing, or expert review.115116## Security & Safety Notes117118- The script only reads the CSS or JSON file you point it to and writes a file only with `--json`.119 It makes no network requests and installs nothing. Requires Node 18+.120- It never edits tokens by itself; changes are proposed and applied after the user approves.121122## Common Pitfalls123124- **Problem:** A dark-mode pair shows `OK` against the light background.125 **Solution:** Make sure dark-mode variables live in a `prefers-color-scheme: dark`, `.dark` or126 `[data-theme=dark]` block so the script can separate the themes.127128## Related Skills129130- `@wcag-audit-patterns` - For a full WCAG 2.2 audit beyond color contrast.