---
chain-id: 4
name: Drift audit
path: C · Deep (also runs in CI for A and B)
status: live
prompts: [11]
inputs: output/tokens.css (canonical baseline) + target CSS or codebase files
outputs: drift report (severity-ranked, markdown)
documented-in: Ch23 — Quality Gates · Ch24 — Failure Modes
---

# Chain 4 — Drift Audit

Scans a codebase (or Figma file) for values that have drifted from the canonical `output/tokens.css`. Produces a severity-ranked report of every deviation, with the file, line, observed value, and expected token for each finding.

**When to use:**
- Before any merge that touches component CSS
- After a token spec update (to find components that still reference old values)
- Quarterly full audit against the locked spec
- Any time a "this looks wrong" design review surfaces

**Expected runtime:** 5–15 minutes depending on codebase size.

**Prerequisites:** `output/tokens.css` must exist and be current. Target files (CSS/SCSS/TSX) or Figma file via MCP.

---

## Step table

| Step | Prompt | What lands | Checkpoint |
|---|---|---|---|
| 1 | `11-drift-audit.md` | `output/drift-report-<YYYY-MM-DD>.md` — severity-ranked findings | Triage: fix A (Critical) before merge |
| 2 | Per finding: reapply token reference or re-run Prompt 03/04/05 for the affected component | Corrected files | Re-run audit to confirm zero Category A findings |

---

## Step-by-step walkthrough

### Step 1 — Run the drift audit (Prompt 11)

**What to paste:**
- `output/tokens.css` — the canonical baseline
- Target files: paste the CSS/SCSS/TSX files you want to audit (or connect via MCP for Figma)
- For a full codebase audit: paste `output/foundation.css`, `output/composite.css`, `output/patterns.css`, `output/chrome.css`, `output/domain.css`

**What the prompt scans for:**

| Category | Severity | Examples |
|---|---|---|
| A | Critical | Hardcoded hex colors, raw shadow values, hardcoded z-index |
| B | High | Off-scale spacing (e.g., 15px where grid uses 8/12/16), non-spec font sizes |
| C | Medium | Invented token names not in tokens.css, semantic token misuse |
| D | Low | Vendor prefixes without fallback, !important usage, commented-out token references |

**What to check at the checkpoint:**
- Category A findings: zero tolerance before merge. Every hardcoded hex in a component that should use a token is a Category A finding.
- Category B findings: fix before shipping, but does not block merge if a waiver is documented.
- Category C findings: review in the next sprint. Invented tokens indicate a gap in the spec — either add the token to the spec, or remove the invention and use an existing token.
- Category D findings: clean up in the current sprint.

**Common failures:**
- *Audit finds nothing (empty report):* Check that the target files were actually pasted. If the prompt only received tokens.css, it has nothing to compare against.
- *Too many Category B findings:* The component generation prompts (03–05) may have introduced off-grid values. Re-run the affected prompt with explicit spacing constraints: "All spacing values must be from the --space-* token set. No other values."

---

### Step 2 — Fix and re-audit

For each Category A and B finding:

**Option 1 — Manual fix:**
Open the affected file, locate the line, replace the raw value with the correct `var(--token)` reference. Fast for isolated findings.

**Option 2 — Targeted re-generation:**
If multiple findings are in one component, re-run its generating prompt (03, 04, 05, or 07) with the drift report appended: "Re-generate [component name]. The following drift findings must be resolved: [paste findings]." The prompt regenerates only the named component, not the full file.

**After fixing:** Re-run Prompt 11 against the corrected files. The new report should show zero Category A findings and a reduced Category B count.

---

## Cadence

| Trigger | Scope | Blocking? |
|---|---|---|
| Pre-merge (CI) | Files changed in the PR | Yes — Category A blocks merge |
| Token spec update | Full component CSS | Yes — must resolve before next sprint |
| Quarterly audit | Full codebase | No — findings go to backlog |
| Design review flag | Specific components | No — triage and schedule |

## CI integration

Add the drift audit as a CI check using Claude Code:

```bash
# .github/workflows/drift-audit.yml
- name: Drift audit
  run: claude --prompt prompts/11-drift-audit.md \
              --files output/tokens.css,src/components/**/*.css \
              --output output/drift-report-$(date +%Y-%m-%d).md
```

Category A findings in CI output → fail the build. Pipe the report to PR comments for reviewer visibility.

---

*Chain 4 · Drift Audit · Design Systems That Build Themselves · © 2026 Ishdeep S Sahni*