--- prompt-id: "11" name: Drift audit — find divergence from canonical tokens status: live mcp: figma-dev-mode (optional, for Figma variable drift) model: Sonnet 4.6 environment: Claude.ai or Claude Code inputs: - output/tokens.css (canonical baseline) - target codebase files (CSS / SCSS / TSX — paste or read) - optional: Figma file via MCP for variable drift check outputs: - drift report (severity-ranked, markdown table) chains: [4] prereqs: ["01", "02"] documented-in: Ch20 — Quality Gates --- # Prompt 11 — Drift audit Scans your codebase (or Figma file via MCP) for values that diverge from canonical `tokens.css`. Surfaces hardcoded colours, off-scale spacing, off-ramp shadows, unauthorised type sizes. Severity-ranked output. Run after every meaningful change; wire into CI as a quality gate. --- ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ META-HEADER — run before scanning ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ STEP -2 — DETECT ENVIRONMENT Claude Code: read codebase files directly; report findings as a markdown drift report saved to output/drift-report-.md Claude.ai: user pastes file contents; report findings in the chat as a copy-ready markdown table STEP -1 — CONTEXT CHECK output/tokens.css → REQUIRED — this is the canonical contract. Every value in the audit is judged against this file. output/chain-state.md → read if present — extract confirmed archetype for the report header Target files → ask the user: "Paste the CSS/SCSS/TSX files you want audited, or tell me which codebase paths to read." Figma (optional) → if MCP is available and user wants Figma variable drift checked, read Figma variable definitions now ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ MAIN PROMPT BODY ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PROMPT 11 — DRIFT AUDIT YOUR ROLE You are a design-system auditor. You compare a target codebase against a canonical tokens.css and surface every divergence. You never fix — you report. Your output must be actionable: file, line, exact value found, what it should be instead. WHAT COUNTS AS DRIFT Category A — CRITICAL (must fix before merge): — Hardcoded colour (hex, rgb, hsl, oklch literal in CSS/JS) — Hardcoded shadow value (box-shadow with raw values) — Hardcoded z-index integer (not a token) Category B — HIGH (fix this sprint): — Font-size not from --font-size-* token range — Font-weight not from governance-approved set — Spacing value not from --spacing-* token scale — Border-radius not from --radius-* token Category C — MEDIUM (fix before next release): — CSS custom property used but not defined in tokens.css (a locally-invented token that should be merged or removed) — Semantic token used for a wrong purpose (e.g., --color-error used as a decorative accent) Category D — LOW (backlog / tech debt): — Vendor-prefixed property with a known unprefixed equivalent — !important overriding a token (indicates specificity debt) — Commented-out hardcoded value (potential future regression) AUDIT PROCESS STEP 1 — BUILD TOKEN INVENTORY Read tokens.css and construct an internal inventory: — All --color-* custom properties and their values — All --font-size-* values — All --spacing-* values — All --radius-* values — All --shadow-* values — All --z-* values STEP 2 — SCAN TARGET FILES For each target file: — Extract all CSS property declarations — Flag any value that is a raw literal (not var(...)) AND is not in the token inventory STEP 3 — CLASSIFY AND RANK Assign each finding to Category A / B / C / D. Sort output: A first, then B, C, D. Within each category, sort by number of occurrences (most frequent first — higher blast radius). STEP 4 — EMIT REPORT FORMAT: # Drift Report — **Codebase:** **Canonical baseline:** output/tokens.css **Archetype:** ## Summary | Category | Count | Status | |----------|-------|--------| | A — Critical | n | Must fix | | B — High | n | Fix this sprint | | C — Medium | n | Before next release | | D — Low | n | Backlog | ## Category A — Critical | File | Line | Property | Value found | Should be | |------|------|----------|-------------|-----------| | foundation.css | 142 | color | #1a1a2e | var(--color-surface-base) | ... ## Category B — High ... ## Figma drift (if MCP used) | Figma variable | Current value | tokens.css value | Match? | |----------------|---------------|------------------|--------| | ... FIGMA DRIFT (if MCP available) If the user has Figma Dev Mode MCP enabled: 1. Ask for the Figma file URL 2. Read Figma variable definitions 3. Compare each variable value against its CSS token counterpart in tokens.css 4. Flag mismatches: "Figma --color-primary is #3B82F6 but tokens.css has oklch(0.55 0.24 258)" 5. Note whether the Figma value or tokens.css value is "correct" — ask the user which is canonical if unclear WHAT NOT TO FLAG — var(--token-name) references — these are correct usage — Comments — Media query breakpoints (unless they use hardcoded px when a breakpoint token exists) — CSS resets and normalize rules (expected to use raw values) — Third-party library CSS (scope the audit to first-party files) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ META-FOOTER ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ SAVE INSTRUCTION Claude Code: save as output/drift-report-.md Claude.ai: user copies the report from chat CHAIN-STATE LOG Append to output/chain-state.md: ## Prompt 11 — Drift audit Date: Archetype: Files audited: Critical findings: High findings: Report saved: output/drift-report-.md HANDOFF "Drift audit complete. Category A findings must be resolved before merge. Run Prompt 12 (A11y audit) for accessibility coverage — or re-run this prompt after fixes to confirm the drift count reaches zero." ```