Design md drift check

DESIGN.md Drift Check

Overview

Keep DESIGN.md from lying to coding agents. This skill compares the repo's agent-facing design file against the actual frontend source of truth and either reports drift or patches DESIGN.md with source-backed corrections.

When to use

• Trigger when the user asks to audit, update, verify, refresh, repair, or maintain DESIGN.md.
• Trigger when UI work went stale after changes to Tailwind, CSS variables, theme files, component libraries, screenshots, or product copy.
• Do not trigger when the repo has no DESIGN.md and the user wants a new brand system invented from scratch.
• Do not trigger for broad UX critique, visual redesigns, Figma work, or general frontend code review unless the requested output is specifically DESIGN.md drift.

Workflow

1) Establish Scope

• Find the repo root and confirm whether DESIGN.md exists.
• If it does not exist, stop with a short note that this skill maintains an existing file. Offer the minimum evidence inventory that would support a separate creation task.
• Identify the requested mode:
  • report: list drift only.
  • patch: edit DESIGN.md after confirming source evidence.
  • verify: check whether no drift exists.
• If the user did not specify a mode, default to report for broad requests and patch only when they explicitly asked to update or repair the file.

2) Gather Source Evidence

Read the current DESIGN.md first, then inspect only source files that can prove or disprove its claims. Prefer fast, local evidence:

• Token files: tailwind.config.*, theme.*, tokens.*, design-tokens.*, variables.css, globals.css, app.css, index.css, *.module.css.
• Component systems: components/, ui/, src/components/, app/components/, packages/ui/, Storybook stories, component docs, design-system packages.
• Layout and page patterns: representative routes under app/, pages/, src/app/, src/pages/, or router files.
• Brand assets: logo files, icon sets, font imports, image assets, metadata, favicons, and manifest files.
• Interaction states: button variants, form states, menus, modals, empty states, loading states, error states, and responsive breakpoints.

Use rg or equivalent search first. Keep evidence bounded: sample enough files to support each claim, and do not turn this into a full frontend audit.

3) Compare Claims to Reality

Classify each checked DESIGN.md claim:

• matched: source evidence confirms it.
• missing: the file omits a source-backed rule that coding agents need.
• stale: the file says something the code no longer does.
• unsupported: the file invents design guidance not found in source evidence.
• ambiguous: the source is inconsistent or insufficient.

Prioritize drift that would cause generated UI to look wrong: colors, typography, spacing scale, radius, shadows, density, layout constraints, component variants, accessibility states, responsive behavior, copy tone, and forbidden patterns.

4) Patch Only Source-Backed Sections

When in patch mode:

• Edit DESIGN.md directly and keep the file's existing structure when it is usable.
• Replace stale claims with evidence-backed rules.
• Add compact missing guidance only where it changes agent behavior.
• Remove invented guidance that conflicts with source evidence.
• Mark unresolved inconsistencies as short notes, not confident rules.
• Avoid broad rewrites, rebranding, marketing language, or speculative visual direction.

5) Report

Return a concise drift summary:

• Status: clean, patched, drift found, or blocked.
• Evidence checked: the key files or folders inspected.
• Drift: grouped by severity, with file references.
• Changes made: only when patch mode edited DESIGN.md.
• Residual risk: source areas not inspected or ambiguous evidence.