Layout and responsive

Lay out pages with Container, Flex and the spacing scale, and design for each breakpoint.

Neighborhood pages are built from sections stacked down the page. Section components handle their own inner layout at every screen size; Container, Flex and the spacing scale handle the space around and between them.

Breakpoints

Layouts change at these widths. Each applies from its width upward.

Breakpoint	Token suffix	Utility prefix	From
XS		`nbhd:xs:`	375px
SM	`bpSm`	`nbhd:sm:`	544px
MD	`bpMd`	`nbhd:md:`	768px
LG	`bpLg`	`nbhd:lg:`	1024px
XL	`bpXl`	`nbhd:xl:`	1200px
XXL		`nbhd:xxl:`	1300px

Design and build mobile first: start with the smallest screen, then add changes at larger breakpoints. In your own CSS, write the pixel value in media queries, since custom properties can’t be used there:

.promo {
  padding-inline: var(--nbhd-space-4);

  @media (min-width: 768px) {
    padding-inline: var(--nbhd-space-8);
  }
}

Breakpoints lists the breakpoint tokens. Storybook’s viewport menu previews each breakpoint.

Container

Container keeps content to a readable width and adds space at the sides:

It centers its content, up to the brand’s maximum width: 1300px by default, 1800px on Moen.
It adds side padding of space 6 on small screens, growing to space 12 from MD.
It can set a surface for everything inside it. By default it has none.

<nbhd-container>
  <nbhd-text>Content stays centered and padded at every screen size.</nbhd-text>
</nbhd-container>

Many section components, such as Headline Content and Hero Split, already include a container. Their compact setting limits them to the same maximum width; without it, their background runs the full width of the page.

Flex

Flex arranges components in a row or a column:

By default, it stacks its children in a column.
split places them side by side from LG (1024px), spaced apart, and stacks them on smaller screens.
reverse flips the order. With split, the second item comes first.
justify-content and align-items set alignment, using the same values as CSS.

<nbhd-flex split align-items="center">
  <nbhd-text tag="h2" variant="title">Find your finish</nbhd-text>
  <nbhd-cta href="/finishes">Compare finishes</nbhd-cta>
</nbhd-flex>

Flex doesn’t add space between its children. Give them margins from the spacing scale, or use the section components’ spacing settings.

Space between sections

Section components have spacing settings, so you can set the rhythm of a page without writing CSS:

Setting	Values
`margin-top`, `margin-bottom`	`none` (the default), `small`, `medium`, `large`
`padding-top`, `padding-bottom`	`default` (the component’s own padding), `none`, `small`, `medium`, `large`

The values come from the space scale:

Value	Token	Default size
`small`	`--nbhd-space-6`	24px
`medium`	`--nbhd-space-12`	48px
`large`	`--nbhd-space-24`	96px

The sizes follow the brand’s spacing step, so small is 24px by default and 30px on Moen.

<nbhd-headline-content margin-bottom="large">…</nbhd-headline-content>
<nbhd-hero-split padding-top="none">…</nbhd-hero-split>

To separate sections that sit next to each other, alternating surfaces often works better than adding more space. See Designing with surfaces.

Spacing in your own CSS

Use the space scale, --nbhd-space-0 to --nbhd-space-40, for spacing in your own CSS:

Use gap on flex and grid parents, instead of margins on each child.
Use logical properties, such as margin-block-end and padding-inline. See Styling.
Pick steps that relate. A section that uses space 6 inside often uses space 12 around it.

Spacing shows the full scale, and Neighborhood CSS has the same scale as utilities, such as nbhd:gap-4 and nbhd:md:p-8.

Check every breakpoint

Before a page goes live, check it at XS, MD and XL at least:

Content reflows without scrolling sideways.
Long titles still read well when they wrap onto several lines.
Images stay sharp and are cropped where you expect.
Order makes sense when side-by-side layouts stack.