# Layout

Page structure, grid, spacing, radius, and elevation.

## Overview

Tempo pages are calm and orderly. Flat cards sit on a tinted page, line up on a twelve-column grid, and keep generous space between groups, so the content stands out more than its frame.

Space follows relationships. Elements sit close within a group, further apart between groups, and furthest apart between sections. As the screen widens, the margins grow and the sidebar opens, while the content keeps a comfortable width.

For page frames and width changes, see [Responsive Layout](/docs/patterns/responsive-layout).

## Page Structure

Every page shares one frame, which [App Shell](/docs/components/app-shell) provides.

* **Sidebar:** Navigation on the start edge, which moves into a drawer on small screens.
* **Top Bar:** The page title and its main action, in one bar above the content.
* **Content:** Cards, charts, and tables, arranged on the page grid below the bar.

## Grid

Wide pages divide into twelve columns. Each card, chart, and table takes a share of them, and every row keeps the same gutters. [Grid](/docs/components/grid) lays out the columns.

* **Summary Cards (3 of 12):** Key figures in a row of equal cards.
* **Chart and Panel (8 and 4):** A wide chart beside a narrow panel.
* **Tables (12 of 12):** Lists and tables across the full width.
* **Small Screens (phone):** Cards pair up, and panels stack.

## Spacing

Spacing comes from one scale of steps. Pick a step by how closely the elements relate: the closer the relationship, the smaller the gap.

* **Related Elements (4 to 8):** An icon and its label, or a label and its value.
* **Items and Fields (12 to 16):** Items in a list, fields in a form, and buttons.
* **Groups and Cards (24 to 32):** Groups within a section, such as cards in a grid.
* **Page Sections (40 to 64):** The sections of a page, such as a table.

## Radius

Larger elements get rounder corners, from fields at 12px to modals at 32px. [Radius and Padding](/docs/foundations/radius-and-padding) covers each role and its padding.

* `none`: `0rem`
* `3xs`: `calc(0.25rem * var(--tds-corner-scale, 1))`
* `2xs`: `calc(0.5rem * var(--tds-corner-scale, 1))`
* `xs`: `calc(0.75rem * var(--tds-corner-scale, 1))`
* `sm`: `calc(1rem * var(--tds-corner-scale, 1))`
* `md`: `calc(1.5rem * var(--tds-corner-scale, 1))`
* `lg`: `calc(2rem * var(--tds-corner-scale, 1))`
* `xl`: `calc(2.5rem * var(--tds-corner-scale, 1))`
* `2xl`: `calc(4rem * var(--tds-corner-scale, 1))`
* `full`: `62.4375rem`

## Elevation

Shadows mark layers that float above the page, and most surfaces need none. In dark mode, a layer lifts with a lighter surface rather than a deeper shadow.

* **Flat (none):** Cards and panels, which sit flat on the page.
* **Small (shadow.small):** Controls that lift off a track, such as a switch thumb.
* **Regular (shadow.regular):** Menus, toasts, and other popups over the page.
* **Large (shadow.large):** Dialogs and drawers, above the dimmed page.

## Widths

[Container](/docs/components/container) centers content at a maximum width, with side gutters that grow on larger screens. Pick its size by the content, not by the screen.

* **Narrow (48rem):** Forms, settings, and single-task flows.
* **Medium (64rem):** Detail pages, such as a transaction or an API key.
* **Wide (80rem):** The default, for dashboards, tables, and card grids.
* **Full (none):** Charts and canvases that manage their own width.

## Breakpoints

Design for the smallest screen first, then let content spread into more columns as space allows. Components change layout at the same widths, so a layout that shifts beside one should switch with it.

* **Phone (0 to 639px):** One column, with the sidebar in a drawer.
* **Tablet (640 to 1023px):** Two columns, where the content allows.
* **Desktop (1024px and up):** The sidebar opens, and grids gain columns.

Write a breakpoint as a query inside a style.

```tsx
import { style } from '@tempoxyz/ds'

namespace styles {
  export const metrics = style({
    display: 'grid',
    gap: '16',
    '@media >=768': { gridTemplateColumns: 'repeat(3, minmax(0, 1fr)) !custom' },
  })
}
```

## Layout Primitives

Primitives arrange content without adding meaning. When a region needs meaning, render the primitive as a semantic element, such as a list or the main landmark.

* **Stack (gap 16):** [Stack](/docs/components/stack) spaces a vertical run, such as fields in a form.
* **Inline (gap 8):** [Inline](/docs/components/inline) spaces a horizontal run, such as actions or badges.
* **Grid (gap 24):** [Grid](/docs/components/grid) arranges similar items, such as metric tiles.
* **Container (size):** [Container](/docs/components/container) sets the page width and side gutters.
* **Inset (space):** [Inset](/docs/components/inset) pads a region without drawing a container.
* **Surface (size):** [Surface](/docs/components/surface) is a visible card that groups related content.

