{PROJECT_NAME} — Web Design Reference Sheet

Single source of truth for all visual and interaction decisions. Use this document when designing in Figma, writing CSS, or reviewing code. Figma source: Web Design Reference Sheet

Table of Contents

1. Brand Identity
2. Colour Palette
3. Typography
4. Spacing System
5. Layout & Grid
6. Borders & Radius
7. Shadows & Elevation
8. Motion & Transitions
9. Component Patterns
10. Accessibility
11. Dark Mode
12. Figma Sync Notes

1. Brand Identity

If brand identity is not defined in code, ask the user to supply it or mark as TBD.

2. Colour Palette

All tokens are defined as CSS custom properties in {TOKEN_FILE_PATH}.

Primary Colours

Semantic Colours

Colour Do / Don’t

• Do use --{accent} only on --{sufficient-contrast-bg} text
• Don’t use --{over-saturated} as a background

3. Typography

Font Stack

Include only font roles that exist in the project.

Type Scale

4. Spacing System

Section Vertical Rhythm

5. Layout & Grid

Container

Column Grid

Breakpoints

6. Borders & Radius

7. Shadows & Elevation

8. Motion & Transitions

Standard Transitions

Keyframe Animations

List any named @keyframes found in CSS with their purpose.

Reduced Motion

Document how prefers-reduced-motion is handled (global CSS guard, per-component, etc.).

9. Component Patterns

For each distinct interactive pattern found in components, document:

Buttons

Primary:

{copy-paste HTML with all classes}

Secondary:

{copy-paste HTML}

Ghost (on dark bg):

{copy-paste HTML}

Badge / Section Label

{copy-paste HTML}

Card

{copy-paste HTML}

Section Structure

{copy-paste HTML section skeleton}

Add any additional patterns found (modals, toasts, tabs, accordions, etc.)

10. Accessibility

11. Dark Mode

Document which tokens change in dark mode and which stay fixed (accent colours typically do not change).

Dark mode strategy: {class-based .dark / prefers-color-scheme / data attribute}.

12. Figma Sync Notes

Keeping Figma and code in sync

1. All design tokens live in {token file path} — treat it as the master token source.
2. When updating a value: update CSS first, then reflect in Figma library.
3. The Figma Web Design Reference Sheet provides the template structure. Use it to populate a project-specific Figma file.
4. Recommended Figma file structure: Colours → Typography → Spacing → Grid → Components → Accessibility notes.

Naming convention alignment

Checklist when adding a new component in Figma

• Uses only tokens from Section 2 (Colours)?
• Type size, weight, and font match Section 3 (Typography)?
• Spacing uses values from Section 4 (Spacing)?
• Passes WCAG AA contrast (Section 10)?
• Added to Component Patterns (Section 9) in this doc?

Elements of Design

The elements of design are the fundamental visual building blocks — the raw vocabulary of any visual composition. Every design, from a logo to a webpage, is constructed from some combination of these elements.

1. Line

A mark connecting two points; the most fundamental element.

Types:

• Straight — order, precision, strength
• Curved — flow, softness, elegance
• Diagonal — dynamism, tension, movement
• Zigzag — energy, nervousness, excitement

Line weight: Thick lines feel heavy and bold; thin lines feel delicate and refined.

Implied lines — not drawn, but suggested by alignment of elements, eye gaze direction, or the edge of a shape. Strongly guide eye movement.

Design application: Horizontal rules, border separators, underlines, and grid lines are all lines. Diagonal photography compositions create energy. Text alignment creates implied lines that organise content.

2. Shape

A two-dimensional area defined by a boundary (a closed line, contrast, or colour).

Geometric shapes — circles, squares, triangles, polygons. Convey structure, order, logic.

• Square/Rectangle: stability, trust, reliability
• Circle: wholeness, community, continuity
• Triangle: direction, energy, dynamism (point up = growth; point down = instability)

Organic shapes — irregular, free-form, natural. Convey warmth, creativity, approachability.

Abstract shapes — simplified or stylised representations (icons, logos, pictograms).

Positive vs negative shape: The filled shape (positive) and the space around it (negative/white space) are equally important. Logos exploit figure-ground relationships.

Design application: Button shapes, card containers, avatar crops, hero section blobs, icon design — all are shape decisions. Rounded corners soften; sharp corners are more assertive.

3. Form

Shape extended into three dimensions — or the illusion of three dimensions on a 2D surface.

Actual form — physical 3D objects (packaging, product design, signage).

Implied form — the illusion of depth and volume created through:

• Shading and highlights (light source)
• Perspective and foreshortening
• Overlap and occlusion
• Gradient and shadow

Design application: Drop shadows, box shadows, gradients, and depth layers (elevation system) all create implied form in flat UI design. Skeuomorphic design relies heavily on form to imply physicality.

4. Space (Positive & Negative)

The area within and around elements.

Positive space — the area occupied by subjects and content.

Negative space (white space) — the empty area around and between elements. Not absence — it is an active element that defines and supports the positive content.

Depth cues:

• Overlap — objects in front obscure those behind
• Size — smaller = further away
• Atmospheric perspective — distant objects are lower contrast and slightly blue-shifted
• Placement — higher on the picture plane = further away (landscape convention)

Design application: See whitespace-theory.md for detailed application guidance. In UI, the space between a heading and its paragraph, between a card and its neighbours, and the padding inside a button are all active space decisions.

5. Texture

The surface quality of an element — tactile or visual.

Actual texture — physically touchable (print, packaging, embossing, fabric).

Visual texture — the illusion of texture on screen:

• Photographic textures (grain, paper, concrete)
• Pattern-based textures (dot grids, cross-hatch, noise)
• Typographic texture — dense body text creates its own visual texture at a distance

Design application: Subtle noise overlays add warmth to flat colour backgrounds. Paper texture backgrounds evoke analogue craft. Avoiding texture creates the clean, digital aesthetic. Most modern web UI uses texture sparingly — a background grain, a subtle pattern.

6. Value (Light & Dark)

The relative lightness or darkness of an element — independent of hue.

Value scale: Runs from pure white (lightest) through grey to pure black (darkest).

High contrast — strong differentiation between light and dark areas. Dramatic, bold, readable.

Low contrast — subtle tonal differences. Soft, refined, sophisticated — but can reduce readability.

Tint — a colour mixed with white (lighter value). Shade — a colour mixed with black (darker value). Tone — a colour mixed with grey (reduced saturation, adjusted value).

Design application: Value is the foundation of readability. Text must have sufficient value contrast against its background (WCAG contrast ratios are essentially value contrast ratios). Dark mode inverts the value hierarchy.

7. Colour

The visual property arising from the spectrum of light reflected or emitted. The most emotionally powerful element of design.

Colour properties:

• Hue — the pure colour (red, blue, yellow, etc.)
• Saturation (Chroma) — the intensity or purity of the colour. Fully saturated = vivid; desaturated = grey.
• Value (Lightness/Brightness) — how light or dark the colour is.

Colour temperature:

• Warm — reds, oranges, yellows. Advance visually, feel energetic, urgent.
• Cool — blues, greens, purples. Recede visually, feel calm, trustworthy.

Colour relationships (harmony): See psychology-of-color.md for full palette strategy.

