# Composition — Layout

Use Arrow's 12-column grid utilities for every page layout. **Do not write custom CSS for layout.** Containers, rows, columns, gaps, and alignment are all utility classes on plain HTML elements — no React component is needed.

## Containers

A container caps the content width and centers it horizontally.

| Class | Max width | Use for |
|---|---|---|
| `tdds:container` | 100% | Full-bleed sections (hero banners, footers) |
| `tdds:container-xl` | 1180px | Default page width — most pages start here |
| `tdds:container-lg` | 960px | Reading layouts, narrow marketing pages |
| `tdds:container-md` | 768px | Forms, settings pages |
| `tdds:container-sm` | 530px | Single-column login or onboarding |

```tsx
<main className="tdds:container-xl">
  {/* page content */}
</main>
```

## Rows and columns

Wrap columns in a `tdds:row`. Columns sum to 12 across a row.

| Class | Width |
|---|---|
| `tdds:col-1` … `tdds:col-12` | n/12 of the row |
| `tdds:col-auto` | Sized to content |
| `tdds:col-fill` | Takes remaining space after fixed-width siblings |

```tsx
<div className="tdds:container-xl">
  <div className="tdds:row tdds:gap-3">
    <div className="tdds:col-8">{/* main */}</div>
    <div className="tdds:col-4">{/* sidebar */}</div>
  </div>
</div>
```

## Responsive variants

Prefix any column or gap class with a breakpoint to change behavior at that size.

| Prefix | Min width |
|---|---|
| `tdds:sm:` | 360px |
| `tdds:md:` | 768px |
| `tdds:lg:` | 1024px |
| `tdds:xl:` | 1280px |

Mobile-first: write the smallest layout first, then layer larger breakpoints.

```tsx
<div className="tdds:row tdds:gap-3">
  {/* Mobile stacked, tablet 2-up, desktop 3-up */}
  <div className="tdds:col-12 tdds:md:col-6 tdds:lg:col-4">Card 1</div>
  <div className="tdds:col-12 tdds:md:col-6 tdds:lg:col-4">Card 2</div>
  <div className="tdds:col-12 tdds:md:col-12 tdds:lg:col-4">Card 3</div>
</div>
```

## Decision tree — picking column widths

1. **One thing on the row?** → `tdds:col-12` (or `tdds:container-md` and skip the row)
2. **Two equal things?** → `tdds:col-12 tdds:md:col-6` (stack on mobile, side-by-side from tablet up)
3. **Three equal cards?** → `tdds:col-12 tdds:md:col-6 tdds:lg:col-4` (1 → 2 → 3 columns)
4. **Four equal cards?** → `tdds:col-6 tdds:md:col-3` (2 → 4 columns)
5. **Main + sidebar?** → `tdds:col-12 tdds:lg:col-8` for main, `tdds:col-12 tdds:lg:col-4` for aside
6. **Asymmetric two-up?** → `tdds:col-12 tdds:md:col-8` + `tdds:col-12 tdds:md:col-4`
7. **Toolbar with flexible middle?** → `tdds:col-auto` for fixed items, `tdds:col-fill` for the flexible one

## Direction

Default rows flow left-to-right. Reverse or stack with direction utilities on the `tdds:row`.

- `tdds:direction-row` (default)
- `tdds:direction-row-reverse`
- `tdds:direction-column`
- `tdds:direction-column-reverse`

## Alignment

| Axis | Class family |
|---|---|
| Cross-axis (vertical when row) | `tdds:align-start`, `tdds:align-center`, `tdds:align-end` |
| Main-axis (horizontal when row) | `tdds:justify-start`, `tdds:justify-center`, `tdds:justify-end`, `tdds:justify-between`, `tdds:justify-around` |
| Per-item override | `tdds:self-start`, `tdds:self-center`, `tdds:self-end`, `tdds:self-stretch` |

```tsx
<div className="tdds:row tdds:justify-between tdds:align-center">
  <div className="tdds:col-auto">Logo</div>
  <div className="tdds:col-auto">Nav</div>
</div>
```

## Gaps

Set spacing between columns with `tdds:gap-*` on the row. Gap is responsive — combine with breakpoints.

| Class | Size |
|---|---|
| `tdds:gap-0` | 0 |
| `tdds:gap-1` | 8px |
| `tdds:gap-2` | 16px |
| `tdds:gap-3` | 24px |
| `tdds:gap-4` | 32px |
| `tdds:gap-5` | 40px |

```tsx
<div className="tdds:row tdds:gap-3 tdds:md:gap-5">…</div>
```

## Order

Reorder visually without changing DOM order: `tdds:order-1` through `tdds:order-12`, plus `tdds:order-first`, `tdds:order-last`, `tdds:order-initial`. Useful for flipping a sidebar from above to beside the main content at larger breakpoints.

```tsx
<aside className="tdds:col-12 tdds:lg:col-4 tdds:order-2 tdds:lg:order-1">…</aside>
<main className="tdds:col-12 tdds:lg:col-8 tdds:order-1 tdds:lg:order-2">…</main>
```

## Layout rules

- No inline `style` for layout — use utility classes
- No custom CSS Grid or Flexbox in component code
- Always wrap columns in `tdds:row`; never nest a column directly under a container
- Columns must sum to 12 (or use `col-auto` / `col-fill`) — overflow wraps to a new row
