CtrlK
BlogDocsLog inGet started
Tessl Logo

pantheon-ai/web-reference-sheet-generator

Generate a comprehensive web design reference sheet (docs/design/design-reference.md) and its companion enforcement skill (.agents/skills/{project-slug}/SKILL.md) for any website project. Extracts tokens from CSS files, validates completeness against a JSON schema scratchpad, inspects existing components, and produces a 12-section living document covering colours, typography, spacing, layout, borders, shadows, motion, component patterns, accessibility, dark mode, and Figma sync notes. Use when starting a new project, onboarding a design system, creating a Figma reference sheet, porting design tokens, or auditing existing styles. Triggers on: "create a design reference", "generate a style guide", "document the design tokens", "make a brand reference sheet", "create design docs", "port design tokens", "audit existing styles".

97

2.61x
Quality

100%

Does it follow best practices?

Impact

89%

2.61x

Average score across 3 eval scenarios

SecuritybySnyk

Passed

No known issues

Overview
Quality
Evals
Security
Files

whitespace-theory.mdreferences/

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

Anti-patternWhy it failsFix
No padding on mobile containersContent touches screen edge; feels unfinishedMinimum padding-inline: 16px
Equal spacing above and below headingsHeading floats between sections; unclear which it belongs toMore space above than below headings
Dense hero sectionsFeels cluttered; headline loses impactIncrease vertical padding; reduce number of elements
Removing whitespace to "fit more content"Reduces comprehension; reduces perceived qualityPrioritise content; remove what's less important rather than compressing
Inconsistent spacing between related elementsRandom gaps signal carelessnessApply spacing tokens; never eyeball gaps
Zero margin between sectionsSections bleed into each otherEvery section needs clear spatial separation
Tight letter spacing on body textReading fatigue; especially on long contentDefault or slightly positive letter-spacing for body

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.

SKILL.md

tile.json