Your coding agent can scaffold a working UI in seconds and still ship something that looks like every other default template. The fix is a UI.md file — a set of design rules your agent reads before it writes a single component. It’s the same idea as AGENTS.md, applied to how things look instead of how the codebase behaves.
Why your agent’s UIs all look the same
Most coding agents produce competent but generic interfaces. They reach for the same default spacing, the same button styles, the same layout grid every time, because nothing told them otherwise. The agent isn’t bad at design — it was never given a design.
That’s the gap UI.md fills. Where AGENTS.md tells your agent how your project works, a UI.md tells it how your project should look. One file, no plugins, read on every task.
What goes in a UI.md
Keep it short and opinionated. A useful UI.md covers:
- Visual language. Color palette (with hex values), typography stack, and the spacing scale you use. Concrete values beat adjectives.
- Component norms. Button sizes, rounding, default shadows, whether you use borders or fills. “Primary action is solid; secondary is outline” is a rule an agent can follow.
- Layout rules. Max content width, grid behavior, how you handle responsive breakpoints.
- Do-nots. The patterns you’ve banned — no centered modal overload, no rainbow gradients, no default placeholder avatars.
The point is constraints. An agent given zero design constraints will pick the statistically most common one. An agent given explicit rules produces something that matches your product.
How to use it with your agent
Drop UI.md at the repo root next to AGENTS.md. When you ask the agent to build or modify an interface, reference it: “Build the settings page following UI.md.” Most agents that respect AGENTS.md will pick up UI.md without special configuration.
If you use Claude Code specifically, pair it with the frontend-design skill so the agent has both the capability and the rules. The skill gives it the ability to design; the UI.md gives it your taste.
UI.md vs AGENTS.md
They’re complementary, not redundant:
| AGENTS.md | UI.md | |
|---|---|---|
| Scope | How the codebase works | How interfaces look |
| Answers | Commands, structure, conventions | Colors, spacing, components |
| Best for | Backend, refactors, navigation | Frontend, components, pages |
A repo with both tells the agent everything it needs: how to move through the code and what the result should look like when it’s done.
FAQ
Q1: Is UI.md a real standard or just a convention? It’s a convention, not a vendor standard — but it builds on the same pattern as AGENTS.md, which most major coding agents already read automatically. You define the file; the agent reads it.
Q2: Do I need both AGENTS.md and UI.md? Only if you care about both behavior and appearance. If your project is backend-only, AGENTS.md alone is enough. For anything with a UI, UI.md keeps the agent from defaulting to generic design.
Q3: Will a UI.md stop my agent from producing ugly output entirely? It dramatically reduces generic output by giving concrete constraints, but it won’t replace human design judgment on hard problems. Treat it as a baseline style guide the agent is required to follow, not a substitute for review.
Why pay $20/mo for ChatGPT, $20/mo for Claude, $20/mo for Gemini? aiFiesta gives you all of them and more for just $12/mo.