/design-to-code-check

name: design-to-code-check
description: "Check alignment between a specific design specification and its code implementation — a focused, single-component or single-screen comparison. Trigger when someone says: does this match the design, check implementation, design code alignment, what's different between the design and the build, spec check, implementation review, or anything about comparing a designed component or screen to its coded equivalent. Do NOT trigger for system-wide drift detection across multiple components or teams — use drift-detection for that."
references:
  - ../../knowledge-notes/design-to-code-contract.md
  - ../../knowledge-notes/output-discipline.md

Design-to-code check

A skill for reviewing the alignment between a design specification and its code implementation, producing a structured discrepancy report catalogued by dimension and severity.

Context

Design-to-code alignment reviews catch two different categories of problem. The first is implementation error — the developer built something different from what was specified, either by mistake or because the specification was unclear. The second is specification ambiguity — the design did not define behaviour completely enough for the developer to implement it correctly, and the developer made a reasonable guess that turned out to be wrong.

Both categories matter, but they require different responses. An implementation error needs to be corrected in the code. A specification ambiguity needs to be corrected in the design and documented, so the same guess does not get made again.

This skill produces a report that distinguishes between the two.

---

Configuration

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

• `severity.*` — overrides for discrepancy severity, especially `specification_gap` and `missing_interaction_state`
• `system.framework` and `system.styling` — pre-selects framework-specific checking guidance
• `integrations.figma` — if enabled, auto-pull the design specification (see below)
• `integrations.chromatic` — if enabled, use visual regression data as a supplementary signal
• `gates.design_to_code` — if running as part of `component-to-release`, determines which findings block release

Auto-pull integrations

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

• Pull the component specification directly from `integrations.figma.file_key` via Figma MCP
• Read component properties, variant definitions, and layer structure as the design reference
• This replaces the need for the user to provide a Figma file link — the skill can say "I pulled the Button specification from your Figma library" and proceed immediately

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

• Pull the latest visual snapshots for the component being checked
• Use visual diffs between the Chromatic baseline and the current implementation as a supplementary signal for Dimensions 1–3 (spacing, colour, typography)
• Chromatic data does not replace the manual dimension review but can surface differences the manual review should confirm

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

• If the component implementation is in the configured repo, pull the component source files directly
• Identify the component's last update date and recent changes to contextualise findings

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

Step 1: Gather the comparison materials

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

• The design reference: Figma file link, exported specs, or described specification (skip if pulled from Figma MCP)
• The implementation reference: component in code (React, Vue, Twig, etc.), a link to a running implementation, or a description of what was built. Note the styling approach — CSS custom properties, SCSS variables, Tailwind utility classes, or CSS-in-JS — as this affects how token references are identified during the check.
• The component or screen being reviewed
• Whether this is a first-pass review or a follow-up check after a previous round of corrections
• Any known areas of concern the review should pay particular attention to

If both design and implementation are available directly, proceed to the check. If only one is available, note in the report which side of the comparison is inferred rather than directly inspected.

Step 1b: Design specification checklist

Before running the check, verify the design specification is complete enough to check against. Incomplete specs are the root cause of Type II (specification gap) findings — catching them upfront reduces noise in the report.

**Design specification completeness checklist:**

• [ ] All interactive states are defined (default, hover, active, focus, disabled, error, loading)
• [ ] Spacing values are specified using token names, not pixel values
• [ ] Colour values are specified using token names, not hex values
• [ ] Typography is specified using type scale tokens
• [ ] Responsive behaviour is defined for at least two breakpoints
• [ ] Focus indicator style is specified
• [ ] Content overflow behaviour is defined (truncation, wrapping, scrolling)
• [ ] Touch target sizes are specified for mobile breakpoints

**If the specification fails this checklist:** Note the missing items and proceed with the check. Missing specification items will appear as Type II findings in the report — but flagging them upfront sets the right expectation: these are design gaps, not implementation errors.

Share this checklist with designers as a pre-handoff tool. A specification that passes this checklist before handoff will produce a cleaner design-to-code check.

Step 2: Run the check across all dimensions

Review alignment across five dimensions. For each dimension, the goal is not to produce a list of every difference — minor sub-pixel differences in a rounding pass are not discrepancies worth reporting. The goal is to identify differences that affect