Additive colour (RGB/screen) — red + green + blue = white. Used for all digital design.

Subtractive colour (CMYK/print) — cyan + magenta + yellow + black = black. Used for print.

Design application: Colour is never used in isolation — it is always experienced relative to surrounding colours. Establish a palette of primary, secondary, and neutral colours, then use them consistently through design tokens.

8. Typography (as Element)

Typography is simultaneously a functional tool and a visual element with its own texture, rhythm, and personality.

Typeface categories:

• Serif — traditional, editorial, trustworthy (Times New Roman, Georgia, Playfair Display)
• Sans-serif — modern, clean, approachable (Inter, Helvetica, Roboto)
• Monospace — technical, code, precise (JetBrains Mono, Courier)
• Display/Decorative — expressive, personality-driven — use sparingly for headings only
• Script/Handwritten — personal, elegant, artisanal — use very sparingly

The typographic elements:

• Letterform — the shape of individual characters
• Counter — the enclosed or partially enclosed spaces within letters (e.g. inside an ‘o’)
• Baseline — the invisible line on which letters sit
• X-height — the height of lowercase letters (higher x-height = more readable at small sizes)
• Ascender/Descender — strokes above/below the cap height and baseline

Design application: See typography-principles.md for hierarchy, scale, and pairing guidance.

Quick Reference

Design Reference Skill — {PROJECT_NAME}

Enforce visual and interaction consistency across code and Figma.

Mindset

Never make a colour, spacing, typography, or component decision from memory. Always read the reference sheet first. The reference sheet is the contract — code is the implementation. When in doubt, check the token; when the token is wrong, update the reference sheet first, then the code.

When to activate

• Before adding or editing any CSS or inline style
• Before creating a new React/HTML component
• Before reviewing a PR that touches UI files
• When asked “is this on brand?”, “does this match the design?”, or “check the style”
• Before making a Figma decision on colour, spacing, or type

Workflow

Step 1 — Read the reference sheet

Use the Read tool on docs/design/design-reference.md.

Step 2 — Identify the relevant section

Step 3 — Apply the rules

{Paste the 6–8 most important project-specific rules from the generated reference sheet here.}

Step 4 — Output format for reviews

When reviewing files for style consistency, output findings as:

file:line — [RULE] description

Group findings by category: COLOUR, TYPOGRAPHY, SPACING, LAYOUT, COMPONENT, ACCESSIBILITY, DARK MODE, MOTION.

Anti-patterns to catch

Token quick-reference

{Paste the colour, font, and spacing tokens in the compact format from docs/design/design-reference.md.}

Gestalt Principles

Gestalt psychology (German: “shape” or “form”) describes how the human brain organises visual information into unified wholes rather than perceiving individual parts in isolation. The core insight: the whole is different from the sum of its parts.

These principles are directly applicable to UI/UX layout because the browser renders a flat collection of HTML elements — Gestalt explains how users perceive those elements as meaningful groups, patterns, and structures.

1. Proximity

Elements close together are perceived as belonging to the same group.

The brain interprets spatial closeness as a relationship signal — before colour, shape, or any other attribute is processed.

● ● ●   ■ ■ ■
Three circles and three squares — perceived as two groups based on proximity,
despite the shape difference.

UI application:

• A label and its form input must be closer to each other than to adjacent label-input pairs
• Navigation items grouped by function (primary nav, utility nav) should have more space between groups than within them
• Cards on a grid are perceived as related because the gap between cards is smaller than the gap between section blocks
• The gap above a heading should be larger than the gap below it — tying the heading to its body

Practical rule: If two elements are related, move them closer. If they are separate, move them further apart. Never rely on labels or lines when spacing can do the work.

2. Similarity

Elements that share visual attributes — colour, shape, size, orientation, texture — are perceived as belonging together.

Similarity creates implicit categorisation without borders, labels, or explicit grouping.

UI application:

• All primary buttons should share the same colour, shape, and weight so users learn the pattern instantly
• Navigation items at the same hierarchy level should be visually identical
• Interactive elements (links, buttons, clickable cards) should share a colour token so users know they are actionable
• Column headers in a data table look different from data rows — similarity groups each type

Warning: Similarity works against you when unrelated elements accidentally share attributes. If your CTA button and your error message are both red, the error message inherits the “action” connotation of the button colour.

3. Figure-Ground

The brain separates visual input into a dominant “figure” (foreground) and a “ground” (background).

The figure is perceived as solid, in front, with definite shape. The ground is perceived as behind, shapeless, continuous.

Classic example: The Rubin vase — two face profiles or a vase, depending on which you perceive as figure vs ground.

UI application:

• Modal dialogs rely on figure-ground: the modal is the figure; the dimmed overlay is the ground
• Dropdown menus elevate above the page via shadow — creating figure-ground separation
• Cards sit on a background — the card is figure, the page is ground. This is why card shadow and background colour must provide sufficient contrast
• High enough contrast between text and background establishes text as figure and background as ground
• A lack of contrast collapses the figure-ground relationship and makes text unreadable

Ambiguous figure-ground: Sometimes intentional (logo design, optical illusion art), but in UI it creates confusion. Ensure your figure (interactive or important element) is always clearly distinct from its ground.

4. Continuity (Common Fate)

Elements arranged along a line, curve, or path are perceived as related and connected.

The brain follows the path and groups the elements along it.

UI application:

• A horizontal navigation bar — items arranged along a line are perceived as a related set
• A timeline (vertical or horizontal) — items along the line are perceived as sequential
• A stepper component — numbered steps on a shared track form a connected sequence
• Scrolling content — items that appear along the user’s scroll path are linked by the path
• Progress indicators — the filled portion of a progress bar reads as “completed”; the unfilled as “remaining” — connected along the same track

5. Closure

The brain completes incomplete shapes and fills in missing information.

Humans prefer complete, familiar shapes and will mentally “close” gaps to perceive them.

UI application:

• Icons are often constructed with negative space — the brain completes the shape (hamburger menu, check mark, loading spinners)
• A grid of cards cut off at the edge of the viewport signals “there are more items here” — the user’s brain completes the row and understands to scroll
• Partially visible images at the edge of a carousel indicate more content is available
• Minimalist logos exploit closure — a simple incomplete shape reads as the full letter or symbol

6. Prägnanz (Law of Good Form / Simplicity)

The brain perceives ambiguous or complex images as the simplest possible form.

Given multiple possible interpretations, the simplest is preferred.

UI application:

• Users will interpret a complex set of elements as simple geometric structures (rows, columns, grids) before they process individual element details
• Overly complex layouts trigger cognitive load — users simplify to “this is confusing” before they try to parse the detail
• Clean, grid-aligned layouts conform to Prägnanz — they feel immediately comprehensible
• Every element added to a layout adds complexity; only add elements that earn their presence

7. Common Fate

Elements that move together are perceived as belonging together.

When multiple elements move in the same direction simultaneously, the brain groups them.

UI application:

• An accordion section — the heading and body content expand/collapse together, reinforcing their relationship
• A toast notification that slides in from the top-right is perceived as a single unit because all its parts move together
• Parallax effects — elements moving at different rates are perceived as existing on different depth layers (figure-ground)
• Loading skeleton screens — elements that pulse together communicate “these are loading together”

