Layout

The criterion is perceptual: attention lands where it should, groups read as groups, depth reads as depth. The grid, the ramps, and the shadow specs below are means to that end. The eye is the test; the numbers are where you start.

Visual hierarchy as a system

Hierarchy is not size alone. It is the coordinated use of scale, weight, space, and color temperature to direct attention without labeling it. Every surface has a hierarchy — the question is whether it's intentional.

Why hierarchy works — the perceptual foundation

Design decisions don't work because a style guide says so. They work because of how human visual processing is structured. Knowing the underlying mechanism makes the rules predictive rather than prescriptive.

Pre-attentive processing — Before conscious attention activates (within ~250ms), the visual cortex processes a small set of attributes in parallel: color, size, orientation, motion, and spatial position. This is why a single red item in a field of blue objects is seen instantly — the brain doesn't scan sequentially. Hierarchy exploits this: make the most important element differ from its context on a pre-attentive attribute (size, weight, color), and attention lands there first without the user deciding to look.

Gestalt principles — the grammar of grouping

• Proximity: elements close together are perceived as related. This is not a rule — it is a reflex. No label can override it. If two elements that don't belong together are spatially adjacent, the user will assume they're related regardless of what they say.
• Similarity: elements that look alike are perceived as part of a set. This is why consistent button styling matters — every button that looks like a button signals "action available here." Break the pattern on one element and it reads as belonging to a different category.
• Continuity: the eye follows paths and edges naturally. Aligned elements feel connected. Intentional visual axes guide attention without arrows or labels.
• Figure/ground: every element is perceived as either foreground (figure) or background (ground). Surface contrast controls this. Low contrast = receding. High contrast = advancing. This is why pure #000000 on white feels harsh — maximum figure/ground contrast with no intermediate depth.

Cognitive load and chunking — Working memory holds roughly four chunks of information at once. A UI that presents 12 undifferentiated items simultaneously overloads working memory. Grouping by Gestalt proximity and similarity reduces 12 items to 3 groups of 4 — three chunks, not twelve. Good hierarchy is working memory management.

The serial position effect — Items at the beginning and end of a sequence are remembered more reliably than items in the middle. In navigation: primary action at start or end of the tab bar. In a list: the most important filter or action at top or bottom, not buried in the middle. This is not convention — it is how episodic memory encodes sequence position.

The four axes of hierarchy

Scale contrast — The perceived difference between your largest and smallest type or element. A flat ramp (16/18/20/24) reads as noise. A steep ramp (14/16/32/56) reads as signal. The ratio between adjacent levels matters more than the absolute values. A 1.25 modular scale is mechanical. A designed ramp — 0.75 / 0.875 / 1 / 1.25 / 1.625 / 2.25rem — has deliberate leaps.

Weight contrast — Bold against regular creates emphasis without size change. But bold-on-bold is meaningless, and regular-on-regular is invisible. The contrast between the heaviest and lightest element in view must be unmistakable: if you squint at the page and can't tell what matters, the weight ramp is too shallow.

Spatial grouping — Proximity signals relationship. Elements that belong together must be separated from other groups by a gap larger than their internal spacing. The Gestalt law of proximity is the designer's grammar. Breaking it is a hierarchy error, not a style choice. Internal padding: --spacing-sm. Group gap: --spacing-xl. Section gap: --spacing-3xl. If these collapse toward the same value, the page dissolves into noise.

Color temperature as depth signal — Warm, high-chroma colors advance in perception. Cool, low-chroma colors recede. In a predominantly cool neutral UI, a warm accent reads as foreground even at small size. Use this directionally: primary actions warm (or high-contrast); secondary and disabled cool and desaturated; backgrounds the most neutral and receded surface in the palette. Depth is not always z-index. It is often hue.

Hierarchy anti-patterns (the real cost)

• Same font size for three adjacent levels — scale contrast collapsed, attention has nowhere to go
• All text in --color-text-default — weight and color not doing any work
• Card padding and section gap at the same value — spatial grouping erased
• Accent color used for decoration and for primary CTA — depth signal wasted
• Every section on the same skeleton and spacing cadence — perfect rhythm, dead page. Spacing on grid is layout; composition is tension, and it needs at least one section whose content breaks the cadence

Spacing — the 8pt grid

Spacing is not a list of numbers. It is an architectural decision about rhythm, breathing, and grouping.

The 8pt grid

If the project already follows a different consistent rhythm (a 4pt grid, a platform-native scale), that rhythm wins — consistency beats this default. Otherwise: all spacing values are multiples of 8px (with 4px available for micro-details: icon-to-label gaps, badge padding, internal icon alignment). This is not aesthetic preference — it is alignment with device pixel ratios (1×, 2×, 3× all divide cleanly by 8) and with the visual rhythm of body text at 16px.

Why 8px base: at 1rem body text (16px), a line-height of 1.5 = 24px = 3 grid units. Padding of 16px = 2 grid units. Section gap of 48px = 6 grid units. The page breathes in a consistent rhythm because every measurement is proportionally related.

Not every value needs to be on grid. Border widths (1px, 2px), icon sizes (14px, 20px), and focus ring offsets (2px) are exceptions. The rule applies to spatial relationships — padding, margin, gap — not to atomic measurements.

Optical vs mathematical alignment

Mathematical alignment (pixel-perfect centering) and optical alignment (what looks centered) are different things. The eye is not a ruler.

Icon + label: mathematically centered icons on a cap-height baseline look too high. Nudge the icon 1–2px down to align with the optical center of the adjacent text.

Large type: a headline with padding-top: 48px and padding-bottom: 48px looks bottom-heavy. Text descenders and line-leading add visual weight below. Increase top padding by 8–12px and reduce bottom accordingly to achieve optical balance.

Cards with icons: a 24px icon in a 40px container is mathematically centered. It may look slightly high. The visual centroid of icons is often above the geometric center — compensate.

Principle: start with mathematical alignment, then look, then adjust. Document the adjustment. "Icon nudged 2px down for optical baseline alignment" is a design decision, not a hack.

Spatial grouping in practice

The gap between items that belong together must be smaller than the gap that separates groups. This is not a matter of aesthetics — it is the functional communication of relationships.

If a section gap equals a component's internal padding, the hierarchy has collapsed. Fix the gap, not the padding.

When to break the grid — intentionally

Every experienced designer breaks the 8pt grid. The question is whether the break is a decision or a slip.

Intentional breaks:

• Marketing heroes: section gaps jump to 96px or 128px (12–16 grid units) to create breathing room that signals premium. This is the grid at 3× density, not a violation.
• Dense data UI: internal component spacing drops to 4px where the grid unit is too large — 4px is the sub-grid. 6px is off-grid: use 4px or 8px instead.
• Optical correction: a 2px nudge on an icon or baseline alignment is not a grid break — it's a sub-pixel optical correction. Document it. "Icon nudged 2px down for optical baseline alignment" is a craft decision.
• Type metrics: cap-height, x-height, descenders don't align to the grid. The grid applies to spacing between elements, not to internal letter geometry.

Grid violations (bugs, not decisions):

• padding: 11px 14px — no grid logic, no optical reason
• margin-top: 23px — between standard values with no derivation
• Inconsistent gap values within the same component (gap: 12px in one list, gap: 10px in adjacent list)

The test: can you explain why this value isn't on grid? If yes, document it. If no, put it on grid.

Baseline grid — optional, high-value

For text-heavy products (editorial, documentation, marketing pages), a baseline grid aligns all text elements to a 4px or 8px baseline. This makes multi-column layouts feel coherent rather than accidentally aligned. In practice: set line-height to a multiple of the grid unit, and use spacing values that are grid multiples. The result is automatic baseline alignment without explicit calculation.

Materiality — surfaces and shadows

How surfaces feel is as important as their color.

Shadows

• Tint shadows to the background hue — a shadow on a warm surface should not be neutral gray
• "Diffusion shadow": very light, wide-spreading — 0 20px 40px -15px rgba(0,0,0,0.05) — depth without clutter
• Inner border on glass surfaces: 1px rgba(255,255,255,0.1) to simulate physical edge refraction
• Inner shadow on glass: inset 0 1px 0 rgba(255,255,255,0.1) — do not just use backdrop-blur alone
• Z-index only for systemic layers (sticky nav, modal, overlay, toast) — no arbitrary stacking

Cards

• Cards communicate elevation, not containment. Use them when z-axis hierarchy is the point.
• Dense data UI (cockpit density): remove cards entirely. Use hairline dividers or negative space.
• Rounded containers: large radius (2rem+) for marketing surfaces, small (0.375rem) for data UI.

Color

• Max 1 accent color per UI. When in doubt, go more neutral.
• Off-black only — never pure black (oklch(0% 0 0)). Use oklch(12–15% 0.01–0.02 H) where H matches the brand hue.
• Dark mode: avoid pure dark backgrounds. Base surface at oklch(14% C H), elevated at oklch(18% C H) — the slight L gap creates depth without introducing new colors. The color skill carries the full dark-mode transformation.