/drift-detection

name: drift-detection
description: "Identify where a design system has diverged from its original intent across the whole system — components implemented differently to spec, tokens overridden locally, patterns forked across teams. This is a system-wide sweep for divergence patterns, NOT a single-component spec comparison. Trigger when someone says: find drift, where has the system diverged, design code inconsistency, what's out of sync, where are teams going off-system, component drift, or anything about identifying gaps between design system intent and actual implementation. Do NOT trigger for checking one specific component against its design spec — use design-to-code-check for that."
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.

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

Before producing output, check for a `.ds-ops-config.yml` file in the project root. If present, load:

• `severity.*` — overrides for drift finding severity ratings
• `system.styling` — pre-selects token drift detection approach (CSS vars, SCSS, Tailwind, CSS-in-JS)
• `integrations.*` — enables auto-pull for drift comparison data (see below)
• `recurring.*` — enables comparison with previous drift report

Auto-pull integrations

If integrations are configured in `.ds-ops-config.yml`, pull data automatically:

**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:
• 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
• Use commit history on component files to detect version lag

**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

If an integration fails, log it and proceed with manual input.

Recurring workflow

If `recurring` is configured in `.ds-ops-config.yml`:

1. **Load the previous drift report** from `recurring.output_directory`. 2. **Compare against current findings:**

• New drift instances since last run
• Resolved drift instances (corrected since last run)
• Persistent drift (present for 2+ cycles — escalate severity)
• Classification shift (e.g. accidental drift that became intentional divergence)

3. **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)?

4. **Save output** and prune per `recurring.retain_count`.

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.

**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). 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
• Th