DESIGN.md, Design Tokens, Figma or Screenshots: What Should You Give Your AI Coder?

If you are building a UI with an AI coding agent, you have a choice about how to tell it what the thing should look like. There are about six options in common use. They are not interchangeable, and most of the frustration I see comes from picking one that cannot do the job being asked of it.

Here is what each is genuinely good at.

Figma

Good at: being the source of truth for a design that a person actually designed. If a designer has produced screens, this is where the decisions live, and nothing else you hand the agent will be as complete.

Where it falls short: the agent generally cannot read it. Some tools can pull a Figma file through the API, and when that works it works well, but you are then dealing with whatever structure the file happens to have. A file where everything is a named component with bound variables exports cleanly. A file where the designer used raw hex values on loose frames, which is most files, exports as a pile of absolutely positioned rectangles.

The deeper mismatch is that Figma describes screens and code needs rules. A Figma file tells you this button is 44px tall with 24px of horizontal padding. It does not tell you that every button is, or that 44px is a system value rather than a one-off on that screen.

Use it when: a designer is involved and the file is componentised.

Screenshots

Good at: conveying mood, fast. One image gets you light or dark, dense or airy, serious or playful, and vision models read them well. For "make it feel like this", nothing is quicker.

Where it falls short: it is a rendering, not a specification. You cannot recover exact values from pixels. Is that heading 44px or 48px? Is the tracking negative or default? Which of the four greys is the body colour and which is a border? The agent approximates, and approximations accumulate: 40px instead of 44px, #6B7280 instead of #5C6270. Each is invisible. Together they are why the result looks nearly like the reference.

Screenshots also say nothing about states or breakpoints. No hover, no focus, no disabled, no mobile.

Use it when: you are establishing direction early, or correcting something specific. Pair it with values rather than relying on it alone.

Design tokens

Good at: being exact and machine-readable. A token file is unambiguous about what color.primary.500 is, and if you already have one, use it.

Where it falls short: tokens are a vocabulary, not a grammar. They tell an agent that color.accent.600 exists. They do not tell it that the accent should appear once per screen, on the primary action, and never as a border.

That gap produces a specific failure: technically correct, aesthetically wrong. Every value comes from the token file, and the page still looks off, because the agent used your accent eleven times.

Token names also tend to describe hue rather than job. blue-600 does not tell you what blue-600 is for. primary does.

Use it when: you have them. Add the usage rules separately.

Component libraries

Good at: guaranteeing consistency for anything they cover. If the agent is composing from your existing <Button>, it cannot get the button wrong. This is the strongest option available and it is underrated.

Where it falls short: it only covers what exists. The moment the agent needs a layout you have not built, it improvises, and the improvised part will not match. Page-level composition, meaning how much space sits between sections and what the heading hierarchy is, is usually not in the library at all, and that is a large share of what makes a page look coherent.

Use it when: you have one. It handles components; you still need to answer layout and hierarchy.

One-off prompts

Good at: small corrections. "Make the heading larger and tighten the tracking" is a perfectly good instruction and you should keep using it.

Where it falls short: it evaporates. This is the single most common problem and it is not really about design at all.

You spend twenty minutes getting the homepage right. Every correction lives in that conversation. Then you open a new session for the pricing page and the agent knows none of it. So you correct it again. Then again for settings. Six pages later, each one carries whichever subset of your preferences you remembered to restate that day, and the product looks like six people built it.

Use it when: iterating within a session. Never as the place decisions live.

DESIGN.md

The idea is a markdown file in the repo that states the design decisions, which the agent reads as context on every task.

Good at: persistence and role naming. It survives the conversation, and it can say things the other formats structurally cannot:

colors:
  primary: "#FF4F00"   # the one accent — primary actions only
  hairline: "#C5C0B1"  # 1px borders and dividers

That comment is the design decision. A token file has the hex; a screenshot has the pixels; only prose can carry the constraint. It can also hold the negative rules, which matter more than people expect: elevation is surface colour, not shadow, no gradients, one primary action per view.

Where it falls short: it is text, so nothing enforces it. Drift is possible in a way it is not with a component library. It is also only as good as what you put in. A vague file produces vague output, same as a vague prompt. And for genuinely visual decisions, prose is worse than an image; you would not describe an illustration style in markdown.

Use it when: you are working with an agent across more than one session, which is most of the time.

The short version

The pattern in that table is that no single row is complete, and the column most often missing is the third one.

What I would actually do

If you have a component library, use it, and add a short file covering layout, hierarchy and the negative rules it does not encode.

If you have design tokens, use them, and add the usage rules beside them.

If you have neither, which is where most people building with an agent are, write the file. Fifteen values and five prohibitions gets you most of the way, and there is a walkthrough here if you want a starting shape.

And use screenshots throughout, for direction. They are good at the thing they are good at.

The reason to keep it in a file rather than a prompt has nothing to do with the format being clever. It is just that a file is still there tomorrow. If you want to skip writing one by hand, DesignMD generates it from a site whose visual language already works. But the file existing matters more than where it came from.