How to prototype app screens with Claude Code before coding

To prototype app screens with Claude Code, ask it for one self-contained HTML file per screen state (empty, loading, filled, error, modal open), built from your real code and sized for your device, and tell it not to modify the app. Review those frames, ask for changes against one specific frame, and only when a version looks right, tell Claude Code to implement it. The steps below work with nothing but Claude Code and a browser.

Why prototype before Claude Code writes code

Claude Code is fast at changing a component. It is less good at guessing what you meant by “make the list clearer”. When the first thing you see is a diff, you judge the screen through code, and you notice the missing empty state or the cramped error message after it is merged.

A prototype turns that around. You look at the result first, while it is cheap to throw away, and the code changes once you have picked. Three habits make it work with a coding agent:

• Prototypes are separate files. Your repository stays untouched until you say “apply”.
• Each state is its own frame. You review “the list with a save error”, not “the list”.
• Every change is a new version. You can compare and go back without asking the agent to remember what it did.

List the screens and their states first

Before any HTML, ask Claude Code to read the code and list what exists. A short inventory prevents the classic gap where the happy path is prototyped and nothing else.

Read the routes and page components of this app. List each screen with its route, its source file and every state a user can reach. Do not write any code yet.

Check the list against this table. Most screens need at least three rows.

State	What to show	Often forgotten because
Empty	First use, no data, a clear next action	Seed data hides it
Loading	Skeleton or spinner, stable layout	It lasts 200 ms on a fast machine
Filled	Realistic data, long names, many rows	Placeholder text is always short
Error	The message, where it sits, how to retry	The API never fails locally
Modal or panel open	Focus, what stays visible behind	It needs a click to reach
Restricted	What a read-only user sees	Everyone tests as admin

Ask for self-contained HTML, one state per file

The format matters more than it seems. A self-contained HTML file opens in any browser, needs no build step, and Claude Code can read it back later to change it. Ask for it explicitly:

Prototype the Interventions screen before changing any code. Write one self-contained HTML file per state in /tmp/prototypes/interventions/: empty, list, list filtered by "late", new intervention modal, save error. Inline CSS only, no scripts, no remote fonts or images, 1440 x 900. Use the real labels, colors and spacing from src/pages/Interventions.tsx and realistic sample data. Do not modify the app code.

Rules worth repeating in every prompt:

• Inline CSS, no scripts, no network. A prototype shows a state; it does not simulate behavior. Remote assets break as soon as the file is opened elsewhere.
• One state per file. A file that toggles between states with JavaScript hides half of them.
• Real texts and sample data. Your actual labels, and names long enough to wrap.
• The device size. 390 x 844 for a phone, 1440 x 900 for a desktop, so the layout is judged at the size people use.
• Outside the repository. A folder such as /tmp/prototypes that you can delete, so nothing ends up in a commit by accident.

Show the current app before changing it

A redesign should start from what the app shows today, not from the agent’s reading of the code. If the app runs locally, a screenshot of each state is more faithful than a redrawing. Playwright screenshots do this in a few lines: open each route, click to reach a modal or a tab, save one image per state.

Two rules keep this safe. Use a demo account and demo data, because a screenshot captures whatever is on screen. And keep a one-off capture script outside your repository.

When you then ask for a change on a captured screen, ask Claude Code to first recreate it as HTML faithful to the screenshot and to the code, then apply the change. You get a before and an after that you can put side by side.

Iterate on one frame at a time

Vague feedback on a whole flow produces vague changes. Point at one frame and say what to change:

In /tmp/prototypes/interventions/save-error.html: move the error message above the form, keep the values already entered, and make the Retry button primary. Save it as save-error-v2.html and write one line on what changed.

Keep every version. A numbered file with a one-line change note is enough for a solo project: it lets you compare v2 with v1, and return to v1 without asking the agent to undo anything.

When you are not sure of the direction, ask for variants instead of one answer: “Propose three variants of the empty state, labelled A, B and C.” Then choose yourself. An agent that picks its own favorite skips the step where your judgment matters.

Apply only what you chose

When a version is right, the handoff is one clear instruction:

Implement save-error-v2.html in the real app: src/pages/Interventions.tsx and its components. Keep the existing tests passing, add one for the error state, run the checks, then list the files you changed.

Then review as usual: git diff, the tests, the running app next to the prototype. If something differs, the prototype is the reference, which is much easier to point at than a memory of the chat.

Doing this with agentappbuilder

The folder of HTML files works, but you end up managing file names, versions and screenshots by hand. agentappbuilder is a workspace built for this loop with Claude Code:

• Claude Code writes each state as a frame on a canvas, linked to the next state by the user action that leads there (“Tap Save”).
• With your agreement, it captures your running app with a Playwright script on your machine, one screenshot per state, on a Live app canvas. You import the captures you want into the prototype.
• Each frame has a URL. You paste it in the chat with your request, and Claude Code adds a new version. Older versions stay listed, and Compare shows two side by side.
• Claude Code can propose 2 to 4 variants of a state; you choose one on the canvas.
• Small changes (fill, stroke, corner radius, padding, auto layout, text styles) you make yourself on the canvas. They become a version signed by you, which the agent must not replace without asking.
• When you say “apply”, Claude Code codes the active versions and reports them as implemented. If you later make another version active, it asks you before production follows.

Setup is one sentence to Claude Code: Getting started walks through it, and Working with your agent lists the prompts for each step. If you prefer to connect over MCP, the Claude Code MCP server setup guide explains the command and its scopes.

Conclusion

Prototyping with Claude Code comes down to a few habits: list every state, ask for one self-contained HTML file per state, change one frame at a time, keep versions, and apply only the version you picked. A folder and a browser are enough to start. If you want the canvas, the frame URLs and the versions handled for you, agentappbuilder does that part, and your agent still writes the code in your repository. To see how the guide Claude Code follows is written, read how to write an llms.txt that coding agents follow.