tommygeoco_ui-audit/references/23-patterns-visual-hierarchy.md

Patterns: Visual Hierarchy

Patterns for guiding attention and creating clear content structure.

---

What is Visual Hierarchy?

The arrangement of elements to show relative importance. Users should instantly understand what's most important without reading everything.

Core principle: Design tells users where to look. Make it intentional.

---

Typography Hierarchy

What: Using type size, weight, and style to establish importance.

Hierarchy Levels

Level	Purpose	Typical Treatment
Display	Hero content, page title	Largest, boldest
H1	Page heading	Large, bold
H2	Section heading	Medium-large, semibold
H3	Subsection	Medium, semibold
Body	Primary content	Base size, regular
Secondary	Supporting text	Smaller, lighter color
Caption	Labels, metadata	Smallest, light

Implementation Guidelines

DO:

• 2:1 ratio minimum between heading levels
• Consistent application across pages
• Weight AND size differences (not just one)
• Appropriate line height per level
• Limit to 4-5 distinct levels

DON'T:

• Use more than 2 typefaces
• Make headings barely bigger than body
• Use color alone for hierarchy
• Skip heading levels (H1 → H3)
• Use all caps for long text

Type Scale Example

Display:  48px / Bold
H1:       36px / Bold  
H2:       24px / Semibold
H3:       20px / Semibold
Body:     16px / Regular
Small:    14px / Regular
Caption:  12px / Regular

---

Color Hierarchy

What: Using color intensity, saturation, and contrast to direct attention.

Hierarchy Through Color

Element	Color Treatment
Primary action	Brand color, high saturation
Secondary action	Muted/outline variant
Primary text	Darkest (near black)
Secondary text	Medium gray
Disabled	Light gray
Destructive	Red family
Success	Green family

Implementation Guidelines

DO:

• High contrast for primary elements
• Reserve saturated colors for actions/emphasis
• Use color consistently (same action = same color)
• Ensure 4.5:1 contrast ratio minimum
• Test with color blindness simulators

DON'T:

• Use more than 3-4 colors for UI elements
• Use red for non-destructive actions
• Rely on color alone to convey meaning
• Make secondary elements more colorful than primary
• Use low contrast for important elements

Color Application

Primary action:    Blue-600 (saturated)
Secondary action:  Blue-100 bg + Blue-700 text
Tertiary action:   Gray-200 bg + Gray-800 text
Disabled:          Gray-100 bg + Gray-400 text

---

Whitespace Hierarchy

What: Using space to group related items and separate unrelated ones.

Principles

• More space between unrelated items
• Less space between related items
• Space increases with hierarchy level
• Consistent spacing scale throughout

Spacing Scale

4px   - Tight (icon + label)
8px   - Related elements
16px  - Related groups
24px  - Section spacing
32px  - Major section breaks
48px+ - Page-level separation

Implementation Guidelines

DO:

• Follow Law of Proximity religiously
• Use consistent spacing scale
• More space above headings than below
• Generous margins at page level
• Space proportional to importance

DON'T:

• Use arbitrary spacing values
• Cram elements together
• Use equal spacing everywhere
• Separate clearly related items
• Waste space inconsistently

---

Size Hierarchy

What: Using element size to indicate importance.

Size Principles

• Larger = more important
• Primary actions larger than secondary
• Main content larger than supporting
• Size differences should be noticeable (1.5x minimum)

Button Size Example

Large:   48px height (primary page actions)
Medium:  40px height (standard actions)
Small:   32px height (inline/secondary)
X-Small: 24px height (compact contexts)

Card Size Hierarchy

Purpose	Size
Featured	Largest, spans multiple columns
Primary	Standard size, prominent
Secondary	Smaller, supporting content
Compact	Minimal, high-density contexts

---

Proximity & Grouping

What: Using spatial relationships to show content relationships.

The 4 Gestalt Laws for Hierarchy

1. Proximity — Close items are related
2. Similarity — Similar items are related
3. Common Region — Items in same container are related
4. Connectedness — Items connected by lines are related

Application Examples

Proximity:

• Form label + input (tight spacing)
• Form group + next group (more spacing)
• Card content grouped tightly
• Cards separated from each other

Similarity:

• All navigation items styled the same
• All buttons of same importance styled the same
• All card components share style

Common Region:

• Related items in same card/container
• Form fields in fieldset
• Related actions in button group

Connectedness:

• Breadcrumbs connected by separators
• Stepper stages connected by line
• Related items connected by visual element

---

Contrast Hierarchy

What: Using contrast differences to establish visual priority.

Contrast Types

Type	Application
Color contrast	Light/dark, saturated/muted
Size contrast	Large/small
Weight contrast	Bold/regular
Density contrast	Busy/sparse areas
Motion contrast	Static/animated

Creating Focus

High contrast for:

• Primary CTAs
• Important information
• Error states
• Current/active states

Low contrast for:

• Secondary actions
• Supporting text
• Disabled states
• Background elements

---

Position Hierarchy

What: Leveraging natural reading patterns and expectations.

Reading Patterns

F-Pattern (text-heavy pages):

• Users scan horizontally at top
• Then vertically down left side
• Place key content along the F

Z-Pattern (sparse pages):

• Users scan top left to right
• Then diagonally to bottom left
• Then across bottom
• Place CTAs at end of Z

Gutenberg Diagram:

• Top left: Primary optical area (high attention)
• Top right: Strong fallow area
• Bottom left: Weak fallow area
• Bottom right: Terminal area (natural end, place CTAs)

Position Guidelines

DO:

• Most important content top-left
• Primary actions top-right or bottom-right
• Navigation where expected (top, left)
• CTAs at natural stopping points

DON'T:

• Bury primary actions bottom-left
• Place important info in weak fallow area
• Violate expectations without reason
• Scatter actions unpredictably

---

Hierarchy Patterns by Component

Cards

1. Image/media — Visual hook, top
2. Title — Primary info, prominent
3. Description — Supporting context
4. Metadata — Secondary info, muted
5. Actions — Clear CTA, bottom

Tables

1. Header row — Bold, sticky
2. Key column — Left-most, often linked
3. Data columns — Clear alignment
4. Actions column — Right side
5. Pagination — Below, muted

Forms

1. Form title — Clear purpose
2. Section headers — Group labels
3. Labels — Above fields, clear
4. Inputs — Prominent
5. Help text — Below fields, muted
6. Primary action — Emphasized
7. Secondary action — De-emphasized

Pages

1. Page title — Clear orientation
2. Primary content — Center/prominent
3. Supporting content — Secondary/sidebar
4. Navigation — Consistent location
5. Actions — Contextual, accessible

---

Hierarchy Audit

Element	Clear Hierarchy?
☐ Headings distinct from body
☐ Primary action obvious
☐ Related items grouped
☐ Unrelated items separated
☐ Reading flow logical
☐ Most important content prominent
☐ Consistent hierarchy across pages