8. Uniform Connectedness

Elements with an explicit visual connection (line, border, shared background) are perceived as more strongly related than elements grouped by proximity or similarity alone.

UI application:

• Cards use a border or background colour to visually bind their contents into a single unit
• A form section uses a card or background shade to group its fields
• A tag/badge binds a label and colour into an inseparable unit
• Breadcrumbs use dividers to connect sequential path items
• Stepper components use lines to connect numbered steps

Applying Gestalt to Layouts

When building a page layout, work through these questions:

Proximity check: Is every related pair of elements closer to each other than to unrelated elements?

Similarity check: Do all interactive elements share a visual attribute that marks them as interactive? Do all navigation items of the same level look the same?

Figure-ground check: Is the main content clearly distinct from the background? Do modals, dropdowns, and elevated panels have enough shadow/contrast to separate from the page?

Closure check: Are any elements cut off that should signal “more content available”? Is that cutoff intentional?

Continuity check: Are sequential or related items arranged along a common path or line?

Prägnanz check: Does the overall layout resolve to a simple structure (grid, columns, rows) that the brain can interpret quickly? Is there unnecessary complexity?

Quick Reference

Grid and Layout Theory

Grids are the invisible structure that organises content into coherent, predictable, and professional layouts. They create alignment, rhythm, and consistency — the qualities that separate designed pages from assembled pages.

What a Grid Does

A grid provides:

1. Alignment — elements connect to shared invisible lines, creating visual order
2. Consistency — the same grid applied across pages creates coherence
3. Efficiency — designers and developers share a common spatial language
4. Flexibility — grid systems allow variety within structure

A well-applied grid is invisible to the viewer — they simply feel that the layout is “right”.

Types of Grid

1. Column Grid

The most common grid type for web layout. The page width is divided into a fixed number of equal columns with consistent gutter (space between columns) and margin (space on the outer edges).

Standard web column grids:

12-column grid is the de facto standard because 12 divides evenly into 1, 2, 3, 4, 6, and 12 columns — providing maximum layout flexibility.

How to use column spans:

• Full-width section: 12 columns
• Two equal halves: 6+6
• Sidebar + content: 3+9 or 4+8
• Three equal thirds: 4+4+4
• Four cards: 3+3+3+3
• Featured + two supporting: 6+3+3

2. Baseline Grid

A horizontal grid with uniform row height (the baseline interval) applied to the entire page. All text elements align to the baseline grid, creating vertical rhythm.

The baseline unit is typically equal to the body text’s line height (e.g. 24px for 16px body at 1.5 line height).

In web practice: Pure baseline grids are difficult to maintain with CSS. Instead, establish a spacing scale based on a base unit (8px is standard) that approximates baseline rhythm:

4px  → micro (icon gaps, border offsets)
8px  → xs
16px → sm
24px → md
32px → lg
48px → xl
64px → 2xl
96px → 3xl

All padding, margin, and gap values should come from this scale.

3. Modular Grid

Combines column and row grids to create a matrix of cells. Common in editorial design (magazine layouts), image galleries, and complex dashboard layouts.

Web application: CSS Grid with defined row heights creates modular grids.

4. Hierarchical Grid

A flexible, rule-based approach where elements are placed intuitively but still align to implied axes and proportional relationships. Not a strict grid — more a set of alignment rules.

Common in highly creative, editorial, or asymmetric layouts. Requires more design judgement.

The 8-Point Grid System

The most widely adopted spacing system for digital product design.

Principle: All spacing values (padding, margin, gap, width, height) are multiples of 8px.

Why 8?

• Most common screen densities (1×, 1.5×, 2×, 3×) scale 8px evenly — no blurry sub-pixel rendering
• 8px divides into 4px and 2px for fine adjustments while maintaining the system

Practical scale:

4px   → hairline spacing (badge padding, tight icon gaps)
8px   → tight spacing (within-component padding)
16px  → default spacing (standard component padding, gap between related elements)
24px  → comfortable spacing
32px  → section breathing room
48px  → section separation
64px  → major section gaps
96px  → hero/section vertical padding

Applying in CSS:

:root {
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 16px;
  --space-4: 24px;
  --space-5: 32px;
  --space-6: 48px;
  --space-7: 64px;
  --space-8: 96px;
}

Responsive Layout Strategies

Fluid vs Fixed

Fixed-width layout: A max-width container centred on the page. Common values: 1200px, 1280px, 1440px. Clean, predictable, easy to reason about.

Fluid layout: Container stretches with the viewport up to a maximum. Used when content should expand with available space (data tables, dashboards).

Full-bleed sections: Background images, colours, and video that extend edge-to-edge, while inner content remains within the max-width container.

.section-wrapper {
  width: 100%;
  background-color: var(--color-surface-alt);
}
.section-inner {
  max-width: 1200px;
  margin-inline: auto;
  padding-inline: 24px;
}

Breakpoints

Define breakpoints based on content needs, not device names.

Common breakpoints:

/* Mobile-first default styles: 0px and up */
@media (min-width: 640px)  { /* sm  — large phone / small tablet */ }
@media (min-width: 768px)  { /* md  — tablet portrait */ }
@media (min-width: 1024px) { /* lg  — tablet landscape / small desktop */ }
@media (min-width: 1280px) { /* xl  — desktop */ }
@media (min-width: 1536px) { /* 2xl — wide desktop */ }

Mobile-first approach: Write default styles for mobile, then use min-width media queries to add complexity for larger screens. This is preferable to desktop-first because:

• Forces prioritisation of essential content
• Reduces the amount of CSS to override
• Better for performance on constrained devices

CSS Grid for Page Layout

.page-grid {
  display: grid;
  grid-template-columns: repeat(12, 1fr);
  gap: 24px;
  max-width: 1200px;
  margin-inline: auto;
}

.hero-content    { grid-column: 1 / 8; }
.hero-image      { grid-column: 8 / 13; }

@media (max-width: 768px) {
  .hero-content,
  .hero-image    { grid-column: 1 / -1; }
}

CSS Flexbox for Component Layout

Flexbox is suited to one-dimensional layouts (row or column):

.card-row {
  display: flex;
  gap: 24px;
  flex-wrap: wrap;
}
.card {
  flex: 1 1 280px; /* grow, shrink, min-width */
}

Proportional Systems

Golden Ratio (φ ≈ 1.618)

A proportion found throughout nature and classical architecture. Rectangles, containers, and typographic hierarchies built on this ratio feel naturally harmonious.

If short side = 1, long side = 1.618
If container width = 960px, a golden sidebar = 960 / 1.618 ≈ 593px content + 367px sidebar

Rule of Thirds

Divide the composition into a 3×3 grid. Place focal points and key elements at the intersection points (“power points”). Avoids static centred compositions.

Web application: Off-centre hero layouts, image composition guidelines for photography.

Silver Ratio (1:√2 ≈ 1:1.414)

Used in ISO paper sizes (A4, A3, etc.). Useful for maintaining proportional relationships when scaling components.

Layout Patterns for the Web

Hero section

[Full-width background]
  [Max-width container]
    [Left: headline + sub-text + CTA] [Right: image or illustration]

Common variants: centred text with background image, full-bleed video, split 50/50.

Feature/Benefits grid

[Section heading — centred or left-aligned]
[3-column or 4-column card grid]

Alternating content rows

[Image left | Text right]
[Text left  | Image right]
[Image left | Text right]

Creates visual rhythm and variety while maintaining a consistent structure.

Sidebar layout

[Main content — 8 columns] [Sidebar — 4 columns]

Common for blog posts, documentation, product pages.

Masonry / Pinterest grid

Variable height items in a multi-column layout. CSS columns or JS masonry library. Use when items have unpredictable heights (images, user-generated content).

Common Layout Mistakes

Principles of Design

The principles of design are the rules and guidelines that govern how the elements of design are arranged and combined to create effective visual communication. They are the “how” of design — while elements are the raw materials, principles are how you use them.

1. Balance

Visual equilibrium — the distribution of visual weight across a composition.

Symmetrical balance — identical or near-identical elements mirrored across an axis. Conveys stability, formality, trustworthiness. Common in corporate and institutional design.

Asymmetrical balance — different elements balanced by compensating weight (size, colour, texture). More dynamic and modern; requires careful judgement. Common in editorial and startup design.

Radial balance — elements radiate from a central point. Creates a sense of movement and energy. Used in logos, icons, and decorative elements.

Design application: In web UI, asymmetric layouts (e.g. hero image left + text right) feel contemporary while remaining stable if visual weights are managed.

2. Contrast

The juxtaposition of opposing elements to create visual interest, hierarchy, and readability.

Contrast can be achieved through:

• Colour — dark vs light, complementary colours
• Size — large heading vs small body text
• Weight — bold vs regular
• Shape — geometric vs organic
• Texture — rough vs smooth
• Space — dense vs open areas

Design application: Contrast is the primary driver of visual hierarchy. Without contrast, everything competes equally and nothing is emphasised.

Accessibility note: Colour contrast must meet WCAG AA (4.5:1 for body text, 3:1 for large text and UI components).

3. Emphasis (Dominance / Focal Point)

The deliberate prioritisation of one element to draw the eye first.

Techniques:

• Size (larger = more important)
• Colour (saturated/bright against muted surroundings)
• Isolation (surrounded by whitespace)
• Position (top-left, centre, or above the fold)
• Contrast
• Unique shape or texture

Design application: Every page needs a clear primary focal point — the hero headline, the CTA button, the product image. If everything is emphasised, nothing is.

4. Movement (Flow)

The path the viewer’s eye travels through a composition.

Z-pattern — natural reading path for sparse/marketing layouts: top-left → top-right → diagonal → bottom-left → bottom-right.

F-pattern — natural reading path for text-heavy content: horizontal scan across top → down the left edge → shorter horizontal scans.

Circular movement — used in logo design and illustration to keep the eye engaged within the composition.

Directional cues that guide movement:

• Lines and arrows
• Character eye gaze direction
• Repetition and rhythm
• White space channels

Design application: Hero sections typically use Z-pattern. Blog/article content uses F-pattern. Design layouts to match the expected reading pattern of the content type.

5. Pattern & Repetition

The repeated use of the same or similar elements throughout a design.

Repetition creates consistency and unity — repeated colours, fonts, shapes, and spacing build a recognisable visual language.

Pattern is organised repetition — a motif repeated at regular intervals to create texture or background interest.

Design application: A consistent component library (buttons, cards, badges using the same radius, padding, shadow) is repetition in practice. Repeated typographic scales and spacing tokens enforce visual rhythm.

6. Rhythm

The sense of movement created by repeating elements at regular or varied intervals — analogous to rhythm in music.

Regular rhythm — uniform intervals, predictable. Creates order and calm.

Flowing rhythm — organic, natural intervals. Creates a relaxed, elegant feel.

Progressive rhythm — elements gradually increase or decrease (e.g. a typographic scale or gradient progression). Creates a sense of direction and energy.

Design application: Consistent vertical rhythm (spacing between sections, between text blocks) creates a composed, professional feel. Irregular spacing feels accidental and unpolished.

7. Unity (Harmony)

The sense that all elements belong together — that the design is a coherent whole rather than a collection of parts.

Achieved through:

• Proximity — grouping related elements (see Gestalt)
• Repetition — consistent use of colour, type, and spacing
• Alignment — all elements connect to an invisible grid
• Continuation — visual lines carry the eye across elements

Design application: A design system enforces unity by codifying tokens and patterns. Unity breaks down when one-off colours, rogue font sizes, or inconsistent spacing creep in.

8. Variety

Deliberate introduction of difference to prevent monotony and maintain interest.

Variety is the counterbalance to unity — too much sameness is boring, too much variety is chaotic.

Design application: Vary section layouts alternately (image-left/image-right), use accent colours sparingly for emphasis, mix typographic weights to create texture in body content.

9. Proportion & Scale

The size relationship between elements, and the size of elements relative to the overall composition.

Golden ratio (φ ≈ 1.618) — a naturally pleasing proportion used in layout, typography, and spacing scales.

Rule of thirds — divide a composition into a 3×3 grid; place focal points at intersections.

Typographic scale — a modular scale (e.g. 1.25× or Major Third) applied to font sizes creates harmonious hierarchy.

Design application: Scale is the fastest way to communicate importance. A 48px heading above 16px body text immediately communicates hierarchy via proportion.

10. White Space (Negative Space)

The empty space around and between elements — not wasted space, but an active design element.

Macro white space — large gaps between major sections and layout regions. Creates breathing room and structure.

Micro white space — small gaps between lines, letters, list items, and UI components. Directly affects readability and perceived quality.

Design application: Generous white space signals premium positioning. Cramped layouts feel cheap or overwhelming. Padding, line-height, and margin tokens are the primary tools for controlling white space systematically.

11. Hierarchy

The visual organisation of elements by order of importance, guiding the viewer through a deliberate reading sequence.

Distinct from Emphasis (which concerns a single focal point), hierarchy is about the full stack of importance — primary, secondary, tertiary, and supporting content.

Created through:

• Size — larger elements read first
• Weight — bold before regular
• Colour — high contrast before low contrast
• Position — top and left before bottom and right
• Spacing — isolated elements feel more important

Design application: A well-structured typographic scale (H1 → H2 → H3 → body → caption) communicates hierarchy without decoration. If a user cannot identify the most important content within 3 seconds, hierarchy has failed.

12. Alignment

The positioning of elements along a common axis or grid line.

Types: Left, right, centre, justified.

Edge alignment — elements aligned to a shared invisible edge create visual connection and order.

Centre alignment — creates formality and symmetry; appropriate for short headings, modal dialogs, and hero text. Avoid for long body copy.

Design application: Even a few pixels of misalignment are noticed subconsciously and reduce perceived quality. Use an 8-point grid or consistent spacing tokens to enforce alignment.

Quick Reference

Psychology of Colour

Colour is the fastest, most emotionally direct element of visual communication. Humans process colour before they read words or recognise shapes. Understanding colour psychology enables deliberate emotional and perceptual decisions in design.

Colour Psychology Fundamentals

Colour responses are a mix of:

1. Biological — hardwired responses (red = danger/urgency)
2. Cultural — learned associations that vary by region and context
3. Contextual — the same colour reads differently depending on surrounding colours and industry

No colour has a single fixed meaning — context always mediates response.