## Guidelines

### Space Siblings With Gap

Space siblings from their parent. Margins on each child collapse, double up when items reorder, and leave stray space after the last item.

**Do:** Space the items of a list from their parent.

```tsx
/**
 * Do example for "Space Siblings With Gap" on the Layout page.
 * Space the items of a list with `gap` on the parent.
 * @module
 */
import { style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <span {...styles.item()}>Sent 25.00 USDC to 0x3c44…93bc</span>
      <span {...styles.item()}>Received 120.00 USDC</span>
      <span {...styles.item()}>Sent 8.50 USDC to 0x90f7…b906</span>
    </div>
  )
}

namespace styles {
  export const item = style({
    backgroundColor: 'container.regular',
    borderRadius: '2xs',
    color: 'content.primary',
    paddingBlock: '8',
    paddingInline: '12',
    typography: 'body.b2',
  })

  export const list = style({
    borderColor: 'line.secondary',
    borderRadius: 'xs',
    borderStyle: 'dashed',
    borderWidth: 'regular',
    display: 'flex',
    flexDirection: 'column',
    gap: '12',
    maxWidth: '100% !custom',
    padding: '12',
    width: '18rem !custom',
  })
}
```

**Don't:** Add a margin to each child, which leaves space after the last one.

```tsx
/**
 * Don't example for "Space Siblings With Gap" on the Layout page.
 * Don't add a margin to each child, which leaves space after the last one.
 * @module
 */
import { style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <span {...styles.item()}>Sent 25.00 USDC to 0x3c44…93bc</span>
      <span {...styles.item()}>Received 120.00 USDC</span>
      <span {...styles.item()}>Sent 8.50 USDC to 0x90f7…b906</span>
    </div>
  )
}

namespace styles {
  export const item = style({
    backgroundColor: 'container.regular',
    borderRadius: '2xs',
    color: 'content.primary',
    marginBottom: '12',
    paddingBlock: '8',
    paddingInline: '12',
    typography: 'body.b2',
  })

  export const list = style({
    borderColor: 'line.secondary',
    borderRadius: 'xs',
    borderStyle: 'dashed',
    borderWidth: 'regular',
    display: 'flex',
    flexDirection: 'column',
    maxWidth: '100% !custom',
    padding: '12',
    width: '18rem !custom',
  })
}
```

### Group Related Content by Proximity

Put less space inside a group than between groups. A label sits close to its value, and separate pairs sit well apart, so they need no dividers.

**Do:** Keep each label close to its value and leave more space between pairs.

```tsx
/**
 * Do example for "Group Related Content by Proximity" on the Layout page.
 * Keep each label close to its value and leave more space between pairs.
 * @module
 */
import { Stack, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Stack gap="24">
      <Stack gap="4">
        <span {...styles.label()}>Recipient</span>
        <span {...styles.value()}>0x3c44…93bc</span>
      </Stack>
      <Stack gap="4">
        <span {...styles.label()}>Amount</span>
        <span {...styles.value()}>250.00 PathUSD</span>
      </Stack>
      <Stack gap="4">
        <span {...styles.label()}>Network fee</span>
        <span {...styles.value()}>0.01 PathUSD</span>
      </Stack>
    </Stack>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b3' })

  export const value = style({ color: 'content.primary', typography: 'body.b1Strong' })
}
```

**Don't:** Space every line equally, which makes labels and values hard to pair.

```tsx
/**
 * Don't example for "Group Related Content by Proximity" on the Layout page.
 * Don't space every line equally, which makes labels and values hard to pair.
 * @module
 */
import { Stack, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Stack gap="12">
      <span {...styles.label()}>Recipient</span>
      <span {...styles.value()}>0x3c44…93bc</span>
      <span {...styles.label()}>Amount</span>
      <span {...styles.value()}>250.00 PathUSD</span>
      <span {...styles.label()}>Network fee</span>
      <span {...styles.value()}>0.01 PathUSD</span>
    </Stack>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b3' })

  export const value = style({ color: 'content.primary', typography: 'body.b1Strong' })
}
```

### Keep Cards Flat

Separate a [Surface](/docs/components/surface) from the page with its lighter background, not a shadow. Keep shadows for content that floats over other content.

**Do:** Keep cards flat, and add a shadow only to the layer above them.

```tsx
<LayoutDemo kind="elevated" />
```

**Don't:** Give every card a shadow.

```tsx
<LayoutDemo kind="shadowed" />
```

### Use One Surface per Group

