Spacing System
Fluid spacing tokens (clamp) for components and sections
What is the Spacing System?
In BreakColorUI, spacing is a set of CSS variables that represent fluid spacing values (using clamp()). This lets your padding/gap/margin scale smoothly between small and large screens, without relying on breakpoints in your CSS.
Important
These tokens are meant to be defined globally (e.g. in :root / html:root via export), and then used anywhere with var(--...).
Two scales (component vs section)
The system has two token families to avoid “one spacing scale for everything”:
Component spacing (--hsp-*)
For internal padding, grid/flex gaps, and spacing inside UI components
Section spacing (--hss-*)
For spacing between sections and large layout blocks (hero, sections, vertical stacks)
7-step scale
Both scales use: XXS → XS → S → M → L → XL → XXL
Available tokens (CSS variables)
--hsp-xxs
--hsp-xs
--hsp-s
--hsp-m
--hsp-l
--hsp-xl
--hsp-xxl--hss-xxs
--hss-xs
--hss-s
--hss-m
--hss-l
--hss-xl
--hss-xxlWhen to use each scale
Use --hsp-* when…
…you’re defining spacing inside a component (padding, gap, small margins).
Use --hss-* when…
…you’re defining page rhythm and separation between sections / large blocks.
Common mistake
Don’t use --hss-* for button/card padding: the scale is larger and you’ll lose consistency. Likewise, don’t force --hsp-* for section spacing — it will feel “tight”.
How to use (CSS)
/* Component spacing: padding and gaps */
.button {
padding: var(--hsp-xs) var(--hsp-s);
}
.card {
padding: var(--hsp-l);
}
.form {
display: grid;
gap: var(--hsp-s);
}
/* Section spacing: vertical rhythm and sections */
.section {
padding-block: var(--hss-l);
}
.hero {
padding-block: var(--hss-xxl);
}Quick best practices
Use gap to space items inside stacks/grids and reserve margin for exceptions. Keep tokens as the “single source of truth” for consistency.
Where these variables should live
To work everywhere, spacing tokens should be defined globally — typically in html:root / :root. In BreakColorUI, this happens when you Export and paste the CSS into your project (or in Breakdance: Global Settings → Custom CSS).
html:root {
/* Component spacing */
--hsp-xxs: clamp(...);
--hsp-xs: clamp(...);
/* ... */
/* Section spacing */
--hss-xxs: clamp(...);
--hss-xs: clamp(...);
/* ... */
}Note about this project (Next + Tailwind)
In this app’s codebase you’ll see lots of p-*, gap-* and space-y-* (Tailwind). That’s just for the UI layout of this app. The Spacing System here refers to the exportable tokens (--hsp-* / --hss-*) you use in your own projects.
How it’s generated (in short)
Values are computed from a spacing configuration (min/max sizes, scale, and section multipliers) and converted into clamp(). The result is spacing that grows smoothly across viewports.
Recommended workflow
- 1. Configure spacing in the Dashboard (simple or advanced mode)
- 2. Export the updated CSS
- 3. Paste globally (Breakdance Global CSS or your project stylesheet)
- 4. Use
var(--hsp-*)andvar(--hss-*)in your components