/drift-detection

name: drift-detection
description: "Finds where consuming code has drifted from what the design system intended: local re-implementations, token overrides, forked patterns, classified by cause. Use it whenever someone asks where a codebase, product or team has drifted or gone off-system. One component vs spec: design-to-code-check."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(diff:*), Bash(find:*), Bash(head:*), Bash(ls:*), Bash(sort:*), Bash(tail:*), Bash(wc:*), Bash(npm view:*)
references:
  - ../../knowledge-notes/token-architecture.md
  - ../../knowledge-notes/design-to-code-contract.md
  - ../../knowledge-notes/output-discipline.md

Drift detection

A skill for identifying and classifying drift in a design system — the accumulated distance between design system intent and actual implementation across consuming products. Produces a drift report with severity ratings, origin classification, and recommended response for each finding.

Before you begin: verify references

Confirm that every path in this skill's frontmatter `references:` exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example `npx skills install`) dropped the repo-root `knowledge-notes/` directory. Tell the user to reinstall by a method in `1-INSTALL.md` and run `verify-install.sh` from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

Context

Drift is the normal condition of a used design system. The question is not whether your system has drifted — it has — but whether the drift is intentional, how severe it is, and whether it is compounding.

Not all drift is bad. A product team that made a deliberate, documented exception to an established pattern is making a design decision. A product team that unknowingly re-implemented a design system component with slightly different spacing is creating maintenance debt. The distinction matters, because the response is different: intentional drift might become a contribution, while accidental drift needs to be corrected and its root cause addressed.

This skill distinguishes between drift types and routes each finding to the appropriate response.

---

Configuration

If `.ds-ops-config.yml` exists, follow the configuration-and-recurring knowledge note (`../../knowledge-notes/configuration-and-recurring.md`) for loading, integration fallbacks and recurring runs. This skill reads:

• `severity.*` — drift finding severity overrides
• `system.styling` — pre-selects the token drift detection approach (CSS vars, SCSS, Tailwind, CSS-in-JS)
• `integrations.*` — drift comparison data (see below)
• `recurring.*` — drift trend (see Recurring workflow)

Auto-pull integrations

**Figma MCP** (`integrations.figma.enabled: true`):

• Read component specifications from the published library at `integrations.figma.file_key`
• Use as the design-side reference for visual and API drift detection
• Compare Figma component properties against code component props to detect API drift without manual specification

**GitHub** (`integrations.github.enabled: true`):

• Search `integrations.github.repo` for code patterns that indicate drift (see the note's GitHub caution):
• Hardcoded colour values outside the design system package
• Local component re-implementations (component names used outside the system's source)
• Token overrides using CSS `!important` on design token properties
• Pull recent PRs to identify components changed outside the design system package
• Detect version lag by comparing the design system version each consumer declares in `package.json` and resolves in its lockfile against the latest published version (`npm view [package] version`). Commit history doesn't tell you which version a consumer runs

**Chromatic** (`integrations.chromatic.enabled: true`):

• Pull visual diff data — components with accepted visual changes outside a DS release cycle are potential visual drift
• High rates of accepted changes may indicate the team is accepting drift rather than correcting it

Recurring workflow

Follows the recurring-run procedure in the configuration-and-recurring note. Specific to this skill:

• **Persistent drift** (present for 2+ cycles): escalate severity.
• **Classification shift:** flag drift whose classification changed, e.g. accidental drift that became intentional divergence.
• **Add a "Drift trend" section** to the report:
• Total drift count: increasing / stable / decreasing
• Drift velocity: how fast is new drift accumulating vs. being resolved?
• Classification trend: is the mix shifting toward more system gaps (E) or more accidental drift (C)?

Step 1: Define the scope

Ask for or confirm (skip questions already answered by auto-pull):

• What is being assessed? (Specific product, specific component set, specific token scope, or full system)
• What sources are available for comparison? (Figma files, codebase, documentation, Storybook, token files in any format — JSON, CSS custom properties, SCSS variables, Tailwind config)
• Are there specific areas where drift is already suspected?
• Is there any known intentional divergence that should be documented rather than flagged as a problem?

The more specific the scope, the more actionable the report. A drift detection across "the whole system" surfaces patterns but produces a long list of findings with limited prioritisation signal. Scoping to a specific product or a specific component category produces a more actionable output.

**Drift needs a consumer.** If the only code in reach is the design system's own repository, there is nothing to have drifted from it. Stop and say so, then point to the skills that do apply: `token-compliance` for raw values in the system's own components, `component-audit` for duplication and gaps inside the library, `design-to-code-check` for one