# @spark-web/stack — AI Context

## What this is

Vertical layout component. Renders children in a column with consistent spacing
between them. Use `Stack` as the default layout for any top-to-bottom
arrangement — page sections, form fields, card bodies, filter bars.

## What this is NOT

- Not for horizontal layouts — use `Row` or `Columns`
- Not a grid — use `Columns` for multi-column layouts
- Not a scrollable container — add `overflow` via a wrapping `Box`

## Props interface

| Prop       | Type                                                      | Default     | Notes                                 |
| ---------- | --------------------------------------------------------- | ----------- | ------------------------------------- |
| `gap`      | spacing token (responsive)                                | —           | Space between children                |
| `align`    | `'left' \| 'center' \| 'right' \| 'stretch'` (responsive) | `'stretch'` | Cross-axis alignment of children      |
| `dividers` | `boolean`                                                 | `false`     | Insert a `Divider` between each child |
| `as`       | HTML element tag                                          | `'div'`     | —                                     |
| `data`     | `DataAttributeMap`                                        | —           | Test/analytics attributes             |

`Stack` also accepts all `Box` props except `display`, `alignItems`,
`flexDirection`, `justifyContent`, and `flexWrap` — those are locked.

## Common patterns

### Page-level layout

```tsx
<Stack gap="xlarge">
  <PageHeader>Users</PageHeader>
  <FilterRow />
  <DataTable ... />
  <Pagination />
</Stack>
```

### Card body

```tsx
<Stack gap="medium" padding="large">
  <Text weight="semibold">{title}</Text>
  <Text tone="muted" size="small">
    {description}
  </Text>
</Stack>
```

### Form fields

```tsx
<Stack gap="large">
  <Field label="Name">
    <TextInput />
  </Field>
  <Field label="Email">
    <TextInput type="email" />
  </Field>
</Stack>
```

## Do NOTs

- NEVER set `flexDirection`, `display`, or `alignItems` on `Stack` — locked
- NEVER use `Stack` for side-by-side layouts — use `Row` or `Columns`
- NEVER nest `Stack` inside itself just to change gap — restructure the children
  instead