layout

Good spacing makes a screen easy to read: things that belong together sit close, and groups are set apart. So every gap and every padding comes from one short scale, every control comes in the same three heights, and the components adapt to the room they are given.

There is no grid component. A layout is put together from stacks, boxes, cards and a simple grid in your own CSS.

the scale

Every gap and padding is one of eight steps: 4, 8, 12, 16, 24, 32, 48 or 64 pixels. There is nothing in between, no 10 and no 20. A short scale keeps spacing the same from screen to screen, and it makes the right choice an easy one.

• The space between components, and around them, is always a step of the scale. Inside small parts, a few components nudge things by a pixel or a few, to centre a symbol or a label; the specs list them. Those nudges belong to the components: keep your own layout on the scale.
• Space shows structure. Things that belong together sit closer than the groups they form: 8 inside a field, 16 between fields, 24 or more between sections.

control heights

Every control comes in the same three heights, so controls in a row line up.

• Buttons, text fields, selects and icon buttons come in all three heights; an icon button is a square. The multi select comes in small and medium only.
• A checkbox's box and a switch's track are smaller than the controls, but their whole label is the target.
• A few things sit outside the three heights: the items of an action menu, the portal's search field and a dialog's close button.
• A text area has no fixed height. Its number of rows sets it, four unless you choose another.

density

Density is how tightly a component is packed. It is set on each component that has it; there is no switch for a whole page.

• Use the dense table for long lists that people scan and compare with a pointer, such as an inventory or a log.
• Keep the usual density where rows carry a second line, such as a status with its reason, and where people use touch.
• Use one density per view. A dense table under filters of the usual size is fine; two tables of different density side by side are not.

responsive behaviour

Three components change their layout according to their own width, not the screen's. A table in a narrow side panel on a wide screen behaves just like one on a phone, so a component works wherever it is placed.

Move the slider: each component measures itself and changes on its own.

• The width that counts is the room inside the component, so its own padding and border count against it.
• Until a component has measured itself, and wherever it can't measure, such as on a page rendered on the server or in automated tests, it shows its wide layout.
• The filter bar's and the toolbar's widths can be changed; the data table's are fixed. There, a column's rank decides what goes first, and the column that names the row never pops in.
• Everything else adapts by itself. The rows of the filter bar, the toolbar, a worklist's header, the portal's title bar and a banner wrap when they run out of room. filter tabs scroll sideways, with a fade on the edge where more are hidden. A dialog has a maximum width and keeps a margin from the screen's edges, and the toasts are never wider than the screen.
• The components don't look at the screen's width at all, and use no breakpoints. The only setting of the device they follow is reduced motion.

The exact widths are in the specs.

phone width

Every screen works at 390 pixels wide, a phone held upright, and at 320 pixels, which is what a 1280-pixel window becomes at 400% zoom. The components get there on their own; a screen gets there when its own layout does too.

• One column. When there isn't room for two columns, stack them. A grid that fits as many columns as there is room for falls back to a single column by itself; the specs have the rule.
• Rank the columns. Give every data table column after the first an importance, so the table keeps its frame and the lesser values pop in under the row's name.
• No fixed widths. A width on a panel or a field becomes a maximum width, so nothing grows wider than its container.
• The same actions. A toolbar folds its actions into its menu, and the filter bar its facets behind one button. Nothing is left out at phone width, and nothing works only with hover.
• Test it. At 390 pixels and at 400% zoom, in the browser's responsive mode, with the keyboard as well as with touch.

grid and layout

There is no grid component, no column system and no breakpoints. A layout is put together from a few parts:

• Stack: one direction, with a gap from the scale. It does most of the work.
• Box: padding from the scale, and a canvas background.
• Card: a group with a title and the usual padding.
• A grid in your app's CSS, for rows and columns, with gaps from the scale.
• The tile group is the one component with a grid of its own: as many columns as fit, or a set number of columns.

accessibility

• Even the small controls are taller than the smallest target allowed, 24 pixels. The checkbox's small box and the switch count their label as the target; boxes without a label in a list need 24 pixels from one to the next.
• At 400% zoom, a 1280-pixel window is 320 pixels wide. The components that respond to their own width then behave as they would in a narrow panel: only the most important columns stay, the facets fold, and the actions move into the menu.
• A column that pops in is still read out: its label and value are text under the row's first cell, not hidden.
• In your own layouts, keep the order on the screen the same as the order in the page's code, without reordering anything with CSS. Then what people see, what they hear and the order of the tab stops all agree.

do and don't

related

• Stack: gaps from the scale, in one direction.
• Box: padding from the scale.
• Data table: column importance, pop-in and density.
• Worklist: a whole page built from these parts.
• Shape: the frames these spaces sit in.

specs

the scale

Eight steps, --s-1 to --s-8, from tokens/tokens.json.

The nudges inside small parts: 2px in the switch track and between a filter tab's count and its label; 3px to sit a glyph on the first line of text; 6px between a status glyph and its text, around a tooltip, and inside inline code and kbd.

control heights

• Button and Input take size and inputSize, Select selectSize, IconButton size (a square: 28, 34 or 42px). MultiSelect has sm and md only.
• The checkbox box is 16px; the switch track is 20px high (md) or 16px (sm).
• Outside the three heights: action menu items are at least 32px high, the portal's search field is 32px, and a modal's close button 26px.
• Textarea: rows, 4 by default.

density

responsive

• Measured with a ResizeObserver: the element's content box, rounded to the pixel. The toolbar has 12px of padding and a 1px border on each side, so its actions move while its outer edge is still under 586px; the data table's 1px border puts its steps at 722 and 482px outside.
• Without a measurement, and where ResizeObserver doesn't exist (server rendering, jsdom tests), the wide layout shows.
• collapseBelow moves the filter bar's and the toolbar's threshold. The data table's 720 and 480 are fixed; the first column, or the one marked rowHeader, never pops in.
• The library has no viewport media queries; its only media queries are for prefers-reduced-motion.
• CSS only: a modal is at most 480px wide (width) and 16px from the edges; the toaster is at most the viewport's width minus 32px.
• Tile group: repeat(auto-fill, minmax(14rem, 1fr)) by default (minTileWidth), or a fixed columns count, with gaps of 4, 8, 16 (default) or 24px.

a grid that falls to one column

/* columns at least 12rem wide, as many as fit; one column on a narrow screen. */
.volumes {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 12rem), 1fr));
  gap: var(--s-4);
}

how to apply it

• CSS. var(--s-1) … var(--s-8), from tokens.css.
• Box and stack. p, px, py and gap take the step in px: 0, 4, 8, 12, 16, 24, 32, 48 or 64. TypeScript rejects any other number; at run time an off-scale number resolves to 0.
• JavaScript. From @nalet/design-system, space is the helper behind those props: space(16) returns 'var(--s-4)'. The values themselves are tokens.space (tokens.space['s-4'] is '16px'), or space from @nalet/design-system/tokens.
• Tailwind. The preset sets the spacing keys 1–8 (and s-1–s-8) to the scale, so p-5 is 24px here, not Tailwind's 20px, and gap-8 is 64px. Tailwind's other spacing keys (0.5, 10, 12 …) are still there and off the scale: don't use them.
• Order. Keep the DOM order the visual order: no order, no reversed flex directions.