Re-prompting "make it look better" rarely works, because the model cannot tell which thing you dislike either. Naming the failure does work. "Fix the hierarchy collapse: one primary button per section, body text at a third of the heading size" gets you a better screen on the first try.
This site went through the same list tonight. The pages had drifted into competing type sizes and hundreds of low-contrast lines. The fix was one type scale in a single tokens file, two typefaces, and roughly 450 contrast corrections. Every item below showed up somewhere.
The ten failure modes
- Hierarchy collapse. Everything looks equally important. Make headings at least three times the body size, use one primary button per section, and push weights apart (regular against bold, nothing in between).
- Spacing chaos. Each piece looks fine and the whole feels off. Put every gap on one grid (8px steps), use
gapinstead of scattered margins, and keep the space inside a group smaller than the space between groups. - Border overload. It looks like a wireframe. Take borders off cards and containers, use a soft shadow or a faint ring, and keep real borders for inputs, tables and dividers.
- The generic font. It looks AI-made at a glance. Swap the default sans for something with a voice (this site uses Fraunces with JetBrains Mono) and make the weight contrast between headings and body extreme.
- No color system. Colors clash or wander. Define every color once as a variable, split roughly 60-30-10 between background, surface and accent, pick one accent, and drop the blue-to-purple gradient.
- Missing states. It looks fine in a screenshot and dead in the hand. Give every control hover, focus, pressed and disabled styles, and design the loading, empty and error views.
- Responsive blindness. Great at one width, broken at the rest. Build for the phone first, turn tables into cards on narrow screens, and look at 375, 768, 1024 and 1440 pixels before you ship.
- Wrong component. It works and it is clunky: a modal that only displays text, a dropdown for three options, an error in a toast. Use the tables below.
- Density mismatch. Cramped where it should breathe, or sparse where people need data. Dashboards run tight; landing pages run generous. Match the density to how the screen gets used.
- Accessibility gaps. Fine to look at and unusable by keyboard or screen reader. Visible focus rings, contrast of at least 4.5:1 for body text, real buttons and headings instead of styled divs, and labels on icon-only buttons.
Picking the container
| The task | Use |
|---|---|
| Must finish before continuing, or confirm something destructive | Modal |
| Needs to see the page underneath while working; filters; settings | Drawer |
| Many fields, worth a bookmark, needs the back button | Its own page |
| Extra detail about one item | Inline expansion |
Modals slow people down on purpose. Use them to stop mistakes and never to show content.
Picking the selector
| Options | Use |
|---|---|
| 2, on or off | Switch |
| 2 to 5, pick one | Radio group or segmented control |
| 5 to 10 | Dropdown, or radios if there is room |
| 10 or more, a known list | Dropdown with search |
| Hundreds (countries, time zones) | Type-ahead field, never a long dropdown |
| Several from up to 10 | Checkboxes |
If every option fits on screen without scrolling, show them all.
Picking the display
| The data | Use |
|---|---|
| Compare across rows, sort, filter, act in bulk | Table |
| Visual items browsed one at a time | Cards |
| Two to four plain attributes, scanned in order | List |
| A table on a phone | Cards with the key fields, tap for the rest |
| Stages of a pipeline | Board |
| Events in time | Timeline |
Before you call it done
states.md — copy this
# State check: [screen name] [ ] Default resting look [ ] Hover pointer feedback on everything clickable [ ] Focus a visible ring when you Tab to it [ ] Pressed feedback on click or tap [ ] Disabled dimmed, not clickable, still readable [ ] Loading a skeleton of the real layout [ ] Empty a line of guidance and the first action [ ] Error next to the thing that failed, words plus icon [ ] Success a quiet confirmation [ ] Widths 375, 768, 1440: nothing spills off the side
Paste the failure mode names and this checklist into the conversation with your AI before it builds the next screen. It will make fewer of these mistakes, and when it does make one you will both have a name for it.
Next door
The brief that should come before any screen is in Working With Claude. If you want a starting point that already passes most of this list, Portfolio in a Box is this site's stylesheet, packaged.