Layout

Principles

• Space by relationship. Related items sit closer than separate tasks, so gaps alone show the groups.
• Take every gap from the scale. Spacing tokens step in multiples of 4px, so edges line up across screens. Only inside a control do sizes take 2px half steps.
• Give each gap one owner. The parent's gap spaces children and the container's padding spaces its inside; children add no margins.
• Set one size per composition. SizeProvider sizes a whole form, table, or menu, so neighboring controls match.
• Reflow without reordering. On narrow screens, regions stack in DOM order, so focus order matches the screen.

Containers

Pick a container by task. It fills the available width up to its maximum and centers beyond it.

Inside any container, reading text wraps at the line length Typography sets.

Grid

Use Grid columns for equal cards, and the 12 / 6 / 4 layout grid for regions of different widths, such as main content beside a panel.

import { Container, Grid, GridItem, Card } from '@surflane/ui'

<Container width='workspace'>
  <Grid columns='layout'>
    <GridItem span={8} mediumSpan={4} smallSpan={4}>
      Main
    </GridItem>
    <GridItem span={4} mediumSpan={2} smallSpan={4}>
      Details
    </GridItem>
    <GridItem span={12} mediumSpan={6} smallSpan={4}>
      Results
    </GridItem>
  </Grid>
</Container>

// Equal cards: 3 columns, then 2, then 1.
// Match bleed to the card padding so card text aligns with the text around it.
<Grid columns={3} gap={4} bleed={4}>
  {items.map((item) => (
    <Card.Root key={item.id} padding={4}>
      ...
    </Card.Root>
  ))}
</Grid>

// As many columns as the grid's own width holds, each at least 20rem.
<Grid columns='auto' min='card'>
  {items.map((item) => (
    <Card.Root key={item.id}>...</Card.Root>
  ))}
</Grid>

A fixed count steps down with the window. Where a grid's room does not follow the window, such as beside a sidebar or inside a panel, columns='auto' fits as many columns as the grid's own width holds, each at least min: 'tile' 10rem for a figure and its label, 'brief' 14rem for a card of a name and a line or two, such as one of many sessions, 'card' 20rem for a card, 'wide' 30rem for a chart or a small table.

Match bleed to the card padding, such as bleed={4} for padding={4}, so card text lines up with the text around the grid. Don't bleed at the window edge or inside a clipped area.

Scroll wide tables and code inside a ScrollArea instead of widening the page.

Spacing

Pick each gap from the scale by how closely two things relate.

The form below follows the table. Turn on the dimensions to measure each gap.

<Stack gap={4}>
  <Stack gap={1}>{/* Title and description; margin: 0 */}</Stack>
  <Field.Root>{/* Field.Label + Input; gap: var(--surf-space-2) */}</Field.Root>
  <Inline gap={2}>{/* Action buttons */}</Inline>
</Stack>

Compact layouts tighten task groups to 16px and leave controls as they are. On phones, the page inset drops to 16px and section gaps to 32px. Size gaps from the scale, never from viewport height.

Component sizes

Small, Default, and Large change control height, text, and inner spacing. They don't scale the screen.

On touch and narrow screens, controls never shrink below the target size. Size never changes chart data or line thickness. Only control text steps with the size: every type role stays the same, apart from the titles of cards, sheets, drawers and dialogs, which take the subsection role at Small. A default SizeProvider renders exactly as none.

SizeProvider sizes a form, table, or menu, including the portals it opens. A nested provider or a size prop overrides it. Wrap Table.Container from outside instead of putting a provider inside a table. Its density='compact' tightens the blocks inside for a dense screen: 12px between them, 8px within, label-role card titles, compact tables and charts, and controls that keep their size on touch.

import { SizeProvider, Button, Input, Select } from '@surflane/ui'

<SizeProvider size='small'>
  <Input aria-label='Project name' />
  <Select aria-label='Environment' options={environments} />
  <Button>Apply</Button>
  <Button size='large'>Start deployment</Button>
</SizeProvider>

// The short sm / md / lg spellings still work, but are deprecated.
// A numeric size on Input is the standard HTML character-width hint.

Density

Density is a second axis beside size. Size sets how big a control is; density sets how close blocks sit. SizeProvider density='compact' packs a region people scan more than they edit, such as a monitoring dashboard: blocks sit 12px apart and keep 8px inside, and the parts inside take their compact forms.

Keep forms, documents and phone-first screens at the default density. Set compact on a whole region, not on single parts, so neighboring blocks match; a table people read closely opts back with density='default'.

Compact never takes a target under 24px, the WCAG 2.2 AA minimum. On touch screens its controls keep their size instead of growing to 44px.

Collections

A collection shows like items side by side, such as sessions, hosts or deployments, as cards in a Grid. People compare the cards across a row, so every card shows the same parts in the same places, and the grid fits the cards to the room it has.

import {
  Avatar,
  Card,
  Grid,
  Inline,
  Meter,
  Sheet,
  SizeProvider,
  Stack,
  Stat,
  StatusBadge,
  Text,
  categoryFor,
} from '@surflane/ui'

<SizeProvider density='compact'>
  <Grid columns='auto' min='card'>
    {sessions.map((session) => (
      <Sheet.Root key={session.id}>
        <Card.Root>
          <Card.Header>
            <Inline justify='between' wrap={false}>
              <Inline gap={3} wrap={false}>
                <Avatar.Root
                  category={categoryFor(session.name)}
                  aria-hidden='true'
                >
                  <Avatar.Fallback>{session.initials}</Avatar.Fallback>
                  {session.working && <Avatar.Status tone='progress' live />}
                </Avatar.Root>
                <Stack gap={0}>
                  <Card.Title lines={1}>
                    <Sheet.Trigger render={<Card.Action />}>
                      {session.name}
                    </Sheet.Trigger>
                  </Card.Title>
                  <Text variant='caption' color='secondary' lines={1}>
                    {session.agent}
                  </Text>
                </Stack>
              </Inline>
              <StatusBadge tone={session.tone}>{session.state}</StatusBadge>
            </Inline>
          </Card.Header>
          <Card.Body>
            <Text lines={2}>{session.lastMessage}</Text>
          </Card.Body>
          <Card.Footer>
            <Meter.Root value={session.context} low={60} high={85} optimum={0}>
              <Meter.Label>Context</Meter.Label>
              <Meter.Value />
              <Meter.Track>
                <Meter.Indicator />
              </Meter.Track>
            </Meter.Root>
            <Stat.Group label='Session counts' labelHidden size='small'>
              <Stat.Root>
                <Stat.Label>Turns</Stat.Label>
                <Stat.Value>{session.turns}</Stat.Value>
              </Stat.Root>
              {/* Tools, Tokens, Time: a value not yet known shows a dash. */}
            </Stat.Group>
          </Card.Footer>
        </Card.Root>
        <Sheet.Content>
          {/* The whole session: counts, context, turns. */}
        </Sheet.Content>
      </Sheet.Root>
    ))}
  </Grid>
</SizeProvider>

Reading direction

Components mirror for right-to-left languages when two things are set: dir='rtl' on the page or region turns the layout, and DirectionProvider direction='rtl' around it turns arrow keys and the popups that render outside the region. Every side in the stylesheets is logical, so padding, alignment and docked parts follow the reading direction.

For text that mixes directions, such as names and identifiers, see Content and localization.

Related

• Typography — Sets typefaces, type roles, line length, and Korean text rules.
• Visual hierarchy — Orders planes, elevation, lines, and points from structure to detail.
• Accessibility — Sets the WCAG 2.2 AA baseline that every screen meets.
• App shell / Sidebar — Frames content with collapsible navigation, brand and theme on top, account below.