Agentic Prototyping for Designers: A Practical Guide to Claude Code & Codex

Part 1 — Orientation

1. Why Agentic Prototyping

For the last decade, the design-to-dev handoff has looked roughly the same: you design in Figma, write specs, hand it to an engineer, wait, review, request changes, wait again. Agentic prototyping breaks that loop.

Tools like Claude Code and OpenAI's Codex CLI let you describe what you want in plain language — or point them at a Figma file — and watch them write, run, and preview real, working code. Not a static mockup. Not a click-through prototype held together with hotspots. An actual running application with real interactions, real state, and real data if you want it.

This is the biggest shift in the design workflow since Figma replaced Sketch. Designers who learn this workflow stop being dependent on engineering time for early-stage validation — you can test an interaction pattern, a flow, a piece of copy, or a whole feature concept as a real product experience, in an afternoon, and share a live link with your team the same day.

By the end of this tutorial, you'll have:

A working local dev environment
A project scaffolded with a real design system (ShadCN)
A published, shareable prototype on Vercel
A repeatable feedback loop between Figma and code
A sense for when to prompt and when to just open Figma

2. What's In Scope / Not In Scope

In scope:

Fast, high-fidelity, real prototypes — actual HTML/CSS/JS running in a browser
Realistic interactions, transitions, and states (loading, empty, error)
Testing flows and concepts with actual stakeholders using a live URL
Iterating on visual and interaction design in code, not just in Figma

Not in scope:

Production-grade engineering: proper backend architecture, security hardening, scalability, accessibility audits beyond the basics, full test coverage
Replacing your engineering team — this is a prototyping and exploration workflow, not a way to ship production software solo
Pixel-perfect design system governance — that still lives in Figma and your component library

Think of this as the highest-fidelity prototyping tool available to you today — a rung above Figma prototyping, a rung below shippable production code.

3. How Coding Agents Actually Work (A Designer's Mental Model)

Before you touch a terminal, it helps to understand what's actually happening when you "prompt" an agent.

The agent reads your prompt and decides what files to create or edit.
It has access to your project folder — it can read existing files, write new ones, and run commands (like starting a dev server) on your machine.
It works in a "context window" — think of this as its short-term memory for the current conversation. It doesn't remember previous sessions unless you tell it to (more on this in Section 10, CLAUDE.md).
It shows you what it's doing — file edits, terminal commands, and reasoning — so you can interrupt, correct, or approve as it goes.
It is not deterministic. The same prompt can produce slightly different code each time. This is why specificity and structure (Section 11) matter so much.

The most useful analogy: you're not writing code, you're directing an extremely fast, extremely literal junior developer who has read every framework's documentation but has zero context on your specific project unless you give it that context.

4. Claude Code vs. Codex — Which to Pick

Both are terminal-based coding agents, and both are genuinely capable. Here's the practical breakdown:

	Claude Code	Codex CLI
Maker	Anthropic	OpenAI
Access	Claude subscription (Pro/Max) or API key	ChatGPT Plus/Pro/Team, or API key
Standout features	Skills, subagents, hooks, native MCP support	Open-source (Apache 2.0), strict sandboxing by default
Best for	Designers who want an ecosystem of reusable "skills" and tight Figma/MCP integration	Designers already on a ChatGPT plan, or who want a more sandboxed, cautious default

In practice, both tools are highly capable across the workflow this guide covers, and this guide's screenshots and commands lean on Claude Code. The advice, prompt structures, and MCP setup apply almost identically to Codex — swap claude for codex in the terminal commands and you're set. A good rule of thumb: if you're stuck on one, try the other on the same prompt — they occasionally reach different, useful solutions.

Part 2 — Setup (One-Time)

5. Pre-Requisites & Dependencies Checklist

You don't need to install everything below on day one. Start with Must install, and add from the other two tiers as your workflow matures.

Must install

A code editor with an integrated terminal VS Code or Cursor — you'll use this to see the files your agent creates and to open a terminal.

Node.js (via a version manager) Don't install Node directly — use a version manager so you never fight version conflicts across projects.

# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Install and use the latest LTS version of Node
nvm install --lts
nvm use --lts

Claude Code (or Codex CLI)

# Claude Code — native installer (recommended, no Node required)
curl -fsSL https://claude.ai/install.sh | bash

# Verify installation
claude --version

# Codex CLI
npm install -g @openai/codex

# Verify installation
codex --version

On first launch, both tools open your browser to authenticate — sign in with your Claude or ChatGPT account (or paste an API key if you're using one).

Running dev servers & local preview This is the step that trips up most designers, so it deserves its own explanation. When your agent scaffolds a project, it doesn't automatically show it to you — you have to run it:

npm run dev

This starts a local server, usually at http://localhost:3000 or http://localhost:5173. Open that URL in your browser and you'll see your prototype live, updating as the agent (or you) makes changes. If the port is already in use, most tools will automatically try the next one (3001, 3002...) — check your terminal output for the actual URL.

GitHub account + Git basics Create a free account at github.com if you don't have one. Covered in depth in Section 6.

Strongly recommended

A voice-to-text app Typing full context into a prompt is slow and often produces terser, worse prompts than you'd give verbally. Dictating a paragraph of intent — the way you'd explain a flow to a teammate — tends to produce better prompts, not just faster ones. Two solid options:

Wispr Flow — cross-platform (Mac, Windows, iOS, Android), cloud-based, AI-cleaned transcription, built-in support for dictating into coding tools like Cursor and VS Code.
Superwhisper — Mac-only, runs OpenAI's Whisper model fully on-device, better if privacy/offline use matters more to you than cross-platform sync.

Either works well; pick based on whether you want on-device privacy (Superwhisper) or cross-platform reach and app-aware tone switching (Wispr Flow).

Figma MCP server MCP (Model Context Protocol) lets your coding agent read structured design data directly from a Figma file — components, variables, layout, tokens — instead of guessing from a screenshot. This is what makes "point the agent at Figma" actually work well. Setup:

Open Figma desktop, open your file, switch to Dev Mode.
In your terminal, connect it to Claude Code:

claude mcp add --transport http figma https://mcp.figma.com/mcp

Or for Codex:

codex mcp add figma --url https://mcp.figma.com/mcp

Authenticate when prompted. Once connected, you can select a frame in Figma and prompt your agent with something like "Build this selected frame as a React component using our design tokens."

Full setup docs (including VS Code and Cursor instructions): Figma MCP Server Guide.

Browser tooling

Figma's Dev Mode / Chrome extension — needed for the code-to-Figma workflow in Part 4.
Chrome DevTools' device toolbar (Cmd/Ctrl + Shift + M) — for quick responsive checks without a separate tool.

Nice to have

A screenshot/annotation tool for grabbing UI states quickly (e.g. CleanShot X) — useful as backup if Agentation doesn't cover a given case
.env hygiene — never paste real API keys or secrets directly into a prompt; keep them in a .env file that's excluded from Git (more in Section 18)
A password manager for any service credentials you set up along the way

6. GitHub: Version Control as Your Undo Button

If you take one habit from this entire tutorial, make it this one: commit often.

Coding agents move fast, and occasionally they'll make a change you didn't ask for or don't like. Without version control, "undo" means starting over. With it, "undo" means one command.

The core loop:

# Check what's changed
git status

# Stage everything
git add .

# Commit with a short message
git commit -m "Add pricing page hero section"

# Push to GitHub
git push

If the agent breaks something:

# See exactly what changed
git diff

# Revert a single file
git checkout -- path/to/file.tsx

# Or go back to your last commit entirely
git reset --hard HEAD

A good rhythm: commit after every completed sub-task — after the agent finishes a component, after you approve a change, before you try something risky. Each commit is a rollback point and a natural checkpoint in your session.

Set up a repo in under a minute at github.com/new, then connect your local project (Section 8 covers this in context).

7. Creating Your Project

Most agentic prototyping projects start from a framework starter, not a blank folder. For a design-first workflow, Next.js is the most common choice — it's what ShadCN, Vercel, and most component libraries are built around.

# Scaffold a new Next.js project with TypeScript and Tailwind
npx create-next-app@latest my-prototype --typescript --tailwind

cd my-prototype

You'll be asked a few setup questions (App Router, src/ directory, import alias) — the defaults are fine for prototyping.

Connect it to GitHub:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/your-username/my-prototype.git
git push -u origin main

A quick note on repo structure so it's not intimidating:

app/ or src/app/ — your pages and routes
components/ — reusable UI pieces (this is where ShadCN components land)
public/ — static assets like images and icons
package.json — your project's dependency list
CLAUDE.md or AGENTS.md — your agent's instructions file (Section 10)

You don't need to memorize this — your agent will navigate it for you. You just need to recognize it when you see it.

8. Vercel: One-Click Publishing

Publish early. A real, shareable URL — even a rough one — builds more momentum with your team than another Figma link ever will.

Go to vercel.com and sign up with your GitHub account.
Click Add New → Project, select your repo.
Vercel auto-detects Next.js and configures the build — you don't need to touch settings.
Click Deploy.

That's it. You'll get a live URL like my-prototype.vercel.app. From here on, every time you push to main, Vercel automatically redeploys — so your shared link always reflects your latest work.

Tip: Use Vercel's preview deployments (automatic for any branch or pull request) to share in-progress variants without touching your main live link — useful when you want feedback on an experiment without disrupting what stakeholders are already looking at.

Part 3 — Building

9. Feeding Your Agent a Resource Library

Here's the single most important principle in this entire tutorial:

Don't describe the vibe — show the agent the vibe.

Agents are far better at adapting existing, real code than inventing new code from an adjective. "Make it feel premium and modern" will get you something generic. Pointing the agent at an actual component, animation, or icon set will get you something specific and good.

Components: ShadCN and design systems

ShadCN/ui is the closest thing to a default design system for agentic prototyping — it's not a component library you install as a black box, it's copy-in source code that lives directly in your project, which means your agent can read it, understand it, and modify it like any other file in your repo.

# Initialize shadcn in your project
npx shadcn@latest init

# Add a component — this drops the actual source into components/ui/
npx shadcn@latest add button card dialog

Once components exist in your project, prompt your agent to use them instead of inventing its own:

"Build a pricing card using our existing Card and Button components from components/ui. Don't create new button styles — reuse what's there."

This is the mechanism that keeps a prototype visually consistent as it grows — the agent isn't guessing at your design system, it's reading it.

If you already have a design system elsewhere (Material, Chakra, a custom internal library), the same principle applies: get the actual component source or documentation into the project, and reference it by name in your prompts.

Motion & interaction

Words are a poor medium for describing motion. "Snappy," "smooth," "playful bounce" all mean different things to different agents. Instead, point at real code:

ReactBits — a large, free library of animated React components (text effects, backgrounds, interactive UI) built with React Spring, GSAP, or Three.js. Installable via CLI, same pattern as ShadCN:

npx shadcn@latest add "https://reactbits.dev/r/component-name"

Framer Motion — for hand-rolled, custom interaction logic your agent can adapt.

Prompt pattern:

"Add the 'Fade Content' animation from ReactBits to the hero section, triggered on scroll."

Icons

Pick one icon set and stick with it — mixing icon styles is a fast way to make a prototype look unpolished. Lucide (ShadCN's default) and Heroicons are both free, consistent, and easy for agents to use correctly since they're extremely common in training data and documentation.

npm install lucide-react

"Use icons from lucide-react throughout — don't introduce a second icon library."

Adding resources to your local folder

The actual mechanic, regardless of resource type:

Components (ShadCN/ReactBits): use the CLI install command — it writes the source directly into components/ui or components/.
Icon sets: npm install the package once; the agent imports icons by name as needed.
One-off snippets or references (a code sample you found, a component from a different project): drop the file directly into a components/ or lib/ subfolder, then tell the agent it exists: "There's a reference implementation at components/reference/carousel.tsx — adapt it for our use case."

The underlying habit is the same every time: get the real thing into the repo, then reference it by path or name. An agent working from a file it can actually read will always outperform one working from your description of that file.

10. Design MD & Agent MD

Every fresh agent session starts with zero memory of your project's conventions — unless you write them down somewhere it reads automatically. That's what these two files are for.

CLAUDE.md (or AGENTS.md for cross-tool compatibility) lives in your project root and is read automatically at the start of every session. This is your agent's onboarding document:

# My Prototype

## Project Context
Next.js 15 app, TypeScript, Tailwind CSS, App Router.

## Design System
- Use ShadCN components from `components/ui` — do not create custom
  buttons, inputs, or cards from scratch.
- Icons: lucide-react only.
- Motion: Framer Motion for custom interactions, ReactBits for
  pre-built effects.

## Conventions
- Use the existing `cn()` utility for conditional classNames.
- Keep components in `components/`, pages in `app/`.
- Prefer server components unless interactivity requires "use client".

## Do Not
- Do not modify files in `components/ui` directly — these are
  vendored from shadcn.
- Do not add new dependencies without asking first.

Think of this as the file that stops the agent from reinventing your design system every single session.

A "Design MD" is a lighter, complementary file — a description of your visual language in plain terms (tone, spacing philosophy, color usage rules, voice) that you can paste into a prompt or keep in the repo as DESIGN.md. It's less about code conventions and more about the feel you want preserved as the prototype grows.

# Design Principles

- Generous whitespace — err spacious, not dense.
- One accent color, used sparingly (max 2 elements per screen).
- Copy is short and direct — no filler words in UI text.
- Motion should feel calm, not flashy — 200-300ms ease-out defaults.

Cross-tool tip: if you use both Claude Code and Codex, symlink so both tools read the same file:

ln -sfn CLAUDE.md AGENTS.md

11. Your First Prompt

This is the moment most tutorials rush — but prompt structure is where most first attempts go wrong, producing generic, "Bootstrap-soup" output instead of something that looks like your product.

A good first prompt has four parts:

What you're building — the concrete thing, not the abstract goal
What it should reference — your components, your Figma frame, your resource library
What it should include — specific sections, states, or interactions
What "done" looks like — how you'll verify it worked

Weak prompt:

"Build me a landing page for my app."

Strong prompt:

"Build a landing page for a habit-tracking app called Streak. Use our existing components from components/ui (Button, Card) and the DESIGN.md principles for tone. Include: a hero with a headline, subheadline, and CTA button; a 3-column feature section using Card components; a simple pricing section with two tiers. Use Lucide icons for feature bullets. When done, the page should run cleanly with npm run dev with no console errors."

If you're working from a Figma file with the MCP server connected:

"Build the selected frame as a page at app/page.tsx. Match the layout, spacing, and colors from the Figma design context exactly. Use our existing ShadCN components wherever they match — flag anything in the design that doesn't have a corresponding component yet."

Voice-to-text tip: this is exactly the kind of prompt that benefits from dictation — say it the way you'd explain the page to a teammate, then skim and tighten before sending.

12. Iterating

Your first prompt gets you a first draft, not a finished prototype. The real work happens in the follow-ups.

Good iteration habits:

Be specific about what changed, not just what's wrong. Instead of "the spacing feels off," say "increase the gap between the hero and feature section to roughly 96px, and reduce the card padding by about 30%."
One concern per message when precision matters. Bundling five unrelated requests into one prompt makes it harder for the agent (and you) to verify each fix landed.
Reference exact files once you know them. "In app/page.tsx, change the hero heading to 'Build better habits, one day at a time.'" is faster and more reliable than re-describing the whole page.
Commit at natural checkpoints. After each meaningfully complete change — a new section, an approved revision — commit. This also gives you a clean fallback if the next change goes sideways.
Start a fresh session when things get messy. If the agent seems to be "fighting" earlier context or making increasingly odd choices, a new session (which re-reads your CLAUDE.md from scratch) is often faster than trying to talk it back on track.

A useful mental model: you're not writing one long conversation, you're running a series of small, verifiable sprints — prompt, check the browser, commit, repeat.

Part 4 — The Designer's Feedback Loop

13. Agentation: Visual Feedback for Coding Agents

The hardest part of prompting isn't describing what you want to build — it's describing what's wrong with what already exists. "The blue button in the sidebar looks off" is exactly the kind of vague feedback that sends an agent down the wrong path.

Agentation solves this by turning visual feedback into structured, code-referencable data. It adds a small toolbar to your local prototype:

npm install agentation

import { Agentation } from 'agentation';

function App() {
  return (
    <>
      <YourApp />
      <Agentation />
    </>
  );
}

Once installed, a floating toolbar appears in the corner of your running prototype. Click any element, leave a note, and Agentation captures the class names, selectors, and component hierarchy behind it — so instead of telling the agent "the blue button in the sidebar," you're handing it .sidebar > button.primary plus your comment.

It supports two workflows:

Copy-paste mode — click, annotate, copy the structured output, paste it straight into your Claude Code or Codex session.
MCP mode (via the agentation-mcp package) — the agent reads your annotations directly and can acknowledge, question, or resolve them without any copy-pasting.

This is the closest thing to a "point and say what's wrong" workflow — the natural way designers already give feedback, translated into something the agent can act on precisely.

14. Code → Figma → Code

Sometimes the fastest edit isn't a prompt — it's just dragging something in Figma. The Figma MCP server (Section 5) works in both directions: you can pull Figma designs into code, and you can push a live running prototype into Figma as editable layers.

The round-trip workflow:

With your dev server running and the Figma MCP server connected, use your agent (or Figma's desktop app) to send the live page to Figma as native, editable layers.
Make quick visual tweaks directly in Figma — nudge spacing, swap a color, resize a component — using tools you already know intimately.
Use the Figma Dev Mode Chrome extension, or the MCP connection, to pull those changes back into your codebase: point your agent at the updated frame and ask it to apply the diff.

# Example prompt once changes are made in Figma
"Pull the latest version of the 'Hero' frame from Figma and update
app/page.tsx to match — only touch spacing and color values,
don't change the component structure."

This loop is especially useful for the kind of micro-adjustments that are painful to describe in words but trivial to do by eye — kerning, spacing rhythm, exact color matching.

15. Decision Guide: When to Prompt, When to Use Figma

This is the single most valuable judgment call in this whole workflow — and the one no one teaches. Here's a practical framework:

Situation	Use a prompt	Use Figma
Changing layout structure or logic	✅
New interaction or state (loading, error, hover)	✅
Wiring up real or mock data	✅
Precise spacing, alignment, kerning		✅
Exact color matching		✅
Trying 5 quick visual variants fast		✅
Anything involving component behavior	✅
Anything involving pixel-level feel		✅

The general rule: if you can point at it and drag it, Figma is faster. If you need to describe behavior, logic, or structure, a prompt is faster and more reliable. When in doubt, default to whichever tool lets you verify the change in under 10 seconds — that's usually your answer.

Part 5 — Leveling Up

16. Skills: What They Are and How to Use Them

Skills are reusable, packaged capabilities your agent can invoke — instead of re-explaining a repeatable task every time, you write it once and reference it by name.

A skill lives as a SKILL.md file (plus any supporting scripts) that describes: what the skill does, when to use it, and how to do it step by step. Claude Code and Codex both read these automatically when relevant to your prompt.

Where to find and install skills:

# Browse and install a skills marketplace in Claude Code
/plugin marketplace add alirezarezvani/claude-skills

# Or install a specific skill set for Codex
npx agent-skills-cli add alirezarezvani/claude-skills --agent codex

Why this matters for designers: instead of typing out "check accessibility contrast, verify consistent spacing tokens, flag any hardcoded colors" every single time, you write that once as an audit-design-system skill, and from then on you just say: "run the design system audit."*

17. Auditing Your Project With Skills

This is where skills earn their keep. A well-written audit skill turns your agent into a lightweight QA teammate that catches issues before a teammate or client does.

Example: a basic design-consistency audit prompt (or packaged as a skill):

"Audit components/ and app/ for: (1) any hardcoded hex colors that should be design tokens, (2) inconsistent spacing values that don't match our 4px/8px scale, (3) any component not using our existing Button or Card primitives, (4) missing alt text on images, (5) color contrast issues below WCAG AA. List findings by file with line numbers, don't fix automatically."

Running this as a distinct, read-only pass (rather than bundling it into a build prompt) keeps the audit honest — you see the full list of issues before deciding which to fix and in what order.

Common things worth auditing regularly:

Accessibility: contrast ratios, alt text, focus states, semantic HTML
Consistency: spacing scale adherence, color token usage, typography scale
Code health: unused components, duplicate logic, missing loading/error states

18. Troubleshooting

Your "don't panic" chapter — a few things worth knowing before you hit them for the first time.

Dev server won't start / port already in use Check the terminal output — most tools auto-increment to the next open port (3001, 3002...). If it hangs entirely, stop it (Ctrl + C) and restart with npm run dev.

Build breaks after an agent change

git diff          # see exactly what changed
git checkout -- path/to/file.tsx   # revert just that file

If the whole thing is a mess:

git reset --hard HEAD    # back to your last commit

This is exactly why Section 6's "commit often" habit pays off here.

Agent edits the wrong file or over-corrects Usually a sign of an ambiguous prompt. Instead of "clean up the hero section," be specific: "in app/page.tsx, only change the heading text and font size — don't touch layout or spacing."

Secrets accidentally exposed Never paste real API keys into a prompt or commit them directly. Keep them in a .env.local file and confirm it's listed in .gitignore before your first commit — Next.js excludes .env*.local by default, but always double-check git status before pushing.

Session feels "stuck" or keeps making the same mistake Start a fresh session. A clean context that re-reads your CLAUDE.md from scratch often resolves this faster than continuing to correct within the same thread.

19. Where to Go Next

You now have the full loop: setup, resource library, first prompt, iteration, Figma round-trips, and audits. A few directions to go from here:

Go deeper on skills — build a personal library of skills for your most repeated tasks (design audits, component scaffolding, states generation)
Explore subagents (Claude Code) — delegate parallel tasks, like building three page variants simultaneously
Join the communities around each tool — Claude Code and Codex both have active Discord/GitHub communities sharing prompt patterns and skills
Push a real prototype in front of real users — the entire point of this workflow is speed to validation; don't let polish delay that

The fastest way to get fluent is the same as with any tool: pick a real idea you actually want to build, and build it end to end using everything in this guide.