Claude Code builds better UI when you treat it like a capable engineer with no design context. Give it a specific brief, show it what good looks like, write down the rules it must follow, and give it a way to see what it built. Most weak output comes from skipping one of those four steps, not from the model being unable to do better.
This guide walks through each step with prompts you can adapt.
Why the first attempt usually looks average
Ask for “a settings page” and you get the most likely settings page: a centred column, stacked cards, default spacing and a safe font. Anthropic describes this as distributional convergence. Without direction, the model reaches for the patterns it has seen most often.
That isn’t a bug you can prompt away with adjectives. “Modern”, “clean” and “premium” describe almost every interface ever made, so they add very little information. What moves the result is specific context: who uses the screen, what matters most on it, what it should look and feel like, and what it must never do. We cover the causes in more depth in why AI-generated interfaces look generic.
1. Write a brief, not a request
A good UI brief for Claude Code is short and concrete. It names the user, the job the screen does, the content it holds and the hierarchy you want. It also names the things you don’t want, because those are often the defaults you’ll get otherwise. For reusable templates, see how to write a design brief for AI coding agents.
Build the billing page in app/settings/billing.
Who: workspace admins checking costs, usually on desktop.
Job: see the current plan, this month's usage and the next invoice
at a glance, then change plan or download past invoices.
Hierarchy:
1. Next invoice amount and date
2. Usage against plan limits
3. Plan details and the change-plan action
4. Invoice history (table)
Constraints:
- Use our existing components in components/ui and tokens in
globals.css. Don't add new colours or font sizes.
- No cards inside cards. No gradient backgrounds.
- Dense but readable: 14px body, tabular numbers for amounts.
- Include empty, loading and error states for invoice history.If you’re unsure what the page should be, start in plan mode. Press Shift+Tab until the status bar shows plan mode, and Claude Code reads and proposes without editing files. The Claude Code best practices recommend exploring and planning before coding for changes that touch several files or where the approach isn’t clear.
2. Show it references, and say what to take from them
Claude Code accepts images. You can paste a screenshot, drag one into the terminal or give it a file path, as described in the common workflows guide. A reference is far more precise than a description of a style.
The mistake is pasting an image with no explanation. A screenshot contains hundreds of decisions, and the model can’t tell which ones you care about. Say what to extract:
[screenshot: linear-issue-list.png]
Use this for density and type hierarchy only: row height, how
metadata is muted, and how little chrome there is around the list.
Ignore its colours and icons. Our palette and icon set stay as they are.Our guide to giving Claude Code visual design references covers this in detail, including how to stop references from filling the context window.
3. Put the rules where they persist
Anything you’d repeat in every prompt belongs in your project’s CLAUDE.md. Claude Code loads it at the start of every session. The memory documentation recommends keeping each file under about 200 lines and writing instructions that are concrete enough to verify, because Claude treats them as context rather than enforced configuration.
## UI rules
- Build with components from components/ui. Check there before creating one.
- Colours, radii and spacing come from the tokens in app/globals.css.
Never hard-code hex values or pixel spacing outside the scale.
- Body text is 14px/20px. Page titles are 24px/32px, weight 600.
- One primary action per view. Secondary actions use the ghost button.
- Every list or table has empty, loading and error states.Rules that only apply to part of the codebase can live in .claude/rules/ with a paths field, so they load only when Claude works on matching files. If your team has a component library and tokens, making Claude Code follow your design system goes further.
4. Give Claude Code a way to see the result
Claude stops when the work looks done, and without a visual check “looks done” means the code compiles. The best practices guide makes this the first recommendation: give Claude a check it can run, such as a screenshot compared against a design.
For UI work that means a running dev server and a browser Claude can control. Claude Code can connect to Chrome through the Claude in Chrome extension (start it with claude --chrome), or you can use a Playwright-based setup. Then ask for the loop explicitly:
Run the dev server and open localhost:3000/settings/billing.
Take screenshots at 1440px and 390px wide. Compare them with the
reference and the brief above. List the differences, fix them,
and screenshot again. Show me the final screenshots.Asking for the screenshots as evidence matters. Reviewing two images is faster than re-running everything yourself, and it stops “done” from being an unverified claim.
5. Review like a designer, then iterate narrowly
When you review the result, judge it against the brief rather than your general impression. Check the order of importance first, then spacing and alignment, then type, then colour and detail. Fix one layer at a time with specific instructions:
- “The usage meter is competing with the invoice amount. Reduce it to body size and move it below.”
- “Spacing between sections is 24px and within sections is 20px. Make sections 40px so the groups read clearly.”
- “The table rows are 56px. Bring them to 44px and right-align the amount column.”
If you’ve corrected the same thing twice, the session is cluttered with failed attempts. Run /clear and restart with a better brief that includes what you learned. The guide to improving AI-generated UI without rebuilding it has a full review checklist.
Make it reusable
The brief, references and rules above are your creative direction, and most of it doesn’t change from screen to screen. Writing it down once, somewhere your agent can reach, is what turns better UI from a lucky session into a habit. That’s the idea behind giving AI coding agents your design taste.
This is the problem we’re building Attuna to solve. You save references with notes on what you like about them, write the principles you want followed, and Claude Code can ask for the direction that applies to a task over MCP.
The short version
- Brief the screen: user, job, hierarchy, constraints and things to avoid.
- Show references and say exactly what to take from each one.
- Keep lasting rules in CLAUDE.md, short and specific.
- Make Claude screenshot its work and compare it before calling it done.
- Review in layers and give narrow, measurable corrections.