JIMDRURY.
Jim Drury
An AGENTS.md file (how to build: prefer our patterns, don't invent APIs, run the checks) and a DESIGN.md file (colour tokens with roles, a four-step type scale, radius 8 and a Dont list striking out gradients, stacked shadows, glassmorphism and a second primary button) both feed an agent, which produces a plain checkout screen with one flat Pay now button; a crossed-out 'make it look less AI' prompt sits to one side
agents

AGENTS.md tells them how to build. DESIGN.md tells them how it should look.

5 MIN READ

I've lost count of the times an agent has shipped a feature that works and somehow looks like it was designed by a committee of default Tailwind presets.

Clean TypeScript. Sensible component names. Then the page opens and it's default blue, a soft shadow on everything that moves, and a gradient that nobody asked for. The model didnt forget how to write CSS. It just had no idea what the product was supposed to look like.

Your agent writes clean code and ugly UI. That gap is a missing spec, not a missing model.

- Victor (@victor_explore), on agents, clean code, and ugly UI

That line from @victor_explore landed harder than most of the launch posts this week. Same week, @sitin_dev put the split into seven words I've been wanting:

AGENTS.md tells AI how to build. DESIGN.md tells AI how it should look.

- sitinDev (@sitin_dev), on AGENTS.md vs DESIGN.md

We've been writing half a playbook

I've been loud about AGENTS.md for months (see NextJS 16.2 AGENTS.md could be the ultimate AI Hack!). That file is brilliant at "prefer our patterns", "dont invent APIs", "run the checks".

What it almost never says is: this product uses these radii, this type ramp, this spacing rhythm, and for the love of all that is holy, dont invent glassmorphism because you saw it in a training set.

So the agents build correctly against the wrong visual contract. Then a human spends an afternoon stripping shadows.

A brief confession

I have absolutely sat there prompting "make it look less AI" three times in a row, as if the model would suddenly remember our brand tokens from vibes alone.

It wont. Vibes are not a design system. I knew that. I still did it. The agents will keep guessing until you give them something denser than a mood.

Design constraints are the TypeScript of UI

This is the bit that feels obvious once you say it out loud. Frontend teams already treat TypeScript as a contract the agents keep trying to break. Tokens, type scale, spacing, and a Dont list are the same idea for the pixel layer.

A DESIGN.md doesnt need to be a 40-page brand book. It needs to be readable by a coding agent before it invents a button. Colours with roles, not just hexes. Type scale. Spacing. Radius. What a primary button is allowed to look like. And the things it must not "improve".

sitin_dev's point about the Dont list is the one I keep coming back to. Agents love to "improve" UI. Improvement without a brake is how you get three shadow levels and a mystery gradient on a status pill.

Here's the boring stub I'd rather have in a repo than another round of "make it cleaner":

DESIGN.md (agent-readable stub)
# DESIGN.md
## Intent
This file is for coding agents. Read it before you invent UI.

## Tokens (roles, not vibes)
- primary: brand action colour (buttons, links)
- surface: page background
- border: hairline only, never decorative glow
- radius: 8px default, 4px for dense controls

## Type
- One sans family. Two weights. No display font for body copy.
- Scale: 14 / 16 / 20 / 28. Do not invent a fifth size mid-PR.

## Spacing
- Base 4. Prefer 8 / 16 / 24 / 40. No 13px "optical" gaps.

## Dont
- Dont add gradients unless this file already defines one
- Dont stack box-shadows to "make it pop"
- Dont invent a second primary button style
- Dont use glassmorphism, neon borders, or AI-glow cards
- Dont "improve" spacing that matches an existing screen

You can generate these files from real products (there's a whole little cottage industry of DESIGN.md exporters doing the rounds). Fine. Steal the structure. Retokenise it to your product. The value isnt the GitHub star count on somebody's awesome list. The value is an agent that stops guessing.

Where it sits next to AGENTS.md

I'm not proposing a third novel next to CLAUDE.md and AGENTS.md. Two jobs, two files.

  • AGENTS.md for how the agents should build (intent, checks, patterns)

  • DESIGN.md for how the UI should look (tokens, components, Donts)

If your teams already keep a Storyblok (or Figma) source of truth, the markdown is a projection for agents, not a second brand bible for humans to argue about in Slack. Glue the mess once. Keep the consumer boring. That's a frontend mindset applied to AI: abstract the complexity behind a contract.

And please dont stuff control flow into either file. We've covered that.

Thoughts

If your agents keep shipping competent, ugly UI, stop blaming the model for a week.

Write a DESIGN.md with tokens and a brutal Dont list. Put it next to the AGENTS.md you already trust. Then watch how much less "make it look less AI" you have to type.

The missing piece was never another prompt. It was a visual contract.

Similar Articles