The Spacing System Generator turns a single base unit into a full, predictable spacing scale you can drop straight into a stylesheet or a Tailwind config. Pick a base value, choose how the steps grow, and it emits ready-to-paste CSS custom properties plus a matching theme.spacing object. Because every value derives from one number, the whole scale stays coherent instead of accreting one-off margins and paddings.
Under the hood, a spacing scale is just a named set of length tokens you apply to properties like margin, padding, gap, and inset. Instead of writing padding: 14px in one file and padding: 16px in another, you reference --space-4 and the intent becomes both consistent and adjustable. Storing the tokens as CSS variables means one edit at :root cascades everywhere, and gap on flex/grid containers plus logical properties like margin-block and padding-inline can all read from the same source of truth.
The generator supports three growth curves. A linear scale (base times an integer: 4, 8, 12, 16) is easy to reason about and dense at small sizes. A geometric scale multiplies each step by a fixed ratio such as 1.5, giving a modular, exponential rhythm that pairs well with a type scale. A Fibonacci scale (4, 8, 12, 20, 32) accelerates on its own and is useful when you want visibly distinct tiers without hand-tuning every stop.
Generating your scale
- 1
Set the base unit. Most systems use 4px or 8px because they divide cleanly on standard displays and align with common component and touch-target heights; enter whatever grid your design uses.
- 2
Choose the progression: linear for uniform increments, geometric for a constant ratio (set the multiplier, e.g. 1.5 or 1.618), or Fibonacci for an accelerating curve.
- 3
Pick how many steps you need. A typical UI wants 8 to 12 tokens spanning from a hairline gap up to large section padding.
- 4
Copy the output in your target format: :root CSS custom properties (--space-1 through --space-n) or a Tailwind theme.spacing object to extend in tailwind.config.
- 5
Wire the tokens into your components using gap, padding, and margin instead of raw pixel values, so future tweaks happen in one place.
When to reach for it
Bootstrapping a design system
You are defining foundations for a new product and need spacing tokens that sit alongside color and type scales. Generate the scale once and expose it as CSS variables that every component library consumes.
Migrating a Tailwind project off arbitrary values
A codebase littered with p-[13px] and mt-[27px] resists any global adjustment. Replace them with a generated theme.spacing scale so utilities like p-4 and gap-6 map to deliberate steps.
Aligning design and engineering
Designers work on an 8px grid in Figma while code drifts to ad-hoc values. A shared generated scale gives both sides the same named steps and removes pixel-by-pixel arguments in review.
Retrofitting consistent rhythm
An existing UI feels uneven because vertical spacing was eyeballed. Swapping loose values for a geometric or Fibonacci scale restores a visible hierarchy between tight and generous gaps.
Practical notes and pitfalls
- Consider converting tokens to rem so spacing scales with the user's root font size; if you keep px, be aware that vertical rhythm will not respond to browser zoom of text-only settings the way rem does.
- Geometric scales produce fractional pixels (4 * 1.5^3 = 13.5px). Browsers render sub-pixel spacing, but rounding across many elements can cause 1px drift; round to half-pixels or nearest whole values if you need pixel-snapping.
- Prefer gap on flex and grid containers over margins between children. Gap avoids the margin-collapsing and first/last-child edge cases that plague sibling margins, and it reads from the same token.
- Do not over-generate. A scale with 20 nearly identical steps invites inconsistency; 8 to 12 well-separated tokens is easier to apply correctly, which is exactly why an exponential curve often beats a linear one at the large end.
- Reach for logical properties (padding-inline, margin-block) with your tokens so the same spacing works in right-to-left layouts without a separate stylesheet.
Common questions
Should I base my spacing scale on 4px or 8px?+
Both are common. An 8px base keeps the scale coarse and quick to apply, while a 4px base gives finer control for dense UI and small components. Many teams use a 4px base but only surface every other step in day-to-day use.
What is the difference between a linear and a geometric spacing scale?+
A linear scale adds a fixed amount each step (4, 8, 12, 16), so increments stay constant. A geometric scale multiplies by a fixed ratio (4, 6, 9, 13.5 at 1.5x), so gaps grow proportionally and create more contrast between small and large spacing.
Should spacing tokens use px or rem?+
Use rem when you want spacing to scale with the user's font-size preference, which helps accessibility and zoom. Use px when you need spacing fixed regardless of text size, such as hairline borders or icon padding. Many systems mix both.
How do I use the generated CSS variables?+
Paste the :root block into your global stylesheet, then reference the variables anywhere a length is valid, e.g. padding: var(--space-4) or gap: var(--space-6). Because they live on :root, changing one value updates every usage.
How do I add the scale to Tailwind?+
Copy the theme.spacing object into tailwind.config.js. You can either extend the defaults under theme.extend.spacing to keep Tailwind's built-in steps, or replace theme.spacing entirely to enforce only your tokens through utilities like p-4 and gap-6.
How many steps should a spacing scale have?+
Most interfaces are well served by 8 to 12 steps, from a small 2-4px gap up to large section padding of 64px or more. Fewer steps enforce consistency; too many make it easy to pick subtly different values that look like mistakes.