Individual Colour Profiles

Red

Psychological associations: Energy, urgency, passion, danger, excitement, appetite stimulation
Positive: Confidence, vitality, strength, love
Negative: Aggression, warning, anger
Industry use: Food (appetite), retail (sale/CTA), healthcare (urgency), sports, entertainment
Brand examples: Coca-Cola, Netflix, YouTube, Target, Red Cross
Web application: High-visibility CTAs, error states, warning alerts, sale badges
Caution: Overuse creates anxiety; avoid as primary in finance and healthcare brands

Orange

Psychological associations: Enthusiasm, creativity, warmth, affordability, approachability
Positive: Friendly, energetic, optimistic, adventurous
Negative: Can feel cheap or unsophisticated if not handled carefully
Industry use: Food, retail, fitness, children’s brands, technology startups
Brand examples: Amazon, Harley-Davidson, Fanta, Mailchimp
Web application: Friendly CTAs, badge highlights, community/social features

Yellow

Psychological associations: Optimism, clarity, warmth, caution, intellect
Positive: Cheerful, accessible, hopeful, stimulating
Negative: Warning, anxiety, visual fatigue at high saturation
Industry use: Children’s, food, energy, optimism-led brands
Brand examples: McDonald’s, IKEA, Snapchat, LEGO, Post-it
Web application: Warning states, highlights, accent pops — rarely a primary brand colour
Accessibility note: Yellow on white fails WCAG contrast; always pair with dark text/backgrounds

Green

Psychological associations: Nature, growth, health, wealth, balance, harmony, go/permission
Positive: Calming, trustworthy, fresh, sustainable
Negative: Envy, inexperience (depending on shade)
Industry use: Finance (wealth/growth), health/wellness, environment, food, technology
Brand examples: Whole Foods, Starbucks, Spotify, John Deere, NHS
Web application: Success states, confirmation messages, eco/sustainability sections
Shade nuance:

• Bright/lime green: energy, youth
• Mid green: nature, health
• Deep/forest green: premium, traditional, wealth

Blue

Psychological associations: Trust, reliability, calm, professionalism, intelligence, depth
Positive: Dependable, serene, authoritative, loyal
Negative: Cold, distant, conservative, aloof
Industry use: Finance, technology, healthcare, government, corporate — the most universally trusted colour in Western business contexts
Brand examples: Facebook, Samsung, Ford, PayPal, NHS, Twitter/X, American Express
Web application: Primary brand colour for trust-building, links (convention), info states
Shade nuance:

• Light blue: openness, friendliness, digital
• Mid blue: professionalism, technology
• Navy: authority, tradition, finance
• Royal blue: confidence, premium

Purple

Psychological associations: Creativity, luxury, wisdom, mystery, spirituality, royalty
Positive: Imaginative, sophisticated, premium, magical
Negative: Artificial (no purple occurs in nature), distant
Industry use: Luxury goods, beauty/cosmetics, spirituality, creative agencies, children’s
Brand examples: Cadbury, Hallmark, Twitch, FedEx (with orange), Milka
Web application: Premium/luxury accents, creative brands, beauty and wellness

Pink

Psychological associations: Romance, femininity, playfulness, compassion, sweetness
Positive: Nurturing, gentle, joyful, approachable
Negative: Perceived as gendered; can undermine authority
Industry use: Fashion, beauty, food, healthcare, children’s, romance
Brand examples: Barbie, Victoria’s Secret, T-Mobile, Glossier, Breast Cancer Now
Shade nuance:

• Hot pink: bold, irreverent, pop
• Dusty/muted rose: sophisticated, modern femininity
• Pale blush: gentle, minimal, bridal

Brown / Earth Tones

Psychological associations: Reliability, warmth, earthiness, craftsmanship, naturalness
Positive: Grounded, honest, artisanal, heritage
Negative: Can feel dull or heavy without contrast
Industry use: Coffee, chocolate, organic/natural, heritage craft, furniture
Brand examples: UPS, Hershey’s, M&Ms, Timberland
Web application: Warm neutrals for backgrounds, earthy brand palettes

Black

Psychological associations: Sophistication, luxury, power, elegance, mystery, formality
Positive: Premium, timeless, authoritative
Negative: Heaviness, death, evil (cultural dependency)
Industry use: Luxury fashion, high-end automotive, technology, editorial
Brand examples: Chanel, Apple, Nike, Rolex, Louis Vuitton
Web application: Primary text, dark mode backgrounds, luxury brand primaries

White

Psychological associations: Purity, simplicity, cleanliness, space, minimalism
Positive: Fresh, modern, honest, open
Negative: Sterile, cold, clinical (context-dependent)
Industry use: Healthcare, technology, minimal/luxury, bridal
Web application: Background colour, negative space, breathing room, high-end minimal layouts

Grey

Psychological associations: Neutrality, balance, professionalism, sophistication, subtlety
Positive: Timeless, understated, versatile
Negative: Dull, lifeless, uncommitted
Use: Text, UI neutrals, supporting palette, background layering
Shade nuance: Warm greys (with brown/yellow undertone) feel inviting; cool greys (blue/green undertone) feel more digital and corporate

Colour Harmony Strategies

Monochromatic

Single hue at different values and saturations. Cohesive, sophisticated, restrained.
Use for: Minimal brands, luxury, premium services.

Analogous

Adjacent colours on the colour wheel (e.g. blue + blue-green + teal). Harmonious, natural.
Use for: Brands wanting depth without tension (nature, wellness, calm tech).

Complementary

Opposite colours on the wheel (e.g. blue + orange, red + green). High contrast, vibrant, energetic.
Use for: Sports brands, calls to action against a primary colour, packaging.

Split Complementary

A base colour plus the two colours adjacent to its complement. Less tension than complementary, more interest than analogous.

Triadic

Three colours evenly spaced on the wheel. Vibrant, playful, versatile.
Use for: Children’s brands, creative agencies, bold consumer brands.

Tetradic / Square

Four colours at 90° intervals. Rich and complex — requires careful balance.

Colour in Brand Strategy

Colour Ownership

Consistent use of a distinctive colour builds “colour equity” — the colour becomes associated with the brand before the logo is even read (Tiffany blue, Cadbury purple, Hermès orange).

Industry Colour Conventions

Breaking convention can differentiate — but at the cost of inherited trust signals:

Colour + Audience

• Age: Younger audiences respond to higher saturation; older audiences prefer more muted, sophisticated palettes
• Gender (generalised): Blues and greens are broadly neutral; highly saturated pink skews female
• Culture: Meanings shift significantly by region — white = mourning in some Asian cultures; green = envy in Western, luck in Asian contexts; red = luck in China

Practical Web Application

Establishing a colour palette

1. Primary — the dominant brand colour (1 hue)
2. Secondary — a supporting hue for variation (often complementary or analogous)
3. Accent — a high-visibility pop colour used sparingly (often the complement of the primary)
4. Neutrals — near-white, mid-grey, near-black — the silent majority of a UI
5. Semantic — success (green), warning (yellow/amber), error (red), info (blue) — standardised

Colour ratios

A common starting framework:

• 60% — dominant neutral or brand colour (backgrounds, large surfaces)
• 30% — secondary colour (headers, cards, supporting sections)
• 10% — accent colour (CTAs, highlights, badges)

