Spec-first series
Spec to codeCode like MicheWork visuallyDurable assetClaude has /skills

Visual-first builders

Your mockup is half a spec.
Here's the half that's missing.

An image specifies arrangement, density, and feel. It cannot specify behavior, permissions, or empty states. Words specify those — but they describe layout badly. The spec is the container, not the medium.

See how it works

The container holds both

Image normative for appearance.
Text normative for behavior.

Same screen. Two different media governing two different things. The spec document says which governs what.

🖼 Image governs
Arrangement & feel
What the screen looks like, where things are, how dense, what hierarchy reads first.
?
Behavior not shownWhat happens when the badge is clicked? Does it filter? Open a panel? Nothing?
?
Empty state not shownWhen no cards exist, what does the main area render?
?
Permissions not shownCan every user see the header button, or only owners?
📄 Text governs
Behavior & rules
What happens on interaction, who sees what, what loads in which order, what the edge cases are.
Interaction
Clicking a status badge filters the card list to that status in place. No navigation. Clears on second click.onClick → setFilter(badge.status); if filter === badge.status → clearFilter()
Empty state
When the filtered list returns zero cards, render the empty state component with the label “Nothing in [status]” and a clear-filter link.
Permissions
The header action button is visible to role: owner | admin only. Read-only members see the list but not the button.
The spec document says: image governs layout and visual hierarchy; text governs interaction, data, and access rules.

Now the agent doesn't have to guess at the design or the behavior.

The argument

A mockup without a spec
is just pixels with vibes.

Handing your agent only a mockup doesn't skip the spec — it just moves where the spec gets written. Instead of one written document, you get forty correction prompts, arriving after the code already exists.

What the image says
Arrangement. Hierarchy. Density. Tone.
Your mockup is authoritative here. The agent should follow it exactly — spacing, grouping, which element reads first, what the page feels like. The image is normative. The agent doesn't need your words to get this right.
What the image can't say
Behavior. Rules. Load order. Empty states.
No mockup shows what happens when a list is empty, who can click the button, or what fires when something drags. The agent guesses — and it guesses wrong in ways that cost you a correction session just like any other unwritten spec.
What the spec adds
The document says which medium governs what.
The spec isn't replacing the mockup. It's the container that holds both — annotated frames embedded where words flail, text governing behavior. Your mockup becomes acceptance criteria instead of a vibe to prompt toward.

Starting from scratch

No codebase yet?
Stronger, not weaker.

When there's no existing code, the visual artifact is the only source of design language. If you hand the agent only a mockup, it fills in the design system from its own defaults — which become the permanent design system by accident. Reference the mockup in your spec so the agent has an explicit normative source, and the first build looks like your intent, not like a framework's opinion.

🖼
Reference the mockup
Describe your UI sketch in the spec — what it shows, how it's organized, what the key hierarchy is. Share the image directly with the agent at build time so it has the actual visual reference alongside the written spec.
📄
Write the behavior spec alongside it
The spec says: image governs appearance; this text governs behavior. The document now contains both media with explicit governance.
⚡
The agent builds to both
Visuals from the image. Behavior from the text. No guessing. Your mockup promoted from vibe to acceptance criteria.

In DecisionGraph

The spec is the container.
The medium is up to you.

Brainstorm with Claude. Generate the spec with /spec-it. Lodge it. Decompose into stories. The mockup reference lives in the document. The behavior lives in the text. Both travel with the work.

01
Annotate what words can't say
Reference the mockup frame in the spec where layout matters. The document notes which medium governs which surface. No more “the image is somewhere in Figma” — the spec points to it with context.
02
Write the half the image misses
Behavior, rules, empty states, permissions. A few paragraphs alongside the reference. The agent now has both underdetermination problems solved — appearance and behavior, in one document.
03
Decompose and build
The Decomposition Engine turns the spec into epics and stories. The mockup reference stays in lineage. Six months later, the new engineer knows exactly what the spec said — not just what the code does.

No tradeoff

Move at AI speed.
Stay in control.

AI gives you speed.
DecisionGraph remembers why.

The spec-first series

Code like Miche

Let the agent rough out the work so your time goes to the details that matter most.

Read → /apprentice

The spec is a durable asset

The prompt-stream spec dies with the session. The written spec keeps working after ship.

Read → /durable

Claude has /skills

DecisionGraph knows when to use them. Skills are capability. The graph is timing.

Read → /skills

From spec to developer-ready code

The whole loop — spec, decompose, build, verify — start to finish.

Watch → /spec-to-code