audit-design-token-drift

When to use

Run this skill when:

• A change to any color, spacing, typography, or shadow token is about to ship
• tokens.json $metadata.cssSyncRequired has any entries
• A new sphere brand color is introduced
• Weekly, on a schedule (cron / make audit-tokens), as drift-prevention infrastructure
• Before publishing a design-system blog post or case study — you cannot claim “0 drift in production” without re-running this

Do NOT use for: component-level visual review (use audit-component-consistency), CSS minification verification (covered by make check-css-sync), WCAG contrast audits (use a dedicated a11y skill).

The four canonical surfaces

Surface	Path	Role
DESIGN.md	/DESIGN.md	Human-readable spec; the rules layer
tokens.json	/lib/styles/tokens.json	W3C format; the bridge
main.css	/lib/styles/main.css	Running production code
design-system.html	/design-system.html	Live demo page

If a fifth canonical surface is added (e.g. tokens.figma.json exported from Tokens Studio), update this skill before adding it to the audit.

Extract token values from each surface

• DESIGN.md: grep for hex codes (#[0-9A-Fa-f]{3,6}) in table rows and prose. Tag each finding with its section number so cross-section drift inside the same document is caught.
• tokens.json: parse JSON. For each $value, resolve {primitive.x.y.z} references to a final hex. Build a flat name → final hex map.
• main.css: extract the :root { ... } block. Capture every --token-name: value; declaration. Ignore @media-scoped overrides — those are intentional surface variations, not drift.
• design-system.html: extract the :root { ... } block from its inline <style>. Same shape as main.css extraction.

The four diffs (leverage-ordered)

1. DESIGN.md ↔ DESIGN.md (intra-document): does Section 2 agree with Section 9 and any prose mentions? Drift here is the worst — the rules layer cannot disagree with itself.
2. DESIGN.md ↔ tokens.json: every named token in DESIGN.md must exist in tokens.json with the same value. Sphere brand colors are the most common drift here.
3. tokens.json ↔ main.css: every primitive→semantic chain in tokens.json must resolve to the same hex declared in main.css. metadata.cssSyncRequired should be empty after this passes.
4. main.css ↔ design-system.html: the live demo page must declare a superset of main.css tokens. Missing tokens here mean components rendered on design-system.html may silently fall back to defaults.

Step 3.5 — final-value verification

The four diffs check token existence but not value drift hidden inside primitive→semantic indirection. For every token DESIGN.md ascribes a hex value to:

1. Look up the same name in tokens.json
2. Resolve its {primitive.x.y.z} reference chain to a final hex
3. Assert that final hex equals the value DESIGN.md states

Any mismatch is High-severity drift. Example (caught by audit-skill-bench as HIGH-1): DESIGN.md:79 says Auxosphere is #909090; tokens.json:192 says auxosphere → {primitive.color.gray.500} which resolves to #6c757d. Diff 2 passes; the value silently drifts. This step was added 2026-05-06 in response to the bench finding.

Output template

# Design Token Audit — YYYY-MM

## Summary
- Total drift findings: N
- Critical / High / Medium / Low: N each

## Findings
For each finding:
- Severity
- Location: file:line ↔ file:line
- Token name
- Values observed (with surface labels)
- Recommended fix (align value | add missing token | remove orphan)
- Loop step (per design-system-loop.html:
  1 Observe, 2 Design, 3 Tokenize, 4 Build, 5 Ship, 6 Document)

## Statistics
- Token counts per surface
- Coverage percentages

## Auditor / Date

Commit, link, verify

• Commit the audit file under _agents/
• Link it from any PR that touches tokens or main.css
• If any Critical findings exist: the change must not ship until they're resolved or explicitly accepted in writing

Verification checklist before considering the skill run complete:

• Audit file exists at _agents/DESIGN_TOKEN_AUDIT_YYYY-MM.md
• Every finding has both a file:line citation and a one-line fix
• tokens.json $metadata.cssSyncRequired reflects current state
• If Critical findings: commit/PR/issue referenced in the audit
• Previous month's audit compared — net drift count should trend down or be explained