Accessibility requirements

• Body text on background: 4.5:1 contrast ratio minimum (WCAG AA)
• Large text (≥18pt or ≥14pt bold): 3:1 minimum
• UI components and icons: 3:1 minimum
• Never rely on colour alone to convey information — pair with shape, label, or pattern

Dark mode colour considerations

• Saturated colours become overwhelming on dark backgrounds — desaturate by 10–20%
• Shadows don’t work on dark backgrounds — use elevation through colour lightness instead
• White text on pure black (#000000) creates harsh contrast — use #121212 or similar dark grey

Colour Temperature & Perceived Weight

Typography Principles

Typography is simultaneously functional and expressive — it must be readable, establish hierarchy, and convey personality. Good typography is largely invisible; the reader absorbs content without noticing the type choices. Bad typography creates friction.

The Six Core Principles

1. Hierarchy

Visual hierarchy communicates importance and guides reading order without requiring the reader to consciously decide what to read first.

Hierarchy tools:

• Size — largest = most important. The simplest and most powerful hierarchy signal.
• Weight — bold draws attention; light recedes.
• Colour — high-contrast pops; muted recedes.
• Case — UPPERCASE commands attention (use sparingly); sentence case is readable.
• Style — italic for emphasis, contrast, or quotation.
• Spacing — more space above a heading than below ties it to the content it introduces.

A clear hierarchy typically has 3–4 levels:

1. Display / Hero headline (largest, boldest)
2. Section headings (H2)
3. Sub-headings (H3)
4. Body text
5. Supporting / caption text (smallest)

More than 4 distinct levels in a single layout creates confusion.

2. Readability & Legibility

Legibility — whether individual characters can be distinguished from one another. Readability — whether text can be comfortably read at length.

Line length (measure): 45–75 characters per line is optimal for body text.

• Too short: eye jumps too frequently, creates choppy rhythm
• Too long: eye struggles to find the next line; fatigue sets in
• A practical rule: a paragraph container should be approximately ch units in CSS matching this range, e.g. max-width: 65ch

Line height (leading):

• Body text: 1.4–1.6× the font size
• Headings: 1.1–1.3× (tighter; they are read in short bursts)
• Very large display text: 1.0–1.1× or even below 1 for tight editorial effect

Letter spacing (tracking):

• Body text: 0 or very slight positive (0–0.02em)
• Uppercase labels/captions: +0.05–0.15em (uppercase needs more air to read well)
• Display/hero text: slight negative (-0.01 to -0.03em) tightens large type elegantly
• Never track body text negatively

Font size:

• Minimum body text: 16px (browser default is 16px for good reason)
• Captions/labels: 12–14px — use sparingly; never below 11px
• Mobile: same minimums; do not reduce body text on mobile

3. Type Pairing

Most designs use 2 typefaces maximum. 3 is occasionally justified; more creates noise.

Pairing strategies:

Serif + Sans-serif — the classic pairing. Serif for headings (personality), sans-serif for body (readability), or vice versa.

• Playfair Display + Inter
• Lora + Source Sans Pro
• Georgia + Helvetica

Sans-serif + Sans-serif — works when typefaces have contrasting personalities or weights.

• A humanist sans (Gill Sans, Optima) + geometric sans (Futura, Avenir)
• A display sans (Clash Display) + neutral sans (Inter, DM Sans)

Monospace + Anything — monospace reserved for code blocks only in most non-technical contexts.

Rules for pairing:

• High contrast between the two faces (serif vs sans, heavy vs light, condensed vs regular)
• Both faces should share a similar x-height for visual harmony at similar sizes
• Never pair two faces with the same personality — the pair must offer contrast

4. Typographic Scale

A modular scale creates harmonious size relationships throughout a design.

Common scale ratios:

Example scale at 1.25 (Major Third), base 16px:

xs:   10px  (0.64rem)
sm:   12px  (0.8rem)
base: 16px  (1rem)
md:   20px  (1.25rem)
lg:   25px  (1.563rem)
xl:   31px  (1.953rem)
2xl:  39px  (2.441rem)
3xl:  48px  (3.052rem)
4xl:  61px  (3.815rem)

In practice: Use a tool like typescale.com or set tokens in your design system. Apply the scale consistently — do not create arbitrary intermediate sizes.

5. Typographic Colour & Texture

At a distance, a block of body text creates a grey mass with its own texture and “colour” — even when printed in black.

Factors that affect typographic colour:

• Font weight (heavier = darker texture)
• Letter spacing (wider = lighter, airier texture)
• Line height (more leading = lighter, more open texture)
• Punctuation density
• The typeface itself (some faces have more variation between thick and thin strokes)

Design application: Vary typographic colour to create visual interest in text-heavy layouts. A pull quote in a heavier weight creates a dark spot that breaks up the grey mass of body text.

6. Emotional Tone

Every typeface has personality. The type choice signals brand values before a word is read.

Type Hierarchy in Web UI

Semantic HTML mapping

h1  → Display / page hero headline
h2  → Section headings
h3  → Sub-section headings
h4  → Card headings, list group headings
p   → Body text
small / .caption → Supporting text, metadata
label → Form labels

Practical CSS starting point

:root {
  --font-size-xs:    0.75rem;   /* 12px */
  --font-size-sm:    0.875rem;  /* 14px */
  --font-size-base:  1rem;      /* 16px */
  --font-size-lg:    1.125rem;  /* 18px */
  --font-size-xl:    1.25rem;   /* 20px */
  --font-size-2xl:   1.5rem;    /* 24px */
  --font-size-3xl:   1.875rem;  /* 30px */
  --font-size-4xl:   2.25rem;   /* 36px */
  --font-size-5xl:   3rem;      /* 48px */
  --font-size-6xl:   3.75rem;   /* 60px */

  --line-height-tight:  1.25;
  --line-height-normal: 1.5;
  --line-height-relaxed: 1.75;
}

Common Typographic Mistakes

Visual Hierarchy

Visual hierarchy is the arrangement of elements to show their order of importance — guiding the viewer’s eye through a composition in a deliberate sequence. It answers the question: “What should I look at first, second, third?”

Without hierarchy, all elements compete equally and the viewer is left to construct their own reading order — which means most will not engage deeply.

Why Hierarchy Matters

The human visual system performs pre-attentive processing before conscious attention kicks in. Within 50–150ms of seeing a page, the brain has already identified the dominant focal point, the rough structure of sections, and the approximate colour and size relationships. Hierarchy operates at this pre-attentive level.

The result: Users decide within seconds whether a page is worth reading. Hierarchy is what makes the content scannable enough to earn that decision.

The Seven Hierarchy Variables

1. Size

The most powerful hierarchy signal. Larger elements receive attention before smaller ones — regardless of position.

• A 60px headline at the bottom of the page commands more attention than a 14px caption at the top
• Use size contrast deliberately: the jump between heading levels should be perceptible at a glance
• Avoid “creeping sameness” — heading levels that are barely distinguishable

Rule of thumb: Each heading level should be at least 25% larger than the one below it.

2. Weight (Font Weight)

Bold text reads before regular text. Weight is the secondary hierarchy signal after size.

• Use weight to differentiate labels from values, headings from body text
• Bold sparingly within body text — if everything is bold, nothing is
• Variable fonts allow fine-grained weight control for subtle hierarchy within a single typeface

3. Colour & Value Contrast

High-contrast elements advance; low-contrast elements recede.

• A saturated accent colour on a muted background instantly signals importance
• Muted/grey text signals secondary or supporting information
• Colour alone must never be the only hierarchy signal (accessibility requirement)
• Dark-on-light and light-on-dark both work — contrast ratio matters, not which is “on top”

Practical use:

• Primary heading: full-contrast (e.g. #111)
• Body text: high contrast but softer (e.g. #333)
• Secondary/supporting text: reduced contrast (e.g. #666 or color-mix)
• Disabled/placeholder: low contrast (e.g. #999 — check WCAG for input placeholders)

4. Position

Where an element sits determines when it is seen.

Western reading convention (left-to-right, top-to-bottom):

• Top-left → first noticed
• Centre → formal, balanced, high attention
• Bottom-right → last noticed

Above the fold: Content visible without scrolling receives more attention. The most important hierarchy decision on any page is what lives above the fold.

Z-pattern vs F-pattern:

• Z-pattern: For sparse marketing/landing pages. Eye scans top-left → top-right → diagonal → bottom-left → bottom-right.
• F-pattern: For text-heavy content. Eye scans across the top, down the left edge, with shorter horizontal scans lower down. Left-rail items receive significantly more attention.

5. Whitespace (Isolation)

An element surrounded by empty space receives more visual weight than one surrounded by other elements. Isolation is a powerful hierarchy signal often overlooked.

• A single bold sentence with large margin above and below it commands more attention than the same sentence buried in a dense paragraph
• Pull quotes, stats, and key claims benefit from generous white space
• Dense information hierarchies (data tables, navigation menus) reduce whitespace to signal equal weight across items

See whitespace-theory.md for detailed whitespace guidance.

6. Contrast of Shape & Style

An element that differs from its surroundings in shape, form, or style will be noticed.

• A circular avatar in a layout of rectangles draws the eye
• A filled button among ghost buttons signals the primary action
• An italic pull quote in a Roman body text section creates hierarchy through style contrast
• Icons next to text items make those items scan faster and stand out from plain text

7. Sequence & Proximity

Proximity groups elements into visual units. Items close together are perceived as related; items spaced apart are perceived as separate.

Reading sequence is established by combining proximity with size, weight, and position:

• A heading followed immediately by body text (small gap between) signals a section unit
• Generous space before a heading signals the start of a new section
• A CTA button immediately below a value proposition captures attention at the end of the reading sequence

Building a Page Hierarchy

Step 1 — Define the goal

Every page has one primary goal. What action or understanding should the visitor leave with? This goal determines the primary focal point.

Step 2 — Establish 3–4 levels

Level 1 (dominant)  → Primary headline, hero image, or main CTA
Level 2 (secondary) → Supporting headings, key claims, section titles
Level 3 (tertiary)  → Body text, supporting copy, card content
Level 4 (supporting)→ Labels, captions, metadata, footnotes

Step 3 — Apply hierarchy variables

For each level, assign appropriate values of size, weight, colour, and spacing. The jumps between levels must be perceptible — not gradual.

Step 4 — Test the squint test

Squint at the design until it blurs. You should still be able to identify:

• The primary focal point (Level 1)
• The rough structure of sections (Level 2)

If multiple elements compete at the blurred view, the hierarchy is insufficient.

Step 5 — Test the 5-second test

Show the design to someone for 5 seconds, then hide it. Ask:

• What was the page about?
• What were you supposed to do?

If they cannot answer both questions, the hierarchy is failing.

Hierarchy in Web Component Patterns

Cards

Card title         → Largest, full contrast, H3 or similar weight
Supporting text    → Body size, reduced contrast
CTA / link         → Accent colour, medium weight
Metadata/date      → Small, lowest contrast

Navigation

Primary navigation items should be equal weight — no single item should dominate. The active/current item may be differentiated by colour or weight (not size).

Forms

Section heading    → Identifies form section
Label              → Names the field — should be clearly visible, not placeholder text
Input value        → Full contrast (user-entered content is highest priority)
Helper text        → Reduced contrast, small — supporting, not dominant
Error message      → Error colour (red), icon + text — must be noticeable

Hero sections

Eyebrow / label    → Small, uppercase, accent colour — sets context
H1 headline        → Dominant — the largest text on the page
Sub-headline/body  → Supports headline, softer weight or reduced contrast
Primary CTA        → High contrast filled button
Secondary CTA      → Ghost/outline or text link — must feel secondary

Hierarchy Anti-patterns

Whitespace Theory

Whitespace (also called negative space) is the empty area between and around elements in a composition. It is not an absence of design — it is an active design element that shapes how content is perceived, grouped, and prioritised.

The misunderstanding that whitespace is “wasted space” is the most common cause of cluttered, unprofessional-looking web design.

The Two Types of Whitespace

Macro whitespace

Large-scale empty space: the space between major sections, the margin around the main content container, the padding at the top and bottom of hero sections.

Function:

• Separates distinct content areas, preventing visual bleed between sections
• Creates breathing room that makes the overall page feel composed and professional
• Signals importance — a standalone quote with generous space above and below commands more attention than the same quote buried in a crowded section

Design application:

• Section vertical padding: typically 80–120px on desktop, 48–64px on mobile
• Space between a page header and the first section: generous — at least 48px
• Max-width content container with auto horizontal margins: prevents lines from spanning too wide

Micro whitespace

Small-scale empty space: the space between lines of text, between letters, between a label and its value, between an icon and its label, between list items.

Function:

• Controls readability — line height and paragraph spacing determine how comfortable body text is to read at length
• Creates visual grouping — related items have less space between them than unrelated items (Gestalt proximity)
• Adds quality signals — even 4px of additional padding inside a button lifts perceived quality

Design application:

• Line height (leading): 1.4–1.6× for body text; 1.1–1.3× for headings
• Paragraph spacing: 0.5–1× the body font size
• Letter spacing: 0.05–0.1em for uppercase labels; 0 or slightly positive for body text
• Icon-to-label gap: 6–8px
• Button padding: sufficient that the label does not feel cramped (typically 12–16px vertical, 20–28px horizontal for standard buttons)

Whitespace and Perceived Quality

Studies in interface design consistently show that designs with more whitespace are rated as more professional, trustworthy, and premium — regardless of colour or content.

Why:

• Whitespace signals confidence. Clutter signals anxiety — a fear that the message will not be heard unless everything is shouted at once.
• Luxury brands universally use abundant whitespace (Apple, Rolex, Hermès). Budget brands tend toward density (maximum product per inch).
• More whitespace = slower, more deliberate communication = higher perceived value per message.

The practical implication: If a design feels “cheap” or “amateurish” and the content is good, the solution is almost always more whitespace, not different colours or fonts.

Whitespace and Information Density

Different contexts call for different whitespace densities:

High density (less whitespace):

• Data tables, dashboards, spreadsheet-like interfaces
• Navigation menus with many items
• Developer/technical tools where information density is valued
• Mobile contexts where vertical space is scarce

Low density (more whitespace):

• Marketing and landing pages
• Luxury and premium brand sites
• Editorial and blog content
• Portfolio and showcase sites

The principle: Match whitespace density to the cognitive context of the user. A user making complex data comparisons needs density. A user being persuaded needs breathing room.

Whitespace as a Hierarchy Tool

Whitespace amplifies hierarchy when used deliberately:

More space above = start of a new section. Generous margin-top on a heading signals “new topic”. Tight margin-top suggests continuation.

More space around = greater importance. A single statistic with 64px of padding on all sides commands more attention than four statistics packed together.

Less space between = more related. A label immediately above its input (8px gap) is clearly paired. A label with 32px between it and the input looks disconnected.

Isolation = emphasis. A single pull quote floating in a full-width section with generous vertical padding receives more attention than any other element on the page because it has the most exclusive use of space.

Whitespace in Component Design

Buttons

• Insufficient padding: the label feels cramped; the button looks small and unconfident
• Standard padding: 12px 24px for a medium button (12px vertical, 24px horizontal)
• Premium/generous padding: 16px 32px — feels higher quality
• Minimum touch target: ensure the total rendered height is at least 44px even if the visual padding is smaller (use transparent padding or min-height)

Cards

• Padding inside the card creates containment — 24px is a comfortable default
• The gap between cards on a grid (gutter) should be consistent and come from the spacing scale
• Card border-radius combined with padding creates “air” that lifts the content away from the edge

Forms

• Space between form fields: 24–32px
• Space between label and input: 4–8px
• Space between input groups: 32–40px if no section divider; 48px+ if a new logical group
• Helper text sits immediately below its input (4–8px gap) — tight enough to associate clearly

Sections

• Vertical padding top/bottom: 80–120px on desktop; 48–64px on mobile
• Space between the section heading and the first content element: 32–48px
• Space between sub-elements within the section (e.g. feature cards): 24–32px

Typography

• Space above an H2: should be at least 1.5–2× the space below it — binding it to the content it introduces while separating it from the content above
• Paragraph spacing: margin-bottom: 1em on <p> tags
• List item spacing: gap: 0.5em or margin-bottom: 0.5em on <li> — depends on list context

Whitespace Anti-patterns

Practical CSS Starting Points

/* Section spacing */
.section {
  padding-block: 96px;
}
@media (max-width: 768px) {
  .section {
    padding-block: 56px;
  }
}

/* Content container */
.container {
  max-width: 1200px;
  margin-inline: auto;
  padding-inline: 24px;
}

/* Heading spacing — more above, less below */
h2, h3 {
  margin-top: 2em;
  margin-bottom: 0.5em;
}

/* Comfortable body text */
p {
  max-width: 65ch;
  line-height: 1.6;
  margin-bottom: 1.25em;
}

/* Card padding */
.card {
  padding: 24px;
}

The Whitespace Audit

When reviewing a design, ask:

1. Can I see where one section ends and another begins? If not, add section spacing.
2. Does the primary heading have breathing room? It should feel isolated and important.
3. Are related elements closer to each other than to unrelated elements? (Gestalt proximity)
4. Does any area feel crowded or anxious? Identify the densest area and increase spacing.
5. Does the design feel premium? If not, double the vertical padding on key sections and assess the change.
6. Is the body text readable over a sustained length? Check line height, line length, and paragraph spacing.

Generation Workflow

Step 1 — Discover design tokens

Search the codebase for CSS custom properties, theme files, and design tokens:

# Find CSS custom properties in :root / @theme blocks
grep -r "^\s*--" src/ --include="*.css" -n

# Find Tailwind config (v3: tailwind.config.js; v4: @theme in CSS)
find . -name "tailwind.config.*" -not -path "*/node_modules/*"
grep -r "@theme" src/ --include="*.css"

# Find font imports
grep -r "font-family\|@import.*font\|@font-face" src/ --include="*.css" -n

Collect all tokens into these categories:

• Colours (brand, semantic, surface, text, border)
• Typography (font families, weights, size scale)
• Spacing (padding, margin, gap tokens)
• Borders and radius
• Shadows and elevation
• Motion and transitions

Step 2 — Inspect existing components

Read 3–5 representative component/page files to understand how tokens are used in practice:

# Find the most complex page files (likely have all pattern variants)
find src/pages -name "*.tsx" -o -name "*.jsx" | head -5

# Find shared layout components
find src/components -name "*.tsx" -o -name "*.jsx" | head -10

For each file read, note:

• Button variants used (primary, secondary, ghost, outline)
• Card/panel patterns
• Section structure patterns
• Badge/label/tag patterns
• Any gradient or special text effects

Step 3 — Check dark mode implementation

grep -r "dark\|prefers-color-scheme\|\.dark\s" src/ --include="*.css" -n | head -20
grep -r "dark:" src/ --include="*.tsx" --include="*.jsx" | head -10

Note the dark mode strategy (class-based .dark, media query, or data attribute).

Step 4 — Check accessibility patterns

grep -r "aria-\|role=\|focus-visible\|visually-hidden\|sr-only" src/ --include="*.tsx" -n | head -20

Step 5 — Fill the structured extraction template

Before writing any markdown, populate templates/skill-output.yaml with every value discovered in Steps 1–4. This acts as a structured scratchpad and ensures no section is skipped.

Validate the populated YAML against schemas/design-reference.schema.json. All required fields must have real values (not TBD) before proceeding. Fields that are genuinely unknown may remain TBD but must be called out in the Step 8 report.

Step 6 — Generate docs/design/design-reference.md

Create the directory if it does not exist:

mkdir -p docs/design

Write the reference sheet using the template at references/design-reference-template.md, filling every section from the values in the populated skill-output.yaml. Replace {PROJECT_NAME} and all {TOKEN_*} placeholders with real values.

The template covers all 12 sections: Brand Identity, Colour Palette, Typography, Spacing System, Layout & Grid, Borders & Radius, Shadows & Elevation, Motion & Transitions, Component Patterns, Accessibility, Dark Mode, and Figma Sync Notes.

Step 7 — Generate .agents/skills/{project-slug}/SKILL.md

After generating the reference sheet, generate a companion enforcement skill using the template at references/enforcement-skill-template.md.

The skill must live under .agents/skills/ — not under docs/. Create the directory:

mkdir -p .agents/skills/{project-slug}

Use a lowercase-hyphenated slug derived from the project name (e.g. design-reference for Design & Bloom). Fill all {PROJECT_NAME} and section-specific placeholders from what was generated in Step 6. In Step 3 of the enforcement skill template, paste the 6–8 most important project-specific rules extracted from the reference sheet.

Step 8 — Confirm output

After writing both files, report to the user:

Generated:
  docs/design/design-reference.md              — 12-section design reference sheet
  .agents/skills/{project-slug}/SKILL.md       — enforcement skill for {PROJECT_NAME}

Sections populated from codebase:
  §2 Colours     — {n} tokens found in {file}
  §3 Typography  — {n} font roles, {n} scale entries
  §4 Spacing     — {n} tokens
  §9 Components  — {n} patterns extracted from {files}

TBD items requiring user input:
  §1 Brand Identity — personality, tagline not found in code
  (list any others)

To keep in sync: update docs/design/design-reference.md whenever
a token in {token file path} changes.