Four-artifact design-to-code pipeline

A reliable design-to-code pipeline does not depend on a particular model brand. It passes four versioned artifacts through explicit gates: visual direction, interaction prototype, design-system contract, and production implementation. Each artifact carries its acceptance criteria forward; Claude Code, Cursor, or Codex use only the image, browser, and design integrations actually configured for the task.

Inputs and outputs

Stage	Reads	Produces	Human gate
1. Visual direction	intent.md, references, brand constraints	Annotated directions or mockups	Product/design chooses a direction
2. Interaction prototype	Accepted direction, state matrix	Inspectable prototype with key flows	Product/design accepts behavior
3. Design contract	Prototype, design-system source	Tokens, components, states, accessibility criteria	Design-system owner accepts
4. Implementation	spec.md, plan.md, design contract	Code, tests, screenshots, review evidence	Code owner and release owner decide

Keep one canonical artifact per decision. Link external design files by stable version and export enough evidence for reviewers who cannot access the tool.

Run the pipeline

1. Create visual directions from intent.

   Ask for alternatives that differ in hierarchy, density, navigation, or interaction—not three color variations.

   Read intent.md, brand constraints, and reference assets.
   Propose three materially different visual directions.
   For each, show the primary screen, explain hierarchy and tradeoffs,
   and list assumptions. Do not write production code.

   Record the accepted direction and rejected alternatives with reasons.

2. Make behavior inspectable.

   Build a prototype in the approved design tool, a local HTML sandbox, or the application with fixture data. Cover the happy path plus empty, loading, error, denied, validation, and destructive states.

   Turn the accepted direction into an inspectable prototype.
   Cover mobile and desktop breakpoints, keyboard navigation,
   focus order, reduced motion, validation, and error recovery.
   Return a state matrix and exact acceptance checklist.

3. Extract the design contract.

   Record tokens, typography, spacing, components, variants, content rules, responsive behavior, accessibility, and asset provenance. Reuse the existing design-system source instead of inventing parallel tokens.

   artifact: design-contract
   version: 1
   source: stable design link or committed prototype
   tokens_source: existing design system path
   components:
     - name: CheckoutSummary
       states: [loading, ready, empty, error]
       keyboard: documented
   breakpoints: [mobile, desktop]
   acceptance_owner: named person or role

4. Plan and implement in the repository.

   Feed the accepted contract to spec.md and plan.md. Work in an isolated branch, preserve existing component conventions, and keep visual acceptance separate from code generation.

5. Collect proof in the real application.

   Run unit, integration, and E2E gates plus keyboard and accessibility checks. Capture the exact route, seed state, viewport, screenshot or video, command, and exit code.

6. Review independently.

   A fresh review pass compares the real implementation with the accepted design contract and reports evidence-backed mismatches. Product/design accepts visual behavior; code and release owners retain their normal gates.

Design tools inherit the data boundary

Mockups can contain unreleased strategy, customer data, or licensed assets. Confirm provider, retention, connector scope, and sharing policy before upload.

Failure modes

A vendor-specific feature disappears. The artifacts still work. Replace the tool adapter, rerun the affected stage, and preserve the contract.

The prototype cannot be reproduced. Record version, seed data, route, viewport, assets, and interaction steps.

Generated tokens fork the design system. Require the canonical token source and owner approval before implementation.

The code matches one screenshot but not the flow. Test state transitions, keyboard behavior, responsiveness, copy, and failure recovery.

The same agent approves its own work. Separate build, independent review, and human acceptance.

Verify the handoffs

• Every stage names its input, output, owner, and acceptance decision.
• Critical states and breakpoints exist before implementation.
• The design contract points to canonical tokens and components.
• Production code is tested in the real application.
• Visual findings contain route/state and evidence.
• Tool changes do not require rewriting the artifact chain.

Improve the weakest artifact

Use the evidence-based rating loop at each handoff, then continue through Build and Test.