Visual Hierarchy: UI principle for coding agents

Size Isn't Everything

Don't rely solely on font size for hierarchy
Use font weight and color to create hierarchy

Font Weight:

Normal (400-500) for most text
Heavier (600-700) for emphasis
Avoid weights under 400 for UI (too hard to read at small sizes)

Color for Hierarchy:

Dark color for primary content
Grey for secondary content
Lighter grey for tertiary content

Don't Use Grey Text on Colored Backgrounds

Grey text on white works because of reduced contrast
Don't use opacity to lighten text on colored backgrounds (looks washed out)
Instead: Hand-pick a color with the same hue, adjust saturation and lightness
Maintains readability without looking faded

Emphasize by De-emphasizing

When an element needs more emphasis, try de-emphasizing competing elements instead
Soften colors of less important items
Remove background colors from competing sections
Let important content stand out by making everything else quieter

Tune the Six Emphasis Dials

Hierarchy is relative. An element is not important because it is large or colorful in isolation; it becomes important because it differs from its surroundings. Start from the screen's goal, pick the element that must lead, then tune a small number of dials:

Size: enlarge the primary message or action enough to be clearly distinct, then shrink secondary material before making the hero enormous.
Color: use accent color to attract attention, semantic color to communicate meaning, and muted color to quiet support. Color is one dial, not the default fix for every hierarchy problem.
Space: isolate the primary element with breathing room while keeping its supporting information nearby. Space can create emphasis without decoration.
Placement: reserve the first part of the scan path for the screen's purpose or status. Put the action close to the information that justifies the decision.
Visualization: turn an abstract fact into an immediately recognizable pattern, such as progress, comparison, trend, or status. A dashboard should provide an insight, not merely restyle the database schema.
Motion: use movement to reveal change, guide attention, or confirm progress. Motion that does not support the screen's goal spends attention without returning meaning.

Most strong hierarchy uses one or two leading dials and lets the others support.

Run the Blur Test

Zoom out, squint, or blur the screen until text is unreadable. Size, contrast, placement, and spacing should still reveal the intended first element and the rough scan path. If a logo, illustration, or decorative card wins instead of the screen's purpose, the hierarchy is wrong even when every component looks polished.

Run the test in context. A delivery status is scanned under time pressure; a report may support slower comparison. Prime placement and emphasis must match the user's immediate question, not a generic page template.

Diagnose Wrong, Weak, and Screaming Hierarchy

Wrong dial: the design keeps changing color when the real problem is placement, space, or an unsuitable visualization. Name what is competing before choosing a lever.
Weak dial: several tiny adjustments leave every element at nearly the same volume. Make one difference large enough to survive the blur test.
Screaming dials: size, color, shadow, and motion all peak at once. The result feels pushy, can trigger resistance, and leaves nothing truly leading. Return to a calm baseline, choose a lead, preserve clear alternatives, and quiet the rest.

Labels are a Last Resort

Avoid labels when possible:

Format can identify data ([email protected], (555) 555-5555, $19.99)
Context can identify data (seeing "Customer Support" under a name)

Combine labels and values:

"In stock: 12" → "12 left in stock"
"Bedrooms: 3" → "3 bedrooms"

When labels are needed:

Treat label as supporting content
Make label smaller, lighter weight, lower contrast
Exception: Information-dense pages where users scan for labels (specs, technical data)

Separate Visual from Document Hierarchy

Use semantic HTML (h1, h2, h3) for accessibility
Don't let semantic tags dictate visual size
Section titles often work as labels (should be small)
Style elements for visual hierarchy, not semantic meaning

Balance Weight and Contrast

Contrast compensates for weight:

Heavy elements (bold text, solid icons) naturally draw attention
Reduce contrast (soften color) to de-emphasize heavy elements
Icons next to text should be softer in color to balance

Weight compensates for contrast:

Low-contrast elements can feel too subtle
Increase weight (thicker borders, bolder text) instead of darkening color
Maintains softer look while adding emphasis

Semantics are Secondary

Don't design actions purely on semantics:

Semantics are important but hierarchy matters more
Not every positive action needs a big green button
Not every destructive action needs a big red warning

Three-Level Action Hierarchy:

Every action on a page sits in a pyramid of importance:

Primary actions:

One true primary action per page (usually)
Should be obvious and high-contrast
Use solid, high-contrast background colors
Example: Main CTA button, Submit button

Secondary actions:

A couple of less important actions
Should be clear but not prominent
Use outline styles or lower contrast background colors
If using a grey solid fill (not an outline), pick a mid grey (400-500), never a near-white grey (200): a too-light grey button reads as disabled
Example: Cancel button, Back button

Tertiary actions:

Seldom used, supportive actions
Should be discoverable but unobtrusive
Style like links
Example: "Delete account", "Reset to defaults"

Destructive actions:

Primary action in destructive flows should be clear and obvious
Use secondary/tertiary button style for destructive action
Make safe option (cancel) more prominent
Add confirmation step if needed

Visual hierarchy > semantic meaning

Visual Hierarchy