Methodology Resource · v2

Design-to-Code Pipeline

A codebase-first system for turning visual intent into deterministic AI build rules.

Most design-to-code processes treat visual consistency as a discipline problem — careful developers, design reviews, periodic audits. It degrades whenever attention lapses, which is always.

This pipeline treats it as a context problem. When AI agents have structured context to consult before acting, consistency becomes a procedural output rather than something you police. The system converts design deliverables into two machine-readable indexes — a design JSON for visual intent and a component index for structural composition — and every agent that builds UI reads both before writing a line.

The v2 pack makes this operational: a portable, self-configuring setup that runs the full pipeline from a single command, handles whatever a design agency actually delivers, and includes a fillable brief to give the agency before work begins.

How It Works

A sequential pipeline from design deliverables to a token-styled, atomically structured codebase — and a standing system that keeps it consistent as the product evolves. Setup runs once. The first three phases are one-time execution. From Phase 4 onward, the system operates continuously.

The pipeline runs via an AI coding agent — Claude Code or equivalent. You don't run Node commands yourself. You point the agent at the pack, give it the invocation, and it drives the full sequence end-to-end, stopping only at the three human decision gates. Your role is directing, not operating.

Tell your agent:

Run: node design-agent-pack/scripts/init.mjs
Then: node design-agent-pack/scripts/run-agent.mjs --config <path-to-pack.config.json>

Pipeline Stages and Agents

Phase	Agent	Mode	Function
1	Intake	One-time	Format-agnostic ingestion of agency deliverables. Produces enriched design JSON, CSS tokens, and conflict audit.
2	Census	One-time per wave	Inventories components across all product roots, scores duplicates, produces migration ledger. Gates the Atomizer.
3	Atomizer	One-time + standing	Restructures codebase to atomic hierarchy. Generates the component index. Defers high-coupling organisms to developers.
4	UI Builder	One-time	Replaces all hardcoded styling with design tokens. Zero functionality changes. Flags anything it can't resolve with confidence.
5	UX Audit	Manual	Storybook review at every atomic level. The single human quality gate before ongoing operation.
6	Feature Builder	Ongoing	Builds new UI from spec by consulting both indexes. Contacts the Atomizer for any new component creation.
—	Curator	Standing	Tracks usage counts, flags one-offs for promotion, emits `curator-report.md` as a developer work queue after each run.
—	Postmortem Governor	Standing	Archives stage runs, tracks finding lifecycle, detects drift across consecutive pipeline executions.

Stack Assumptions

The published agents target React or Svelte with Tailwind CSS and Storybook for component review. All file paths are configured at init time via pack.config.json — no manual placeholder replacement. The methodology, schemas, and governance model are stack-agnostic; adapting to another framework means updating file extensions and syntax references, not the agent logic.

The pack includes eight JSON Schema files (one per structured artifact type) and two Node.js validation scripts — single-artifact and batch validation against the artifact registry. Schema validation runs as a post-step after every JSON-producing stage; failures surface as P0 findings before they propagate downstream.

Status

Active and in production use. The pack is versioned. The methodology evolves as it runs against real codebases. This is not a packaged product — it is a published methodology with working implementation artifacts. Use it, adapt it, and if you build something with it, reach out.

Agent Pack — v2

For teams implementing the full pipeline

Agent specification files for all pipeline stages
JSON Schema contracts + validation scripts
Single-command orchestrator (run-agent.mjs)
Init script, config templates, scan manifest
Design agency intake template (DESIGN.md)

Get Agent Pack

Agency Brief Only

For briefing a design agency before engagement

Fillable DESIGN.md template
11 sections covering palettes, surfaces, dark mode, states, typography
Rationale per section written for designers, not engineers

Get Brief Template