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
100%
Does it follow best practices?
Impact
89%
2.61xAverage score across 3 eval scenarios
Passed
No known issues
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.
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:
Design application:
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:
Design application:
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:
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.
Different contexts call for different whitespace densities:
High density (less whitespace):
Low density (more whitespace):
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 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.
12px 24px for a medium button (12px vertical, 24px horizontal)16px 32px — feels higher qualitymin-height)margin-bottom: 1em on <p> tagsgap: 0.5em or margin-bottom: 0.5em on <li> — depends on list context| Anti-pattern | Why it fails | Fix |
|---|---|---|
| No padding on mobile containers | Content touches screen edge; feels unfinished | Minimum padding-inline: 16px |
| Equal spacing above and below headings | Heading floats between sections; unclear which it belongs to | More space above than below headings |
| Dense hero sections | Feels cluttered; headline loses impact | Increase vertical padding; reduce number of elements |
| Removing whitespace to "fit more content" | Reduces comprehension; reduces perceived quality | Prioritise content; remove what's less important rather than compressing |
| Inconsistent spacing between related elements | Random gaps signal carelessness | Apply spacing tokens; never eyeball gaps |
| Zero margin between sections | Sections bleed into each other | Every section needs clear spatial separation |
| Tight letter spacing on body text | Reading fatigue; especially on long content | Default or slightly positive letter-spacing for body |
/* 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;
}When reviewing a design, ask: