The prompts that get better UI out of Claude Code share three traits: they name the decision you want made, they give the constraint that rules out the default, and they ask for evidence back. Below is a library of prompts organised by the job in front of you, from briefing a new screen to the final polish pass. Copy them, replace the bracketed parts, and keep the ones that work in a skill or your project instructions.
If you want the reasoning behind this approach rather than the prompts themselves, start with how to make Claude Code build better UI.
How to use this library
- One job per prompt. Layout, type and states in a single request produce averaged results. Run them as separate passes.
- Say what must not change. Most damage in iteration comes from the agent “improving” parts you were happy with.
- Ask for screenshots. Claude Code’s best practices recommend giving Claude a check it can run, such as a screenshot compared against a design.
- Plan first for anything structural. Press
Shift+Tabinto plan mode so Claude proposes before it edits.
1. Briefing a new screen
Use when the screen doesn’t exist yet. The point is to make the hierarchy decision before the layout one.
Plan the [screen] at [path]. Don't write code yet.
User: [who, on what device, how often].
Their first question on this screen: "[question]".
Rank the content: what must be seen first, second, third, and what
can be one click away. Then propose a layout for desktop and for
390px wide, naming the components from [component folder] you'd use.For full templates (dashboard, marketing page, mobile), see how to write a design brief for AI coding agents.
2. Fixing hierarchy
Use when everything on the screen has the same weight.
On this page the most important thing is [element]. Right now
[competing element] draws the eye first. Rebalance using weight,
size and position only. Keep the colours and components as they
are. Show me before and after screenshots at 1440px.3. Tightening spacing
Use when groups don’t read as groups.
Audit spacing on [page]. List every gap that isn't on our scale
([4, 8, 12, 16, 24, 32, 48]) with file and line. Then apply one rule:
gaps inside a group are smaller than gaps between groups. Section to
section is [48]. Don't touch typography.4. Typography pass
Use when the type looks default. Typography deserves its own pass; see how to improve typography in AI-generated websites for the details behind this prompt.
List every distinct text style on [page]: size, weight, line height,
tracking, colour, and where it's used. Merge anything that differs
by less than one step on our scale. Body copy stays at [size] with a
line length of roughly 60 to 75 characters. Report the before and
after style count.5. Adding the missing states
Use on any list, table or async view. Generated screens usually show only the populated happy path.
Add these states to [component] and render each one on a temporary
route so I can review them: empty (first use, with one next step),
loading (skeletons matching the real layout), error (with retry),
long content (a 60-character name), and 1 versus 500 items.6. Responsive pass
Use after the desktop layout is approved. Decisions per pattern are covered in making AI-generated UI responsive.
Make [page] work from 360px. Keep the desktop layout exactly as it
is. Tables become [list / priority columns]; the sidebar becomes
[drawer / bottom bar]; actions beyond the primary one move into an
overflow menu. No page-level horizontal scroll. Screenshot at 360,
390, 768 and 1280.7. Matching a reference
Use when you have one clear reference. For several at once, see how to combine multiple design references.
[attach reference]
Take only the [density / hierarchy / composition] from this
reference. Ignore its colours, fonts, icons and copy; those come from
our tokens and components. Build [section], then compare a screenshot
with the reference for that quality only and list the differences.8. Critique before changing anything
Use when something feels off and you can’t say why. Asking for a critique first keeps Claude from making changes you haven’t agreed to.
Act as a design reviewer. Screenshot [page] at 1440 and 390. Give me
the five most important problems, ranked, each with what you see,
why it matters for [user], and a specific fix. Don't edit any files.9. Removing defaults
Use when the page looks like every other generated page. The list of usual suspects is in why AI-generated interfaces look generic.
List anything on [page] that's there by default rather than by
decision: gradients, icon-plus-title cards, centred hero layouts,
decorative shadows, accent colour used on non-actions. For each,
propose removing it or replacing it with something specific to
[product]. Wait for my choice before changing anything.10. Polish pass
Use last, on an approved layout.
Polish [page] without changing layout or content:
- align every element to the same left edges
- consistent corner radii by element type
- hover, focus and pressed states on every interactive element
- truncation instead of wrapping where a row must stay one line
- numbers in tables use tabular figures and are right-aligned
Show a screenshot of each change.11. Accessibility check
Use before calling any screen finished. The full checklist is in how to make AI-generated interfaces accessible.
Tab through [page] in the browser and report the focus order. List
interactive elements without an accessible name, inputs without a
visible label, text below 4.5:1 contrast, and targets under 24 by 24
CSS pixels. Fix nothing yet.12. Capturing what you learned
Use at the end of a session, so the next one starts further ahead.
From this session, list the corrections I made more than once.
Turn each into a one-line rule (prefer or avoid) that would have
prevented it. Propose where each rule belongs: CLAUDE.md, a path
rule in .claude/rules/, or a skill.Turn the prompts you reuse into tools
Any prompt you send more than twice is a candidate for a skill. Claude Code’s skills load only when used and can be called with /skill-name, so prompts 8 and 11 make good /ui-critique and /a11y-check commands. Rules from prompt 12 belong in your CLAUDE.md.
The other half of a reusable setup is context: the references and preferences these prompts keep pointing at. Attuna, in private beta, keeps them in a project your agent reads over MCP, so “take the density from the reference” has a reference to take it from.