css-token-sweep

Find every var(--name) in a project where --name is not defined in any :root { ... } block. Surface tokens defined in default :root but quietly inherited (not overridden) by theme variants. Optionally flag hardcoded colors that duplicate an existing token's value.

This is the missing lint pass that most design-system codebases never add. Without it, a typo like var(--ink-2) instead of var(--ink-soft) renders text in the unset color (often invisible against a white button) and ships to production unnoticed.

The skill bundles scripts/sweep.py — a zero-dependency Python scanner. Most of the work is mechanical, so the script does it deterministically; the skill body just orchestrates running it, interpreting the output, and proposing fixes.

============================================================ === PRE-FLIGHT === ============================================================

Before running, verify:

• [ ] A path was either passed in the slash-command args or there's an

obvious project root in the current working directory.

• [ ] python3 is on PATH (python3 --version).
• [ ] The path contains at least one .css, .html, .htm, .jsx,

.tsx, .vue, or .svelte file. If it doesn't, the scan has nothing to do — say so and exit.

Recovery:

• No path given → default to the current working directory.
• No CSS sources found → tell the user and exit; do not invent files.
• Python missing → tell the user to install Python 3.8+ and stop.

============================================================ === PHASE 1: RUN THE SCANNER === ============================================================

Invoke the bundled scanner with the user's path (or .):

python3 ~/.claude/skills/css-token-sweep/scripts/sweep.py <PATH>

Useful flags:

The scanner reports three findings:

1. Errors — undefined `var(--name)` with no fallback. This is the

canonical invisible-text bug. A var(--ink-2) reference where --ink-2 is defined nowhere falls back to the unset initial value; for color that is the unset paint color, which depending on context may render the text the same color as the background.

1. **Warnings — tokens defined in :root but not overridden in a

[data-theme="..."] variant.** Heuristic: only color-like tokens (anything whose name contains ink, surface, paper, bg, border, accent, text, etc.) are surfaced, because shape and shadow tokens often legitimately stay shared across themes. The warning is a prompt to confirm the default value still reads correctly under each variant, not an automatic fix.

1. Warnings — hardcoded hex colors that duplicate a token's value.

These are stylistic; the code works fine, but switching themes won't move them. Suggest replacing with var(--matching-token).

VALIDATION: scanner exits cleanly and prints either "Clean." or a report with concrete file:line locations. FALLBACK: if the scanner errors on a specific file (permissions, weird encoding), note the file in the report and continue with the rest.

============================================================ === PHASE 2: INTERPRET AND FIX === ============================================================

For each error, the report includes a "Did you mean?" suggestion based on edit distance to the closest defined token. Take that suggestion seriously — in nine cases out of ten it is exactly the right fix, because the bug pattern is almost always a typo / wrong tier name (--ink-2 vs --ink-soft, --bg-muted vs --surface-muted, etc.).

Workflow:

1. Read the file the scanner pointed at.
2. Replace the bad var(--…) with the suggested token, or — if the

suggestion is wrong — define the new token in :root (and in each theme variant).

1. Re-run the scanner. The errors block should be empty.

For theme-variant warnings, do not blindly add overrides. Read each warning, look at the component that uses the token, and decide whether the default value actually reads correctly in that variant. Many shadow / radius / motion tokens legitimately stay the same across themes — only color tokens need variant-specific overrides.

For hardcoded-color warnings, replace in place. This usually takes one sed pass per color.

VALIDATION: a second scanner run reports 0 errors. FALLBACK: if you cannot resolve an error (e.g., the token genuinely does not exist anywhere in any related file), surface it to the user explicitly with a recommendation — either define the token or remove the dead reference.

============================================================ === PHASE 3 (OPTIONAL): RUNTIME CONTRAST SWEEP === ============================================================

Static token-existence checks do not catch a token that exists but resolves to an unreadable color under a given theme. If the project has multiple data-theme variants and the user wants belt-and-suspenders coverage, do a runtime sweep with Playwright:

// Pseudocode — adapt to the project's entry point.
for (const theme of ["light", "dark", "morning", "dusk"]) {
  await page.evaluate((t) => {
    document.documentElement.dataset.theme = t;
  }, theme);
  const lowContrast = await page.evaluate(() => {
    const out = [];
    const interactive = document.querySelectorAll(
      'button, a, input, [role="button"]',
    );
    for (const el of interactive) {
      const cs = getComputedStyle(el);
      const ratio = contrastRatio(cs.color, cs.backgroundColor);
      if (ratio < 3.0)
        out.push({ tag: el.tagName, text: el.textContent.slice(0, 40), ratio });
    }
    return out;
  });
  console.log(theme, lowContrast);
}

Only do this if (a) Playwright is already available in the environment and (b) the project actually has multiple themes. Otherwise it is more overhead than the static scan.

VALIDATION: each theme returns 0 low-contrast interactive elements, or the user has reviewed and accepted any remaining hits. FALLBACK: if Playwright is not available, document the gap in the final report and stop. Do not try to install Playwright unprompted — the static check already catches the highest-impact bugs.

============================================================ === SELF-REVIEW === ============================================================

Score the output (1–5):

• Complete: Every undefined-var error has been resolved (or

explicitly noted as needs-human-judgment)?

• Robust: Did you account for runtime-set custom properties via

--ignore? Did you skip false-positive warnings rather than apply noisy fixes?

• Clean: Is the report concise enough that the user can act on it

without reading the underlying CSS line by line?

If any score < 4:

• Re-run with different flags to narrow the noise.
• For genuinely ambiguous cases (the suggested token is wrong), flag

the case to the user with the two or three candidate tokens rather than silently picking one.

============================================================ === LEARNINGS CAPTURE === ============================================================

After each run, append one entry to ~/.claude/skills/css-token-sweep/LEARNINGS.md:

## <YYYY-MM-DD> — <project name + scan scope>

- **What worked:** <specific suggestion that was correct, or a flag
  combo that produced an actionable report>
- **What was awkward:** <false positive that the scanner could have
  avoided, a missed bug, or a slow step>
- **Suggested patch:** <one concrete improvement — "auto-detect
  inline-style runtime vars and skip them", "add `--include` glob
  to scan only one subdirectory", etc.>
- **Verdict:** [Smooth / Minor friction / Major friction]

Anti-patterns this skill refuses

• Inventing a token to "fix" the error. If var(--ink-2) is bad, fix

the reference or genuinely add the token — do not silently leave the reference and pretend the bug went away.

• Adding var(--name, fallback) everywhere as a workaround. Fallbacks

hide real bugs and create theme inconsistency. Use them only for intentionally optional vars (e.g., user-customizable accents) and document the intent.

• Disabling the scanner for a whole file with --ignore instead of

fixing the underlying issue. --ignore is for runtime-set vars, not for silencing bugs.

• Treating every theme-variant warning as a fix-required error. Many

are intentional. Read each one and decide.