Spacing System & 8px Grid
A base-8 spacing scale that makes padding, margin, and gap decisions automatic and consistent.
Design TokensBeginner
Why
Random padding (13px, 17px, 22px) creates visual jitter and makes 'align this' a manual fight. An 8px-base scale gives 6-8 values that cover every need and make alignment automatic.
Tokens Studio (formerly Figma Tokens) has 500k+ installs, and the W3C Design Tokens Format Module is nearing candidate recommendation. Tokens enable dark mode, multi-brand theming, and platform parity from a single source.
When
Adopt a spacing scale on day one — it's the cheapest, highest-leverage token set. If you have 30+ unique padding values, audit and snap them to the scale.
How
1. Pick a base — 8px (0.5rem); 4px allowed for fine-tuning icons only
2. Generate scale — 0, 4, 8, 12, 16, 24, 32, 48, 64 (×1.5 steps after 16)
3. Name them — xs=4, sm=8, md=12, lg=16, xl=24, 2xl=32, 3xl=48, 4xl=64
4. Apply to everything — padding, margin, gap, component height all use the scale
5. Component sizing — control height = 40px (lg+sm), card padding = 24px (xl)
6. Tailwind — map to p-1..p-16, or use the default 4px scale (p-2 = 8px)
7. Enforce — stylelint-declaration-strict-value bans raw px outside the scale
Example
// spacing-tokens.ts — 8px base scale
export const space = {
0: "0",
xs: "0.25rem", // 4px — icon internal
sm: "0.5rem", // 8px — tight gap
md: "0.75rem", // 12px — default gap
lg: "1rem", // 16px — card internal
xl: "1.5rem", // 24px — card padding
"2xl": "2rem", // 32px — section gap
"3xl": "3rem", // 48px — page gap
"4xl": "4rem", // 64px — hero gap
} as const;
/* Card.tsx — every dimension from the scale */
.card {
padding: var(--space-xl); /* 24px */
gap: var(--space-md); /* 12px */
border-radius: var(--radius-md); /* 8px */
box-shadow: var(--shadow-sm);
}
/* stylelint config — ban raw px */
"declaration-property-value-allowed-list": {
"/^(padding|margin|gap)/": ["/var\\(--space/", "0"]
}
Common Problems
- ⚠Off-grid values — 13px padding to 'nudge' alignment, breaks the whole grid rhythm
- ⚠Scale too granular — 20 spacing values, designers can't decide which to use
- ⚠Mixed bases — 8px for padding, 6px for icons, 10px for type, nothing aligns
Best Practices
- ✓One base, 8 values max — covers 95% of needs, decisions become automatic
- ✓Snap existing values to the scale — 13px→12px, 22px→24px, never keep off-grid
- ✓Enforce via stylelint — ban raw px in padding/margin/gap, CI fails on violations