Design handoff for AI agents: what a coding agent needs

A design handoff for AI agents is the package a coding agent reads before it writes interface code: one reference for each screen state, the design tokens as code, real content, the actions that move between states, the files it may change, and the checks that define done. A human developer asks when something is missing. An agent fills the gap with a plausible default, so everything you leave out comes back as a guess.

This guide lists what to include, how to write it so an agent can use it, and a template you can paste into your chat.

Why an agent needs a different handoff

A handoff to a developer works because the developer brings context: they know the product, they remember last week’s discussion, and they message the designer when a state is missing. A coding agent starts each session with the repository, its instructions and whatever you give it. Three habits follow from that.

• It reads literally. A 13 px gap in a mockup becomes gap: 13px, even if your spacing scale has no 13.
• It fills gaps silently. No error state in the design means the agent invents one, or skips it.
• It follows what it can see. If the reference shows a hardcoded color and the rule about tokens lives in someone’s head, the hardcoded color wins.

The fix is not a longer brief. It is a handoff where each item is explicit, checkable and close to code.

What to include, item by item

Item	What to give the agent	What happens without it
Screen states	One reference per state: default, empty, loading, error, long content, modal open	The agent builds the happy path and improvises the rest
Tokens	The names of your CSS variables or theme values, and the rule to use them	Raw hex values and pixel sizes spread through components
Content	Real labels, realistic data, the longest name you expect	Layouts that break on real text
Behavior	The action that leads from each state to the next: “Click Save”, “Submit invalid form”	Missing transitions, dead buttons
Scope	The route, the files and components to change, and what must not change	Edits in shared components you did not expect
Constraints	Viewport sizes, breakpoints, accessibility needs	A layout that works at one width only
Definition of done	The commands to run and what to compare	“Done” means “it compiles”

States cause the most trouble, because a static design usually shows one of them. The UI states checklist lists the states worth drawing for each kind of screen.

Give references the agent can read

An agent can look at an image, but it has to estimate every value from pixels: is that padding 16 or 20, is that gray a token or a one-off? A reference written as HTML and CSS gives the exact values, the text as text, and the structure of the page. The agent reads it like code, because it is code.

Whatever the format, check three things before you hand it over:

1. Each state is separate. One file or frame per state, named after it (“Invoices · empty”), not a single artboard with notes pointing everywhere.
2. Values match your system. If the design uses a spacing of 12, your scale has a 12. If not, fix the design or add the token before the agent has to decide.
3. Sample data is realistic. Real labels, a long customer name, a price with four digits, an empty list.

If your team is still choosing a format, HTML prototypes or Figma files compares the two for developer-led teams.

Write the rules once, in the repository

Rules you repeat in every chat get forgotten in some of them. Put the stable ones in the repository, where the agent reads them every time. Claude Code loads a project CLAUDE.md (at the root or in .claude/) at the start of every session, and rule files in .claude/rules/ can carry a paths field so they load only when the agent works on matching files. The Claude Code memory documentation recommends short, specific files: under 200 lines, with instructions concrete enough to verify.

A UI section might look like this:

## UI rules
- Tokens live in src/styles/tokens.css. Use var(--...) for colors, spacing,
  radius and font sizes. No hex values or px sizes in components.
- Reuse components from src/components/ui before creating one. Ask before adding one.
- Every screen handles its empty, loading and error states.
- Run npm run typecheck, npm run lint and npm test before you report a UI change as done.

Keep the handoff itself for what changes from one task to the next: the screens, the states, the content. How to write tokens so an agent uses them correctly is covered in design tokens an AI coding agent can follow.

A handoff template to paste into your chat

Implement the new Invoices screen from the prototype.

References, one per state
- default: <link or file>
- empty (no invoice yet): <link or file>
- loading: <link or file>
- error (the API fails): <link or file>

Flow
- default: "Click New invoice" opens the new invoice modal
- error: "Click Retry" reloads the list

Scope
- Route /invoices, files under src/features/invoices/
- Do not change src/components/ui/ without asking

Rules
- Use the tokens in src/styles/tokens.css and the existing components
- Real labels from the prototype; data comes from GET /api/invoices

Done when
- Every state above can be opened and matches its reference at 1440 x 900
- Type checks, lint and tests pass
- You list the files changed and anything you could not match

Ask the agent to restate its plan before it edits anything. A plan that lists the files and components it will touch is the cheapest place to catch a misunderstanding.

Decide what “done” means before the agent starts

An agent reports success when its own checks pass, so those checks are your definition of done. Put them in the handoff:

• Automated checks: type checking, lint, tests, a production build.
• Visual comparison: each state opened at the same viewport as its reference, side by side.
• Coverage of states: every state in the handoff can be reached, by route, by props or by a test fixture.
• A written report: files changed, checks run, and any difference from the reference, with the reason.

The report matters most. “I could not match the chart colors because the tokens do not include them” is exactly what you want to read before merging, not after.

Where agentappbuilder fits

agentappbuilder turns several items of this list into structure. Your agent prototypes each screen as linked HTML frames, one frame per state, with the user actions as labelled links between them. Each frame has its own URL. When you paste it in your chat, the agent reads the frame’s HTML, its description and an optional contract, a JSON description of what the code must honor for that state. See concepts for frames, versions and links.

When you edit a frame yourself on the canvas, the new version carries the exact list of your edits: element, property, value before and after. When you say “apply”, the agent codes each frame whose active version differs from the implemented one, runs your app’s checks and reports what it implemented. Working with your agent gives the prompt for each step.

Summary

An agent does well with a handoff that leaves nothing to guess: every state as its own reference, tokens as code, real content, named actions, a clear scope and a definition of done. Write the stable rules once in the repository, keep the per-task handoff short, and ask for a plan before the work and a report after it.