Drift Detection

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 component against its spec. Ask for a consuming product (a path, a repo, or a Figma file of a product) before continuing.

Small-system note (fewer than 5 components): For systems this size, scope to the full system — there is no need to sample. Drift patterns are different in small systems: teams are typically smaller and more aligned, so drift is less likely to be accidental and more likely to be intentional divergence (Classification A) or a system gap (Classification E) — though each still needs the evidence Step 4 asks for. Simplify the output to a per-component checklist rather than a full drift report. If all components show no drift, state that as the finding and recommend a review cadence.

Step 2: Establish the reference point

Drift is always relative to something. Confirm the source of truth being used as the reference:

• The design system's Figma library
• The published component package at a specific version
• The documented specification for each component
• All of the above (inconsistencies between these are themselves a drift signal)

If there is no clear single source of truth, that is a finding in itself and should be included at the top of the report.

Step 3: Identify drift instances

Assess across four dimensions:

Visual drift

Differences in the visual treatment of a component or pattern compared to the design system reference. Includes spacing, colour (particularly non-token values), typography, border radius, shadow, and icon usage.

For each instance: name the component or pattern, describe the visual difference, and note whether it appears to be intentional or accidental.

Behavioural drift

Differences in interactive behaviour — state transitions, animation, timing, keyboard behaviour, focus management — compared to the designed and documented component behaviour.

Behavioural drift is often the hardest to detect without direct testing, but it carries the highest risk because it includes accessibility regressions.

API drift

Components implemented with different props, different prop names, or different prop semantics than the design system's published API. This is most common when teams implement a component locally rather than consuming it from the system, or when a local version was built before the system component existed and was never migrated.

Token drift

Raw values used where design tokens should be referenced, local token overrides that conflict with semantic intent, and token names used inconsistently across implementations.

The per-file search for raw values is token-compliance's job, with its styling-approach rules and positive control. Don't re-implement it here. If a token-compliance report exists for the product, import its violation table as the token dimension. If not, run token-compliance on the consuming product first, then continue. What this skill adds is the consumer-versus-system reading of each violation: a raw value that equals a system token's resolved value is usually class C or D (someone typed the number instead of the name); a raw value that matches nothing in the system is class A or E and needs the evidence rule in Step 4. Local overrides of system tokens (--color-action-primary: #... redefined in the product, !important on token-driven properties) aren't in token-compliance's remit, so search for those here with a positive control.

Step 4: Classify each drift instance

Classify every finding before assigning a response. Classes A, C and D are claims about the team's intent, which the code alone rarely shows. Assign a class only when its evidence rule is met; otherwise mark the finding Unclassified — needs team input and list what would settle it.

Classification A: Intentional divergence The product team made a deliberate decision to diverge from the system, for a known reason. This may be appropriate (the system does not serve this context) or a contribution candidate (the need is real and should be in the system). Evidence required: a code comment, ADR, PR description, or statement from the team recording the decision.

Classification B: Version lag The implementation matches an older version of the design system. The system has moved on; the product has not. This is not a mistake — it is normal entropy — but it accumulates into a migration burden if left unaddressed. Evidence required: the consumer's installed version (lockfile) is behind the latest published version, and the drifted behaviour matches the installed version.

Classification C: Accidental drift The implementation diverged from the system without intent. Most commonly caused by implementing a component locally when the system version was not yet available, then not migrating once it was. Evidence required: something that shows the divergence wasn't chosen, e.g. the local version predates the system one (git history) and nothing records a decision, or the team confirms it.

Classification D: Misunderstanding The implementation reflects a misreading of the documentation or specification. The consumer thought they were using the system correctly and did not know they were not. Evidence required: the usage matches a plausible reading of the docs (quote the ambiguous passage), or the team confirms it.

Classification E: System gap The drift exists because the system did not have what the product team needed. The divergent implementation is the product team's solution to a design system gap, not a mistake. Evidence required: no system component or token covers the need at the version the consumer runs.

Unclassified — needs team input The evidence doesn't support any class above. Report the finding with its severity and the question that would classify it ("Was the 12px padding on CheckoutCard a deliberate choice?"). Don't guess.

Step 4a: Drift impact severity weighting

Start from a base severity, then weight it:

• 🔴 Critical — an accessibility or behavioural regression on a critical path (focus lost in checkout, missing error announcement on sign-in)
• 🟠 High — an accessibility or behavioural regression elsewhere, or token drift that breaks theming (a hardcoded colour in a themed product)
• 🟡 Medium — visual or API divergence users or developers would notice, with no functional impact
• ⚪ Low — cosmetic divergence in a single instance, or drift in a non-user-facing utility

Then weight by component criticality:

Critical path components (core navigation, authentication, checkout, primary data entry) — drift here is automatically elevated one severity level. A Medium finding on a checkout component becomes High.

High-traffic components (buttons, form inputs, cards, modals) — drift here affects the most users. Weight stays as assessed but flag the blast radius.

Utility components (layout wrappers, spacing helpers, icon containers) — drift here is lower risk. A Medium finding may be downgraded to Low if the component is not user-facing.

Recommendation paths by classification

After classifying each drift instance, route it to the appropriate response: