hierarchy

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 ([e-mail], $19.99, [phone]) 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.