Design Token Guard

design-token-guard

The problem this solves

A hardcoded color renders identically to the token it should have used. style={{ background: "#07090c" }} and style={{ background: "var(--tl-tooltip)" }} produce the same pixels. So every render-level gate — visual review, e2e, screenshots, "console is clean" — passes a component that has silently bypassed the design system. The violation only exists in source.

That is why inline styles and hardcoded CSS accumulate invisibly until someone eyeballs the code weeks later and burns hours on a token refactor. The fix is a source-level gate: a deterministic check that reads the diff for styling that bypasses the token system, run before the code is declared done, and wired into the repo so it can't regress.

This skill is that gate. It does two things:

1. Audit — run the bundled checker (scripts/check_design_tokens.py) to find every inline style and hardcoded color, each mapped to the exact token to use.
2. Enforce — scaffold the check into the repo (config + ESLint rule + pre-commit hook + lint:tokens script) so the gate runs on every commit/CI, not just when an agent remembers to look.

It is dynamic: it auto-discovers whatever token system the project already uses and derives the rules from it. TruthLens and a vanilla Vue app are two configs of one skill, not two skills.

Step 1 — Audit

Run the checker from the project root. It needs no flags for a first pass:

python3 <skill-dir>/scripts/check_design_tokens.py --root .

What it does automatically:

• Discovers the token source — scans for CSS custom properties (--name: …), SCSS/Less vars ($name, @name), JS/TS theme objects, or design-token JSON. From those it builds a color-value → token map.

• Scans the source tree (.tsx/.ts/.jsx/.js/.vue/.svelte/.astro/.html), skipping node_modules, build dirs, config files, and the token files themselves.

• Reports each finding as file:line:col, the offending snippet, and — when the literal matches a declared token — the exact fix:

  no-hardcoded-color (error) — 2
    src/components/schedule/EventBar.tsx:69:17
      fill="#0E1116"
      → hardcoded color #0E1116 is var(--tl-bg-0)  ·  use var(--tl-bg-0)
  

Useful flags:

• --staged — only git-staged files (this is what the pre-commit hook uses).
• --json — machine-readable output for a gate/CI to parse ({ ok, summary, findings }).
• PATHS… — limit to specific files/dirs (e.g. just the component you changed).
• --config <path> — explicit config location.

Exit code is 1 when there are error-severity findings, 0 when clean — so it drops straight into a gate or CI step.

Step 2 — Interpret and fix

Two outcomes per color finding, and they need different fixes — don't blur them:

• "… is var(--token)" — the literal duplicates an existing token. Replace it with the token reference. Mechanical and safe.
• "… is not a declared token" — the color was never tokenized. This is the more important signal: either it's a genuinely new design value (add it to the token source with a real name, then reference it) or it's an off-palette mistake (use the nearest existing token). Don't paper over it by leaving the literal — that's how palettes rot.

For no-inline-style findings, move the value into a token or a utility class. Inline styles whose values are all dynamic (var(--…), JS expressions) are allowed by default — the rule fires on hardcoded literals, not on the mechanism. Use "inlineStyleMode": "strict" only if the project bans inline style attributes outright.

Step 3 — Enforce (scaffold into the repo)

A one-time audit doesn't stop regression. Wire the gate into the repo so it runs without anyone remembering. Read references/scaffolding.md for the full procedure; the short version:

1. Write .design-guard.json at the repo root (template: assets/design-guard.config.json). Set tokenSources explicitly so discovery is deterministic in CI, and turn on any project-specific rules.
2. Add the checker to the repo — copy scripts/check_design_tokens.py into the project's scripts/, or reference the skill path. Add a script: "lint:tokens": "python3 scripts/check_design_tokens.py --root .".
3. Pre-commit hook — install assets/pre-commit (runs --staged, blocks the commit on error-severity findings). Wire via Husky/lefthook if present, else a plain .git/hooks/pre-commit.
4. ESLint editor-time subset — merge assets/eslint-tokens.snippet.mjs into the repo's flat config (create eslint.config.mjs if absent). ESLint gives in-editor squiggles for the patterns it expresses well (inline-style literals, forbidden radius/partisan-color classes). The Python checker stays the authority — it's the only layer that can do the value → token mapping, so pre-commit/CI run that, and ESLint is fast feedback, not the source of truth.
5. CI — add a lint:tokens step to the pipeline (assets/ci-step.yml shows a GitHub Actions example).

Tell the user which layers you installed and which you skipped (e.g. "no Husky here, used a raw git hook").

The rule set

Two universal rules, on by default (these are the "no inline CSS" core):

A project-specific library, off by default — opt in via config when a repo has these conventions:

Each rule's severity is "error" | "warn" | "off". Errors fail the gate (exit 1); warnings report but pass. Full config reference and per-rule notes: references/config.md.

Using it as an agent / orchestrator gate

When a frontend build runs under an orchestrator or agent team, this is a hard source-level wave-gate, complementary to the render-level gates (render-sanity, ux-review) — those check pixels, this checks source, and a build needs both:

• A frontend-agent runs --json against the files it changed before reporting done; error-severity findings mean the task isn't done.
• The orchestrator runs it at the wave gate alongside typecheck/test. Parse summary.errors; non-zero blocks the wave and routes back to the owning agent.

See references/wiring-into-orchestrator.md for the exact gate snippet and how this plugs into the orchestrator's Definition of Done.

Reference files

• references/config.md — full .design-guard.json schema, every field, per-rule notes, and adapting to non-CSS-variable token systems (SCSS, JS theme, Style Dictionary).
• references/scaffolding.md — step-by-step repo enforcement: config, hook, ESLint, CI, with the Husky/lefthook/raw-hook decision.
• references/wiring-into-orchestrator.md — the agent self-check + orchestrator wave-gate snippets, and the Definition-of-Done line this closes.