Stack

When to use it

Use it whenever two or more things sit one above another and need space between them. That is most of a page.

<div class="stack">
  <h3>Export finished</h3>
  <p>2,481 rows written to invoices-2026-03.csv.</p>
  <button class="btn btn-primary">Download</button>
</div>

Why gap instead of margins

This is the argument the rest of Deck rests on, so it is worth making properly. Spacing something with margins means writing a rule for every element that might sit next to every other element. The usual approach is the lobotomised owl — * + * { margin-block-start: 1rem } — and it works, but it has four problems that a gap does not.

<div class="split">
  <div class="card"><div class="card-body"><div class="stack stack-2">
    <span class="badge">Three items</span>
    <p>First</p><p>Second</p><p>Third</p>
  </div></div></div>
  <div class="card"><div class="card-body"><div class="stack stack-2">
    <span class="badge">Last one hidden</span>
    <p>First</p><p>Second</p><p hidden>Third</p>
  </div></div></div>
</div>

The honest counter-argument: gap needs a flex or grid container, so it cannot space arbitrary elements in normal flow. Deck accepts that and uses a container almost everywhere. Where you genuinely have flow content you do not control — rendered Markdown, a CMS body — use .prose, which is the one place Deck does set margins on descendants.

The spacing scale

Every spacing utility in Deck uses the same seven steps. A step that exists in one family exists in all of them, so .stack-3, .gap-3, .p-3 and .mt-3 are all the same distance.

<div class="grid grid-tight">
  <div class="card"><div class="card-body">
    <div class="stack stack-1"><span class="badge">stack-1</span><div class="skeleton" style="block-size:1.5rem"></div><div class="skeleton" style="block-size:1.5rem"></div><div class="skeleton" style="block-size:1.5rem"></div></div>
  </div></div>
  <div class="card"><div class="card-body">
    <div class="stack stack-3"><span class="badge">stack-3</span><div class="skeleton" style="block-size:1.5rem"></div><div class="skeleton" style="block-size:1.5rem"></div><div class="skeleton" style="block-size:1.5rem"></div></div>
  </div></div>
  <div class="card"><div class="card-body">
    <div class="stack stack-6"><span class="badge">stack-6</span><div class="skeleton" style="block-size:1.5rem"></div><div class="skeleton" style="block-size:1.5rem"></div><div class="skeleton" style="block-size:1.5rem"></div></div>
  </div></div>
</div>

How one class is configurable

.stack declares gap: var(--gap, var(--space-4)), and every step class sets nothing but --gap. Three consequences follow, and they are what make the pattern worth copying:

• The step classes are one declaration each, so the whole family costs almost nothing in the stylesheet.
• A value the scale does not have is style="--gap:3.5rem", with no new class and no !important.
• --gap is shared with .cluster, .grid, .split, .scroller and .center — so .stack-6 on a .grid works, because both read the same property.
• A step class on its own does nothing. It sets a property and nothing reads it, so class="stack-3" without .stack renders as an ordinary block with no gap at all — and fails silently, because the class is real. Write both: class="stack stack-3". The same goes for .card-body, which sets a fixed gap of its own that a step class cannot change; nest a .stack inside it instead, as the example below does.

<div class="stack" style="--gap:3.5rem">
  <div class="skeleton" style="block-size:1.5rem"></div>
  <div class="skeleton" style="block-size:1.5rem"></div>
</div>

Because the step classes only set a custom property, .stack-2 on a .cluster does exactly what .cluster-tight does. That is convenient and slightly untidy — see cluster, where the two naming schemes meet.

Centred columns

.center is .stack with align-items: center and text-align: center. It reads the same --gap, so the step classes work on it unchanged.

<div class="center stack-3">
  <span class="avatar avatar-lg">SR</span>
  <h3>No projects yet</h3>
  <p class="text-muted">Create one to get started.</p>
  <button class="btn btn-primary">New project</button>
</div>

align-items: center also stops children from stretching to the full width, which is why the button above is its natural size rather than full width. In a plain .stack it would stretch.

Classes

Generated from src/04-layout.css by tools/docs/extract.mjs.

Tokens

The seven steps the utilities use, plus the two computed spacings that the page-level classes read.

Accessibility

• A stack has no semantics. It is a <div> with display: flex and no role. Put it on a <ul>, <section> or <form> when the grouping means something; the styles do not care what element they are on.
• Flex changes nothing about reading order as long as you do not reorder. flex-direction: column keeps DOM order, so what a screen reader hears matches what a sighted reader sees.
• Never use order or row-reverse to fix a layout. Both leave the DOM order — which is the tab order and the reading order — pointing one way while the visual order points the other. If the order is wrong, the markup is wrong.
• .stack on a <ul> can silence the list. Some Safari and VoiceOver combinations drop list semantics when display: flex is applied. Add role="list" back if the item count matters.
• Spacing is not a separator. A large gap groups things visually and says nothing to a screen reader. If two groups are genuinely distinct, use a heading or a <section>, not .stack-8.
• Gap does not scale with text size unless the token does. Deck's steps are in rem, so they grow with the reader's root font size — a stack set in pixels would not, and a page zoomed to 200% would have text touching.

Right to left

Nothing to do. gap is not a directional property, and a column stack has no start or end edge to mirror. This is one of the clearest cases for gap over margin: margin-block-start would need no RTL rule either, but margin-left on a row would, and a gap never gives you the chance to write the wrong one.

Reduced motion

Nothing about a stack animates or transitions, so prefers-reduced-motion changes nothing here.

Printing

src/99-print.css has no rule for .stack, which is deliberate — a flex column with a gap prints correctly as it is. The layout classes that are unwound for print are .grid and .split, which become display: block so that content can break across pages instead of being trapped in a fixed track.

Overriding it

/* One stack, no layer needed */
<div class="stack" style="--gap:3.5rem">

@layer app.components {
  /* A step the scale does not have, if you need it repeatedly */
  .stack-12 { --gap: var(--space-12); }

  /* A different default for every stack on the site */
  .stack { gap: var(--gap, var(--space-3)); }
}

Prefer setting --gap over setting gap: the custom property is what every step class writes to, so a --gap override composes with them and a flat gap override silently beats them.

When not to use it

• Not for a row. Use .cluster, which wraps, or .bar, which does not. A .stack with flex-direction: row overridden is a cluster you have to maintain.
• Not for content you did not write. Rendered Markdown, a CMS body or a WYSIWYG field arrives as flow content with its own margins. Use .prose, which sets the vertical rhythm on descendants — the one place Deck accepts margins, because there is no container to put a gap on.
• Not for a page's outer rhythm. Use .section, whose padding is a clamp() that grows with the viewport. A fixed .stack-8 between page sections is too much on a phone and too little on a monitor.
• Not when the items should share a row when there is room. That is .grid, which reflows on its own width. A stack is always one column.
• Not to fake a separator. If the reader needs to know two groups are different, give them a heading or an <hr>. Extra space is invisible to anyone not looking at the screen.