How to implement a prototype with an AI agent, step by step

To implement a prototype with an AI agent, settle the version you chose, have the agent map it to your codebase in a plan before it edits anything, build one screen state at a time with your existing components and tokens, then verify each state against the prototype at the same size and record what shipped. The prototype tells the agent what the result looks like. Your codebase tells it how to build it.

Before you start: what must be decided

Implementation goes wrong most often because a decision was left open and the agent made it. Before you ask for code, check:

• One chosen version per state. If three variants are still on the table, the agent will pick one, or blend them.
• Every state you care about exists. Default, empty, loading, error, long content. A state missing from the prototype gets improvised in the code. The UI states checklist helps you find them.
• What the prototype does not say. A prototype shows appearance and flow with sample data. Where the data comes from, what happens when a request fails and who may see the screen come from your code and your specs: say so in the request.
• The scope. Which routes and files change, and which shared components must not.

Step 1: map the prototype to your code, in a plan

Ask for a plan first, with no edits. In Claude Code, plan mode is made for this: the agent reads files, explores and writes a plan without editing your source, and waits for your approval before it changes anything. Start a session in it with claude --permission-mode plan, switch to it with Shift+Tab, or prefix a single prompt with /plan (see Claude Code permission modes).

/plan Implement the chosen prototype of the Invoices screen: states default, empty,
loading and error. For each state, list the route, the files you will change, the
existing components you will reuse, the tokens you will use, any new component you
think is needed and why, the data it needs and where it comes from, and your open
questions. Do not write code yet.

Read the plan for three things: new components where an existing one would do, raw values where a token exists, and data the prototype shows but your API does not provide. Correcting a plan costs a sentence. Correcting a diff costs a review.

Step 2: reuse before you create

A prototype written as HTML is a reference, not code to paste. Its markup is flat, its CSS is inline and its data is invented. Copied into your app, it would bypass your components, your tokens and your accessibility work, and it would look right while being wrong underneath.

Give the agent a clear order of preference:

1. An existing component, with its existing props.
2. An existing component with a new prop or variant, if the difference is real and reusable.
3. A new component, only when nothing fits, named explicitly in the report.

The same order applies to styles: an existing token first, a new token if a value is really new, never a raw value in a component. Design tokens an AI coding agent can follow shows how to set that rule up.

Step 3: implement one state at a time

Build the default state first, then the others in order of how often users see them: empty, loading, error, then edge cases such as long names or many items. After each state, the agent should tell you how to open it: by route, by a prop in a story, or by a test fixture. A state you cannot open is a state nobody reviews.

Keep each step small enough to review:

Implement the default state only. Reuse InvoiceTable and PageHeader. Then run
npm run typecheck and npm test, and stop. Tell me how to open this state locally.

Continue with the next state in the same conversation, so the agent keeps the plan in its context.

Step 4: verify against the prototype

Checks prove the code works. Comparison proves it matches. You need both.

Check	How	Passes when
Types, lint, tests, build	The commands of your repository	All pass, with no rule disabled to get there
Each state can be opened	Route, story or fixture	Every state of the prototype opens on its own
Visual match	A screenshot at the prototype’s viewport, side by side	Same layout, spacing, texts and colors, or the difference is explained
Tokens and components	A search for raw values, then the diff	No new hex or px values in components
Real content	Long text, empty data, API errors	Nothing overflows or disappears

Compare at the same viewport as the prototype, for example 1440 x 900 or 390 x 844. Otherwise every difference turns into a discussion about breakpoints. How to review UI changes made by an AI agent covers the review itself.

Step 5: record what shipped

Ask for a short report before you merge:

Report: states implemented, files changed, components reused or added, tokens added,
checks run with their result, and every difference from the prototype with the reason.

Then record which prototype version each state now implements. That record is what lets you change the prototype later and know exactly what is waiting to be built. Without it, the next change starts with a guess about what is live.

How agentappbuilder runs this loop

With agentappbuilder, the prototype and the record of what shipped live in the same place. Each screen state is a frame with numbered versions. The active version is the one you chose, and the implemented version is the one your agent last reported as coded. When you say “Apply the prototypes.” (or “implement”, or “code it”), your agent takes each frame whose active version differs from its implemented one, codes what that version shows in your real app, runs your app’s checks and reports the implemented versions. The canvas then shows “Implemented: vN” for these frames.

A few rules keep it safe. Nothing is coded until you ask. A state whose variants wait for your choice is not implemented. If you later make another version active on a state that is already implemented, your agent asks you whether production should follow before it changes anything. A version can also carry an optional contract, a JSON description of what the code must honor for that state. Working with your agent has the prompts, and concepts defines versions and notices. A quality harness that your agent installs in your repository (specs, tests, CI) is coming next. Today, your agent runs the checks your app already has.

Summary

Implementing a prototype with an agent works when the decisions come before the code: one chosen version per state, a plan mapped to your components and tokens, one state at a time, checks plus a side-by-side comparison, and a record of what shipped. The prototype says what the user sees. Your codebase, and the rules you wrote for the agent, say how it is built.