Skip to main content
Graphite UI

Spacing

Fourteen raw steps and three semantic density steps that alias into them. Components bind to a density step where one fits and reach for a raw step only when none does. Every row below is read from app/globals.scss and the kit snapshot when the page is built, and every bar is drawn with the token itself.

Contract 2.1.014 steps · 3 densityrem

The scale

14 of 14 steps match the kit’s Spacing collection. The kit stores px; the code writes the same value in rem, at px over 16.

Spacing scale
TokenValueKitDrawn at size
--graphite-space-0000px
--graphite-space-010.125rem · 2px2px
--graphite-space-020.25rem · 4px4px
--graphite-space-030.5rem · 8px8px
--graphite-space-040.75rem · 12px12px
--graphite-space-051rem · 16px16px
--graphite-space-061.5rem · 24px24px
--graphite-space-072rem · 32px32px
--graphite-space-082.5rem · 40px40px
--graphite-space-093rem · 48px48px
--graphite-space-104rem · 64px64px
--graphite-space-115rem · 80px80px
--graphite-space-126rem · 96px96px
--graphite-space-1310rem · 160px160px

--graphite-space-00 has no Carbon counterpart. The kit carries an explicit zero, so the code scale does too, and the rest of the steps keep Carbon’s index.

Reading the names

The suffix is a step index, not a size.

Density

Three semantic steps, each an alias into the raw scale. Change the alias and every component bound to that step moves with it.

Density steps
TokenAliasesSizeSpecimen
--graphite-density-compact--graphite-space-038px
--graphite-density-default--graphite-space-0516px
--graphite-density-spacious--graphite-space-0624px

Components that take density

Found by reading the governed component stylesheets for a density token. Zero bind to one today.

Usage rules

Quoted from the Spacing contract (2.1.0).

Rules

  • Components bind the raw --graphite-space-* steps the kit specifies. The density steps are a preview control, not a component binding.
  • The suffix is Carbon's step index, not a pixel value. --graphite-space-02 is step 2, which is 4px.

Never

  • Never use a spacing token as a border-radius. It is a category error the value diff cannot see, because the numbers agree. Use --graphite-radius-*.
  • Do not convert the scale to px. The rem is what makes it answer to a reader who has changed their root font size.

One compromise is recorded in the contract rather than fixed. A handful of declarations in globals.scss use the scale for things that are not spacing: box-shadow blur and offset, and transform distances. The kit has no shadow or motion distance scale to borrow instead, so they stay tokenised until it does.

Next steps

The two foundations that sit closest to this one, and the place to try density live.

  • Radius

    The other length scale, in px, where the suffix is the size.

  • Layout & grid

    Breakpoints, gutters and the 48px grid the site sits on.

  • Create

    Switch density and watch the components that take it follow.