From Mockup to Code

Module 2 ended with a configured setup and a read-only first session. This module is the payoff: the central, repeatable workflow of giving Claude Code something visual you already have — a screenshot of a mockup, an exported frame, a reference page — and getting back working front-end code. Everything later in the course (prototypes, design systems, automation) is a variation on the loop taught here.

Set expectations early about what conversion means. The promise is not pixel telepathy. A screenshot does not carry responsive behaviour, interaction states, accessibility semantics, or the product rules behind the visible layout. The promise is that the agent can do the structural and syntactic work — markup, layout, components, tokens — while the designer supplies interpretation and judgment, and verifies the result with evidence rather than a glance.

If participants did the Module 2 exercise, they already have a project open and five questions answered about it. Encourage them to use a section from that same project for this module's exercise rather than a toy example, because the review habits only become real against work they care about.

Walk the input types in the order designers will actually use them. Screenshots and exported frames come first because every designer has them: Anthropic's own documentation treats image-to-code as a first-class workflow, with prompts like 'what HTML structure would recreate this component?'. In the CLI, images are pasted with Ctrl+V rather than Cmd+V on macOS — a small detail that trips people up on day one — and they can also be dragged in or referenced by file path. In VS Code and Desktop, attaching an image is more conventional.

The second category is the project itself. The agent can read existing components, token files, and stylesheets, and the @ mention syntax pulls a specific file or folder into context deliberately. This matters for conversion quality more than the image does: an agent that can see your Button component and your spacing tokens will reuse them, while an agent that cannot will invent its own. The instruction file from Module 2 — CLAUDE.md, optionally a DESIGN.md — is where rules that apply to every conversion belong.

The last two categories are the ones people forget. A URL or a local preview gives the agent something it can open and inspect when the browser connection is set up. And real copy and data pasted into the brief prevents the most common conversion failure of all: confident, plausible, invented content. As of June 2026 all of these input paths are standard Claude Code behaviour, not extensions.

This distinction carries the whole module, so spend time on it. A screenshot is genuinely powerful evidence — it communicates hierarchy, density, rhythm, and component relationships better than a paragraph of description ever will. But it is structurally incomplete. It cannot show what happens at 390 pixels wide, what the empty state looks like, which elements are interactive, what the focus order should be, or why the design made a particular trade-off.

The sharpest version of the distinction is visual traits versus product rules. The agent can reasonably infer visual traits from the image: this table uses compact rows, this cancellation link is deliberately quiet, this summary sits above the payment method. It must not invent product rules: who is allowed to cancel, what confirmation is required, what happens when billing data has not synced. If the screenshot shows a cancellation link, the implementation still needs the rules behind it — and if you do not supply them, the agent will guess, confidently.

The practical consequence is that the designer's job in this workflow is the interpretation layer around the image: stating what matters, what can change, what must not change, how unknown states should be handled, and how the result will be judged. That interpretation is exactly what the briefing and annotation steps on the next slides capture.

This slide compresses the school's published prompt teardown, where the same pricing-page request was actually executed twice against an identical scratch target. The vague 26-word version produced the genre average — gradient hero, three interchangeable cards, invented prices — and failed a token audit with 33 hardcoded-colour violations across three correction rounds. The 87-word constrained version asked for decision criteria before building, reused restrained styling, and passed the audit in two rounds. Quote those numbers as what happened in those specific runs, not as a benchmark.

The lesson for mockup conversion is that the brief should carry constraints and decisions, not adjectives. Useful constraints for a conversion brief: which existing components and tokens to use, which states are required (loading, empty, error, disabled, focus), what the section must do on mobile, what content is real and what may not be invented, and what you will check before accepting it. Adjectives like clean, modern, or pixel-perfect carry no decisions and produce the agent's idea of those words, not yours.

Also name the layering point so people do not write 300-word prompts forever: rules that apply to every conversion — token discipline, banned gradients, component reuse — belong in CLAUDE.md or DESIGN.md from Module 2, not retyped per request. The prompt should carry only what is specific to this section: this screenshot, this user job, these states, this content.

Walk the diagram left to right and name who owns each step. Reference in is human: the screenshot or mockup, plus the things the screenshot cannot carry — tokens, components, design rules, real content — and the explicit instruction to annotate first rather than build. Structure analysis is agent-run and read-only: it describes the layout regions, the hierarchy, the components it would map each region to, the states it thinks are required, and the unknowns it cannot infer. The annotation gate is human: you correct the reading while it is still words. If the agent has misread the hierarchy or mapped a region to the wrong component, fixing it here costs a sentence; fixing it after generation costs a round.

Generate is the agent building the section against existing components and tokens, with real states and no invented content. The parity check is also agent-run: it captures screenshots of the built section at the relevant widths and compares them against the reference, listing mismatches and likely causes. Designer review is the human gate where judgment happens — hierarchy, spacing, density, states — and where feedback gets phrased as named mismatches the agent can act on. Accept is a human decision, and the packet of reference, annotation, and QA notes is kept so the next run does not rediscover the same context.

The most common way people collapse this pipeline is skipping straight from screenshot to generate. It feels faster and usually is not, because every misreading that the annotation gate would have caught for free comes back as a correction round after the code exists.

This traced run follows the first-prototype chapter of the book: a single hero section, generated as one self-contained HTML file with inline CSS, no frameworks and no build step, opened directly in the browser with a single command. That shape is deliberate. It removes every piece of setup friction — no npm, no dev server unless you want auto-refresh — and it produces an artifact small enough that a designer can review all of it.

Walk what happens when this brief runs. The annotation request comes back first: the regions, the hierarchy, the states, and usually one or two honest unknowns, such as what the section should do at narrow widths. The generation that follows is markedly better than an unbriefed run because the constraints are doing work: the copy is yours, the values are read from the reference and listed so you can check them, and hover and focus states exist because they were asked for. The closing line — screenshot, compare, list differences — is lifted almost verbatim from Anthropic's own best-practice guidance, which calls giving Claude a way to verify its work the single highest-leverage thing you can do.

Viewing the result is part of the run, not an afterthought. The simplest path is opening the file directly; the exclamation-mark prefix in the CLI runs a shell command like open hero.html without leaving the session. A Live Server style auto-refresh setup is worth adding once iteration starts, and the Chrome connection from Module 2 lets the agent see the rendered result itself. In a real product codebase the same brief points at an existing component and the project's tokens instead of inline CSS — the shape of the brief does not change, only the materials.

This slide is the literacy designers actually need, and it is reading rather than writing. The five checks are deliberately ordered from cheapest to hardest. Structure first: even without knowing the framework, you can see whether the markup has the same shape as the design — distinct regions, headings where headings belong, a list rendered as a list — or whether everything is an anonymous stack of div elements. Semantic structure is also where accessibility starts, so this check pays twice.

Tokens and components are the system checks. Scan for hardcoded hex values and pixel numbers where your project has named tokens, and for new component files that duplicate something the system already provides. You do not need to judge the code quality of either; you only need to notice that they exist and ask the agent why. Spacing and density are visual checks done in the browser against the reference, and the specific drift to watch for is everything becoming slightly more generous than the design — agents tend toward comfortable defaults.

States are the check most often skipped because the happy path renders beautifully. Ask to see the empty state, the error state, the loading state, and keyboard focus, by name. The diff view in VS Code, or asking the agent to summarise its own changes file by file, makes all five checks easier; reviewing a diff is a skill designers pick up in days, not months.

Each of these failure modes is common because each is the path of least resistance for the agent. Spacing drift happens because comfortable, evenly padded layouts dominate the agent's training distribution; your deliberately dense table reads to it like something to fix. Fake data happens whenever real content is missing from the brief — the agent will not leave a gap, it will fill it, and the filled version reads confidently enough to survive a stakeholder review before anyone notices the prices are fictional.

Missing states happen because the screenshot only ever shows one state. System drift happens when the agent cannot see the design system, or can see it but was not told to use it; the result is a parallel set of lookalike components that work today and rot immediately. Responsive drift is the subtlest: the mobile layout often preserves the visual stacking of the desktop DOM rather than the priority order of the user's task, which is a design decision the agent cannot make because nobody stated it.

The meta-point to land: every one of these is invisible in a quick glance at a rendered desktop view, which is the only review most people do. That is the argument for the structured review on the previous slide and the evidence-based parity check on the next one. It is also the argument for putting the recurring rules — token discipline, component reuse, required states — into the harness file so they stop depending on your memory.

The parity check converts review from impression to evidence. Anthropic's guidance for visual work is blunt about this pattern: paste the design, implement it, take a screenshot of the result, compare it to the original, list the differences, and fix them. With the browser connection from Module 2 — or a screenshot script in the project — the agent can do the capture and comparison itself, which means the evidence costs you a request rather than an afternoon.

The prompt on the slide encodes three habits worth naming. First, it asks for capture at two widths, because responsive drift never shows up in a single desktop screenshot. Second, it orders the report by what matters: structure before spacing before polish, and it explicitly asks about missing states and non-system tokens, which a purely visual diff would not surface. Third, it ends with do not change any code yet — the agent reports, the designer prioritises, and only then does a fix round start. Letting the agent fix everything it finds, unprioritised, is how a tidy section gains twenty unrequested changes.

Keep the output. The reference, the annotation, and the QA report together form a small packet that lives in the project, and the published screenshot-to-implementation workflow this slide draws on treats that packet as the deliverable alongside the code: the next run, by you or by someone else, starts from recorded decisions instead of rediscovering them.

Iteration is where most of the session time goes, so the quality of the feedback determines the cost of the workflow. The weak revision prompts on the slide fail for the same reason the vague brief failed: they name a feeling, not a mismatch. The strong ones name what is different, why it matters to the user, and what direction to move — which is exactly the kind of critique designers already give human collaborators, just written down with values where values exist.

Two mechanical habits keep iteration from degrading. The first is the two-corrections rule from Anthropic's best-practice guidance: if you have corrected the same issue more than twice in a session, the context is cluttered with failed approaches; clear the session and start fresh with a better brief that incorporates what you learned. Designers can think of /clear as a new artboard. The second is the checkpoint system: Claude Code snapshots files before editing them, so a round that made things worse can be rewound rather than argued with — Escape twice or the rewind control in VS Code.

Close the loop with the harness point. Feedback that recurs across different tasks — stop hardcoding colours, always include the empty state, never invent copy — is not feedback anymore, it is a rule, and rules belong in CLAUDE.md or DESIGN.md where every future run reads them. That observation is also the bridge to the design-systems and automation modules later in the course.

This slide is short but it changes the economics of the workflow. The first conversion of a screen costs real effort: writing the brief, correcting the annotation, running the parity check, deciding what was acceptable to leave unresolved. If those artifacts evaporate into a chat history, the second conversion — a revision next sprint, the same pattern on a sibling screen, a colleague picking up the work — pays the full cost again, and may repeat the same mistakes.

The packet is deliberately boring: the reference images, an annotations file recording how the screenshot was interpreted, an unknowns file recording what the screenshot could not define, the brief, the component map, and the QA report. The exact folder names matter less than two properties: the files live in the repository where any future agent run can read them with an @ mention, and they record decisions rather than just outputs — including the things deliberately not fixed, so nobody refixes or relitigates them by accident.

This is also the first appearance of a theme that grows through the rest of the course: the difference between a one-off win and a repeatable capability is almost always a small amount of recorded context. Module 6 turns this packet idea into skills and scheduled runs; here it is just a folder and a habit.

The exercise runs the entire pipeline once, on real work, at the smallest scale that is still honest. Steer participants away from two failure modes when choosing the section: too big — a whole page or a whole flow buries them in review and the exercise becomes about stamina — and too synthetic, because converting a tutorial mockup teaches nothing about their own tokens, their own components, or their own product rules.

The step people will be tempted to skip is correcting the annotation, especially if the agent's first reading looks broadly right. Insist on it: finding at least one thing to correct — a hierarchy call, a state it missed, a component mapping — is what makes the gate real rather than ceremonial, and it is the moment most participants discover the agent had quietly misread something they would otherwise have found three rounds later. The other discipline is limiting iteration to one named-mismatch round within the exercise; the goal is to practise the shape of the loop, not to reach perfection today.

If participants kept the planning page from the Agentic Design Fundamentals course or the Module 2 exercise from this course, this is the moment those connect: same project, now with code coming back. Collect or discuss the QA reports if running this live — the recurring mismatches across a group are a preview of what belongs in a shared harness, which is where the design-systems module picks up.

Recap by walking the pipeline rather than the slides: evidence in, structure analysis, the annotation gate, generation against the system, the parity check, designer review, and a human decision to accept — with the two cheap loops, correcting the reading before code exists and sending named mismatches back as a new run. The skills that made it work are all designer skills: supplying interpretation, writing constraints, reading structure, and judging evidence.

Be explicit about what was deliberately small in this module. One section, one file or one component, one round of iteration. That boundedness is what made every step reviewable, and it is the unit the next module composes from: a prototype is not one giant prompt, it is a sequence of runs shaped exactly like the one practised here, plus realistic data and navigation between screens, plus honesty about the line between prototype and production.

If participants finished the exercise, their section, brief, annotation, and QA packet are the starting materials for Module 4's first activity — say so, so the artifacts do not get discarded as homework. If they did not finish, the minimum to carry forward is the chosen section and the screenshot; the rest can be rebuilt in the first part of the next module.