skip to content
menu
components · box
componentslayout & structurereact implementation

box

A box is the simplest building block of a layout: a square frame that puts space around its content. It can also give that content a background and a thin border.

storage-01

when to use

  • To put space around a part of the page in the fixed steps of the space scale, instead of writing your own CSS.
  • To set a part of the page on another shade of the canvas, such as a darker, sunken area inside a panel.
  • To frame something with a hairline, when the header and footer of a card would be too much.

when to use something else

  • For a group of content with a title. Use a card: the header, the line below it, the footer and the usual padding come with it.
  • For the space between things that sit side by side or one above another. Use a stack and its gap. Padding or margins on each of them drift off the scale.
  • For a line between sections. Use a divider.
  • For something people click. A box isn't a control: it can't take focus, and the keyboard can't use it. An action is a button; an entry on the home page is a tile.

anatomy

  1. Frame. Square and never rounded, like every frame (see shape). It has no padding, background or border unless you ask for them.
  2. Padding (optional). Space inside the frame: on every side, on the left and right, or on the top and bottom. Each is a step of the space scale.
  3. Background (optional). One of the four shades of the canvas.
  4. Border (optional). A hairline on every side.

variants and states

Padding comes in the steps of the scale, and there is no default: a box has no padding until you give it some.

p 8
p 16
p 24
p 32

The left and right can take a different step from the top and bottom.

px 32 / py 8
px 8 / py 24

The background is one of the four shades of the canvas. Without one, the box is transparent, and whatever is behind it shows through.

bg
bg-2
surface
surface-2

Boxes nest: a darker, sunken area can sit inside a lighter panel.

Release 2.4.1
pipeline #1543 passedrollout ready, 3 of 3p95 142ms

behaviour

  • A box takes no focus and has no action. tab passes over it, and moves through what is inside it, in order.

The full keyboard map is on the box's React page.

accessibility

  • A box adds no structure for assistive technology: it has no role and no name.
  • Landmarks and other named regions are up to you. A region that people should be able to find by its name needs a role, and that name.
  • The border is a decorative hairline, faint on purpose: it has less contrast than the edge of a control needs (see shape). So a box's border must never be the only thing that marks a control or a selected item.
  • A background changes nothing else. The text inside keeps its own colour, and every text colour has enough contrast on all four backgrounds.

content

A box has no text of its own. Keep what is inside it about one thing. If it needs a title, it is a card.

do and don't

do
storage-01
storage-02
storage-03
The space between the boxes comes from the stack's gap: one value, on the scale.
don't
storage-01
storage-02
storage-03
Margins on each box drift off the scale, and never quite match.
do
backups
Every night at 02:00, kept 14 days.
A group with a title is a card: the header, the line below it and the padding come with it.
don't
backupsEvery night at 02:00, kept 14 days.
A box with a hand-made title is a card that drifts: different padding, no line below the header, and the title in the wrong type.
  • Stack: the space between the things inside it.
  • Card: a box with a header, a footer and the usual padding.
  • Layout: the space scale behind the padding.
  • Shape: square frames and hairlines.

specs

setting in code what it does
Padding on every side p 0, 4, 8, 12, 16, 24, 32, 48 or 64; the steps from 4 to 64 resolve to --s-1 … --s-8. No default.
Padding on the left and right px The same steps, applied after p.
Padding on the top and bottom py The same steps, applied after p: p={16} px={24} gives 16px on the top and bottom and 24px on the left and right.
Background bg="bg", bg="bg-2", bg="surface" or bg="surface-2" --bg, --bg-2, --surface or --surface-2. Without bg, the box is transparent. A sunken area is a bg="bg-2" box inside a bg="surface" one.
Border border A 1px --border hairline on every side.
  • Frame: a div with box-sizing: border-box and border-radius: 0, never rounded. No padding, background or border unless they are set.
  • Contrast: the --border hairline sits below 3:1 by design. Every text colour meets 4.5:1 on all four backgrounds.
  • Role and name: none. For a landmark or a named region, pass a role with an aria-label or aria-labelledby.
  • Focus: none. tab skips the box and moves through what is inside it, in order.