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.

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