| name | hierarchy |
| description | Use when a UI feels noisy, when nothing stands out, when buttons/nav/sections all compete for attention, or when you need to decide which element is primary vs secondary vs tertiary. Covers emphasis through weight and color (not just size), the grey-on-color trap, de-emphasizing competitors, label minimization, weight/contrast counterbalance, and action hierarchy. |
Visual Hierarchy
When to use this skill
- A page feels noisy or like everything is shouting equally.
- Buttons, nav items, or content sections aren't clearly differentiated by importance.
- A "primary" element doesn't feel primary even though it's been styled aggressively.
- Grey text is being placed on a colored background and looks washed out.
- An audit found contrast / emphasis / "no clear focal point" issues.
Core idea
Most "designed-feeling" UIs achieve their polish through deliberate emphasis and de-emphasis of relative importance — not through styling tricks. Hierarchy is the tool; size, weight, color, contrast, and spacing are the levers.
Principles
1. Don't carry hierarchy on font-size alone. Body text ends up too large and supporting text ends up too small. Use weight and color in parallel:
- 2 weights (normal 400–500, emphasis 600–700) cover most UI work.
- 3 colors (dark for primary, mid-grey for secondary, light grey for tertiary).
- Avoid weights below 400 in UI — they collapse at small sizes.
2. Grey text breaks on colored backgrounds. What looks "softer" on white is just lower contrast; on a colored background that grey looks washed out, often disabled. Don't fix it with white-text-with-opacity — transparency leaks the background through, especially over images or patterns. Hand-pick a new color: keep the bg's hue, raise saturation/lightness until contrast feels right.
3. Emphasize by de-emphasizing. When a primary element won't pop, soften the things competing with it before cranking the primary harder. Inactive nav items go softer; the sidebar drops its background tint; supporting copy fades.
4. Labels are a last resort. Skip the label when format implies it (jane@example.com, $19.99, (555) 123-4567) or context implies it (a job title under a name). When a label is needed, fold it into the value: 12 left in stock beats In stock: 12. When you must keep a real label, treat it as supporting (smaller, lighter, or both). Exception: dense spec sheets where users scan for label keywords — emphasize the label, not the value.
5. Visual hierarchy ≠ document hierarchy. Default browser styles push you toward big <h1>s. Pick the semantic element for accessibility, then style independently. Many "section titles" in apps are really labels; make them small. Visually hiding semantic headings is fine when content is self-explanatory.
6. Balance weight against contrast. Bold text covers more pixels than regular — it draws the eye through area, not just darkness. Use this as a counterbalance:
- Heavy elements (icons, especially solid ones; bold text) often need contrast lowered (softer color).
- Low-contrast elements (a 1px hairline border that looks harsh dark but disappears when faded) can be made 2px wider with a softer color — same visual presence, less aggression.
7. Action hierarchy is real, not just semantic. Every page has a pyramid of actions:
- Primary: solid high-contrast background. Usually one per page.
- Secondary: outline or low-contrast background.
- Tertiary: styled like a link.
Destructive actions are not automatically big-and-red. If "delete" isn't the primary action on the page, give it secondary or tertiary treatment, then make it the big-red primary inside the confirmation dialog.
Quick reference
- 2 font weights, 3 grey shades cover most UIs.
- Before amplifying the primary, ask: what can I make less prominent?
- Pyramid every page: 1 primary action, a few secondary, scattered tertiary.
- Grey text on colored bg → re-pick the color in the bg's hue, never just opacity.
- Solid icon next to text? The icon is heavy — soften its color.
Attribution
Heuristics distilled from Refactoring UI by Adam Wathan & Steve Schoger (https://refactoringui.com). Independent skill package; not affiliated with or endorsed by the authors.
