Spacing

One scale

The base unit is 4px, expressed in rem so it follows the reader's font size instead of overriding it. Somebody who has set their browser to 20px because 16px is uncomfortable gets a page whose spacing grows with the text. A scale written in px would give them larger text crammed into the same gaps, which is worse than not scaling at all.

The steps are not linear. They double and half-step — .25 / .5 / .75 / 1 / 1.25 / 1.5 / 2 / 2.5 / 3 / 4 / 5 / 6 rem — because the eye reads ratios rather than differences. The difference between 4px and 8px is obvious; the difference between 80px and 84px is invisible. A linear scale spends most of its steps on distinctions nobody can see.

Two more tokens are fluid rather than fixed. --space-section is clamp(2.5rem, 1.4rem + 5.5vw, 6rem) and --space-gutter is clamp(1rem, .55rem + 2.2vw, 2rem). They are the page rhythm — the band of air around a section, and the breathing room at the edge of the viewport — and both are things that should be tighter on a phone and looser on a monitor without a media query picking where the line falls. .section and .container consume them for you.

The utilities are a subset, on purpose

Fourteen steps in the scale; seven with utilities: 0, 1, 2, 3, 4, 6, 8. There is no .p-5, no .mt-12, no .gap-24, and that is not an oversight waiting to be filled in.

The two halves of the scale get used by different things. The small end — 4px to 32px — is the distance between a label and its input, an icon and its text, a row and the next row. That is a nudge; it belongs to one place on one page, and typing it into the markup is quicker than naming it. The large end — 40px and up — is page rhythm: the band above a section, the inset of a hero. That is a decision about the whole page, it repeats, and it belongs in a rule with a name rather than scattered across forty elements as .mt-16.

So the seven steps cover the nudges and stop. If you find yourself wanting .p-12, the useful question is not "why is it missing" but "what is this element, and should it not be a .section, a .card, or a rule of your own reading var(--space-12)?" Every step of the scale is a public token whether or not it has a utility, and your own layer beats Deck with no !important:

@layer app.pages {
  .hero { padding-block: var(--space-12); }
}

Physical names, logical properties

The short utilities are named the way everyone expects and implemented the way Deck needs. .py-4 does not set padding-top and padding-bottom; it sets padding-block. .mt-4 sets margin-block-start. Nothing in Deck is written in physical properties, so an Arabic or Hebrew page mirrors completely from dir="rtl" with no second stylesheet.

That is also why there is no .ml-4 or .mr-4. Left and right are the two directions that actually flip, so naming them would build the bug in. The inline pair is spelled out instead.

.mis-auto and .mie-auto do the most work of the set. .mis-auto pushes an item to the far end of a flex row — it is what .push in the navbar is underneath. .mx-auto centres a block by splitting the leftover inline space evenly.

<div class="bar"><span class="badge">Start</span><span class="badge mis-auto">Pushed to the end</span></div>

Why gap beats margin

When you are spacing a run of siblings, set gap on the parent rather than a margin on the children. Four reasons, in ascending order of how much time they cost you.

1. The last one is wrong. .mb-4 on every child puts a margin under the final child too, so the group ends with a space that is not between anything. The usual fix is a :last-child reset, which is a rule you now have to write, name and remember.
2. Margins collapse; gaps do not. Adjacent block margins merge into the larger of the two, so .mb-4 above and .mt-2 below give you 1rem rather than 1.5rem. That is correct CSS and almost never what anyone intended. gap has no collapsing rules at all.
3. The spacing belongs to the group, not the item. A margin on a child is a claim about its surroundings made from inside it, so the same component spaces itself differently depending on where you drop it. A gap is set once by whatever is doing the arranging, which is the thing that actually knows.
4. It survives reordering. Wrap a row, reverse it, remove a child, insert one — the gaps stay right, because there is a single value and the layout applies it. Margins have to be re-reasoned every time the order changes.

Deck's layout primitives all set gap from a --gap custom property, so most of the time you do not want .gap-* at all — you want .stack-3 or .cluster-tight, which set the same thing by name. .gap-* is for a flex or grid container you built yourself.

<div class="stack stack-2">
  <div class="card"><div class="card-body">First</div></div>
  <div class="card"><div class="card-body">Second</div></div>
  <div class="card"><div class="card-body">Third, with no trailing space under it</div></div>
</div>

The exception is one element that needs to sit away from one specific neighbour — a back link above a heading, say. That is a real margin: it is about those two elements and not about a group, and .mt-6 is the right tool for it.

Safe areas

Three padding utilities read env(safe-area-inset-*) instead of the scale, for the rounded corners and the home indicator on a phone. They are the only spacing in Deck that changes with the device rather than the design, and they are zero on every screen without a notch — so adding one costs nothing where it is not needed.

.safe-x takes the larger of the gutter and the inset, so text never ends up tighter to the edge than the rest of the page. All three need viewport-fit=cover in the viewport meta tag, which the starter page and Deck::head() both emit.

Spacing that follows the container

.pad-cq and .gap-cq scale with the width of the nearest container rather than the viewport, using cqi units clamped to the ends of the scale. A card in a narrow sidebar takes the small value and the same card in a wide main column takes the large one, with no media query and no second class.

Both only apply inside an element marked .cq. Outside one they do nothing whatsoever, which is why the rows below lead with the selector that carries the rule rather than with the class on its own.

Padding

.p-* sets all four sides, .px-* the inline axis, .py-* the block axis.

One side at a time

Four families, all logical: inline start and end, block start and end. Twenty eight classes that exist so you never have to write a physical padding-left into a page that might be read right to left.

Margin

Deliberately a smaller set than the padding one. There is no .m-4, only .m-0, because a margin on all four sides of something is nearly always a padding on its parent. The block pair covers "space this away from the thing above it", and the inline pair is there for the alignment tricks.

Gap

gap applies to flex, grid and multi-column containers. On anything else it is inert, which makes .gap-3 on a plain <div> a silent no-op and the commonest way to lose ten minutes with these. Check that the parent is really a flex or grid container first.

When not to use these

• Not for the space between siblings. That is .stack-*, .cluster or .grid, each of which sets a gap for you. A column of .mb-4 is a stack written the long way.
• Not for page rhythm. .section already applies --space-section, and it is fluid. Replacing it with .py-8 pins the band at 2rem on a 27 inch monitor.
• Not for the viewport edge. .container applies --space-gutter on the inline axis. Adding .px-4 on top of it double-pads the page.
• Not to fix a component. If a card needs a nudge to look right, the card is wrong, and every other card on the site is wrong the same way. Fix it once in your own layer.
• Not as .ml-* or .mr-*. Those do not exist. Use .mis-* and .mie-*, which flip correctly when the page does.