**Do:** Use one surface with a title for one group.

```tsx
<Surface>
  <Surface.Header>
    <Surface.Title>Balances</Surface.Title>
    <Button size="small" variant="tertiary">View all</Button>
  </Surface.Header>
  <span>120.00 USDC</span>
</Surface>
```

**Don't:** Nest surfaces to create structure.

```tsx
<Surface>
  <Surface>
    <Surface>
      <span>120.00 USDC</span>
    </Surface>
  </Surface>
</Surface>
```

### Size Containers by Content

Pick the narrowest [Container](/docs/components/container) that fits the content.

**Do:** Keep a form in a narrow container, so each field is as wide as its content needs.

```tsx
<Field.Root>
  <Field.Label>Recipient</Field.Label>
  <TextInput.Group>
    <TextInput.Control placeholder="Address or username" />
  </TextInput.Group>
</Field.Root>
```

**Don't:** Stretch a form across a wide page.

```tsx
<LayoutDemo kind="container" width="full" />
```

### Let Collections Reflow

For cards and metric tiles, let the grid fit as many columns as the width allows. A fitted grid collapses to one column on a phone without extra breakpoints.

**Do:** Let a collection reflow to one column at 320px.

```tsx
<LayoutDemo kind="columns" width="phone" />
```

**Don't:** Fix a column count that runs past a narrow screen.

```tsx
<LayoutDemo kind="overflow" />
```

### Keep Source Order Visual Order

Don't reorder content visually. Keyboard focus and screen readers follow the source, so a reordered layout makes focus jump.

**Do:** Write elements in the order they appear, so focus moves left to right.

```tsx
/**
 * Do example for "Keep Source Order Visual Order" on the Layout page.
 * Write elements in the order they appear, so focus moves left to right.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <span {...styles.item()}>
        <span {...styles.step()}>1</span>
        <Button variant="secondary">Cancel</Button>
      </span>
      <span {...styles.item()}>
        <span {...styles.step()}>2</span>
        <Button>Send payment</Button>
      </span>
    </div>
  )
}

namespace styles {
  export const item = style({
    alignItems: 'center',
    display: 'flex',
    flexDirection: 'column',
    gap: '8',
  })

  export const row = style({ alignItems: 'flex-end', display: 'flex', gap: '12' })

  export const step = style({
    alignItems: 'center',
    backgroundColor: 'accent.blue.background',
    borderRadius: 'full',
    color: 'white !custom',
    cornerShape: 'round',
    display: 'inline-flex',
    height: '20',
    justifyContent: 'center',
    typography: 'body.b3Strong',
    width: '20',
  })
}
```

**Don't:** Reverse the visual order, which makes focus jump backward.

```tsx
/**
 * Don't example for "Keep Source Order Visual Order" on the Layout page.
 * Don't reverse the visual order, which makes focus jump backward.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <span {...styles.item()}>
        <span {...styles.step()}>1</span>
        <Button>Send payment</Button>
      </span>
      <span {...styles.item()}>
        <span {...styles.step()}>2</span>
        <Button variant="secondary">Cancel</Button>
      </span>
    </div>
  )
}

namespace styles {
  export const item = style({
    alignItems: 'center',
    display: 'flex',
    flexDirection: 'column',
    gap: '8',
  })

  export const row = style({
    alignItems: 'flex-end',
    display: 'flex',
    flexDirection: 'row-reverse',
    gap: '12',
    justifyContent: 'flex-end',
  })

  export const step = style({
    alignItems: 'center',
    backgroundColor: 'accent.blue.background',
    borderRadius: 'full',
    color: 'white !custom',
    cornerShape: 'round',
    display: 'inline-flex',
    height: '20',
    justifyContent: 'center',
    typography: 'body.b3Strong',
    width: '20',
  })
}
```

## Accessibility

* **Reflow (320px):** Content reflows without sideways scrolling, as fitted grids do by default.
* **Regions (render):** Primitives add no roles, so render regions as meaningful elements.
* **Text Size (200%):** Spacing grows with larger default text, so check layouts at 200%.

## Related

[Responsive Layout](/docs/patterns/responsive-layout)

Covers page frames and width changes.

[Stack](/docs/components/stack)

Use for arranging content.

[Inline](/docs/components/inline)

Use for arranging content.

[Grid](/docs/components/grid)

Use for arranging content.

[Container](/docs/components/container)

Use for width and padding.

[Inset](/docs/components/inset)

Use for width and padding.

[Surface](/docs/components/surface)

Use for cards.

[App Shell](/docs/components/app-shell)

Use for the application frame.

[Radius and Padding](/docs/foundations/radius-and-padding)

Covers how padding pairs with each radius.
