Add Stack component

[vdepizzol]

What are you trying to accomplish?

This PR adds the Stack component to Primer CSS.

A Stack component lays elements horizontally or vertically on the page.

Stack is a simple abstraction of CSS’ Flexbox. Use it to structure elements that are visually grouped and follow the same direction.

Overview

This is the first Layout helper component¹ to be designed and implemented following the new Responsive API design guidelines².

Layout helper components have been proposed as a way to reduce our dependency on utilities, make it easier to implement responsive design, and support the new Primer Primitives design tokens.

Layout helper components are designed in a platform-agnostic way. They will be available to both Primer ViewComponents and Primer React with the same behavior and API.

Features

Stack makes it easy to group elements that follow a same direction (vertically or horizontally), with spacing gap, optional dividers, and optional wrapping.

Responsive by design

All properties from this component are responsive, meaning different values can be passed depending on the viewport range.

For example, a Stack direction can be set to inline (horizontal) on narrow, and block (vertical) on desktop.

In CSS, we use -whenNarrow, -whenRegular, and -whenWide suffixes to target modifier classes to a specific range. This is how the team is planning to support any responsive properties going forward.

More information about viewport ranges can be found here (only available for Hubbers, documentation to be made public in a future PR).

Alignment and distribution of stacking elements

Stack also allows aligning elements without relying on difficult Flexbox property names (align-items, justify-content, and align-content). For that, it uses simpler concepts such as align and spread (described in the Properties section below).

<!-- Vertical stacking, with elements aligned to the right -->
<Stack direction="block" align="end">
  <div class="Box">Element 1</div>
  <div class="Box">Element 2</div>
  <div class="Box">Element 3</div>
</Stack>

<!-- Horizontal buttons, positioned to the right -->
<Stack direction="inline" spread="end">
  <button>Cancel</button>
  <button>Save</button>
</Stack>

Note on using inline Stack for buttons

In the future we may have specialized stacking components for controls using the UI control stack tokens.

In the meantime, we can use these tokens with a custom gap:

<Stack direction="inline" spread="end" gap="var(--primer-controlStack-medium-gap-auto)">
  <button>Cancel</button>
  <button>Save</button>
</Stack>

Properties

Stack has the following properties:

direction

Sets how elements inside Stack are placed, either horizontally (inline) or vertically (block). This property follows the writing mode.

gap

Sets the spacing gap between items. All sizes use design tokens from the new Primer Primitives' UI Stack pattern.

Values:

• none: 0
• condensed: var(--primer-stack-gap-condensed, 8px),
• normal: var(--primer-stack-gap-normal, 16px) (default)
• spacious: var(--primer-stack-gap-spacious, 24px) (on regular viewports, otherwise it appears as normal on narrow viewports)

Custom values are not supported for now.

align

Sets the alignment between items in the cross-axis of the specified direction. For example:

• If direction is set to block (stacks vertically), it controls the horizontal alignment (left, center, right).
• If direction is set to inline (stacks horizontally), it controls the vertical alignment (top, center, bottom).
  
  This property behavior is equivalent to the align-items Flexbox property.

Values:

• stretch (default)
• start
• center
• end
• baseline

alignWrap

Sets how stack lines are distributed, if they wrap into multiple lines. This has equivalent behavior to the align-content Flexbox property.

(Most instances of Stack shouldn't require this property)

Values:

• start (default)
• center
• end
• distribute (equivalent behavior to Flexbox's space-between)
• distributeEvenly (equivalent behavior to Flexbox's space-evenly)

spread

Sets how items will be distributed in the stacking direction.

Values:

• start (default)
• center
• end
• distribute (equivalent behavior to Flexbox's space-between)
• distributeEvenly (equivalent behavior to Flexbox's space-evenly)

wrap

Sets whether items are forced onto one line or can wrap onto multiple lines.

Values:

• wrap
• nowrap (default)

showDividers

Boolean. Whether dividers are present between items or not.

Note: dividers are not compatible in wrapping stacks.

Note 2: the presence of a divider duplicates the gap between items.

dividerAriaRole

Sets which ARIA role will be used for the divider.

Values:

• presentation (default)
• separator

Structure

.Stack
├─ &.Stack--dir-[ inline | block ]-[ whenNarrow | whenRegular | whenWide ]
├─ &.Stack--gap-[ none | condensed | normal | spacious ]-[ whenNarrow | whenRegular | whenWide ]
├─ &.Stack--align-[ start | center | end | baseline ]-[ whenNarrow | whenRegular | whenWide ]
├─ &.Stack--alignWrap-[ start | center | end | distribute | distributeEvenly ]-[ whenNarrow | whenRegular | whenWide ]
├─ &.Stack--spread-[ start | center | end | distribute | distributeEvenly ]-[ whenNarrow | whenRegular | whenWide ]
├─ &.Stack--wrap-[ whenNarrow | whenRegular | whenWide ]
├─ &.Stack--nowrap-[ whenNarrow | whenRegular | whenWide ]
├─ &.Stack--showDividers-[ whenNarrow | whenRegular | whenWide ]
│
├─ .Stack-divider
├─ .Stack-item
│  ├─ &.Stack-item--expand-[ whenNarrow | whenRegular | whenWide ]
│  ├─ &.Stack-item--keepSize-[ whenNarrow | whenRegular | whenWide ]

Storybook

You can play with Stack in Storybook. By default it comes with _debug set to true, so you can see how the elements are positioned.

✨ Link to Storybook ✨

Can these changes ship as is?

• Yes, this PR does not depend on additional changes. 🚢

Footnotes

1. Discussion on Layout helper components (only available for Hubbers) ↩

2. Responsive API design guidelines ADR (only available for hubbers, but content will be made public in a future PR) ↩

[changeset-bot]

🦋 Changeset detected

Latest commit: 2795894

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/css	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR