This skill should be used when the user is adjusting spacing, padding, margins, content density, section gaps, vertical rhythm, or separation between elements. Also applies when reviewing whether a design feels cramped or too sparse, choosing between borders and whitespace for separation, or defining a spacing system. Covers the 4px/8px spacing system, macro vs micro whitespace, content density spectrum, separation techniques (whitespace > background shifts > borders), and vertical rhythm.
npx claudepluginhub oborchers/fractional-cto --plugin visual-design-principlesThis skill uses the workspace's default tool permissions.
Whitespace is not empty space -- it is active structure. Research by Wichita State University found that increased whitespace between paragraphs and around margins improved comprehension by 20%. The Refactoring UI principle is clear: start with too much whitespace, then remove until it feels right. Never start tight and try to add space later.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Whitespace is not empty space -- it is active structure. Research by Wichita State University found that increased whitespace between paragraphs and around margins improved comprehension by 20%. The Refactoring UI principle is clear: start with too much whitespace, then remove until it feels right. Never start tight and try to add space later.
Macro whitespace is the space between major sections, around the content frame, and between layout regions. It establishes page-level breathing room and visual grouping.
Micro whitespace is the space within components -- between a label and its input, between list items, between an icon and its text. It determines readability and component density.
Both must be intentional. Macro whitespace without micro whitespace produces elegant-looking layouts with unreadable components. Micro whitespace without macro whitespace produces readable components floating in a cramped sea.
Define a constrained spacing scale using a 4px base unit. Every spacing value in the system must come from this scale.
:root {
--space-1: 4px; /* micro: icon-text gap */
--space-2: 8px; /* micro: inline element gap */
--space-3: 12px; /* micro: related element gap */
--space-4: 16px; /* standard component padding */
--space-5: 20px; /* component internal sections */
--space-6: 24px; /* between related components */
--space-8: 32px; /* between distinct components */
--space-10: 40px; /* compact section gap */
--space-12: 48px; /* standard section gap */
--space-16: 64px; /* generous section gap */
--space-24: 96px; /* premium section gap */
--space-32: 128px; /* hero/premium section gap */
}
| Context | Whitespace % | Example |
|---|---|---|
| News sites | 20--30% | CNN, Reuters |
| SaaS dashboards | 25--35% | Datadog, Grafana |
| Corporate / SaaS marketing | 35--45% | Stripe docs, GitHub |
| Premium / luxury | 50--65% | Apple product pages |
| Apple homepage hero | 60--70% | apple.com |
Use the lightest-weight separation technique that works. Heavier separators add visual noise.
Prefer in this order:
--color-bg-subtle)Borders are visual clutter. Every border competes for attention. Use them only when spacing alone cannot communicate grouping.
Internal spacing must be no more than 50% of external spacing. This is Gestalt proximity: elements that are closer together are perceived as belonging together.
| Relationship | Spacing |
|---|---|
| Within a group (internal) | --space-2 to --space-4 |
| Between groups (external) | --space-6 to --space-12 |
| Between sections | --space-12 to --space-32 |
If the gap between a label and its input is the same as the gap between two form groups, the user cannot parse the structure at a glance.
| Density | Section Gap | Use Case |
|---|---|---|
| Compact | 32--48px | Dashboards, data-heavy apps |
| Standard | 64--96px | SaaS marketing, documentation |
| Premium | 96--128px+ | Landing pages, brand sites |
Vertical rhythm rule: Section gap standard deviation must be 8px or less. Inconsistent section gaps destroy the sense of structure. Pick one gap value per page density and use it everywhere.
| Anti-Pattern | Problem | Fix |
|---|---|---|
| Edge-to-edge cramming | Content touching container edges | Add --space-4 to --space-6 padding minimum |
| Borders everywhere | Visual noise, heavy feel | Replace with whitespace or background shifts |
| Inconsistent spacing | No visual rhythm, feels unpolished | Use the spacing scale exclusively |
| Claustrophobic layouts | Users feel overwhelmed | Start with 2x the spacing you think you need |
| Equal internal/external gaps | Groups unreadable | Internal spacing <= 50% of external |
Working implementations in examples/:
examples/spacing-system-and-separation.md -- Complete spacing system in CSS/Tailwind/React, demonstrates separation without bordersWhen reviewing or building spacing and density: