# Layout

Compose pages with Stack, Grid, Container and arene's type styles.

Use layout components when their props describe the job. Use a `stylex.create()`
entry when layout belongs with appearance or needs a shape those props do not
express. You can pass that entry through `xstyle`.

## Choose a layout

| Tool                                                           | Use                                                                          |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [Stack](https://www.arene.style/docs/components/stack)         | One axis, with gap, alignment, wrapping or padding. It defaults to vertical. |
| [Grid](https://www.arene.style/docs/components/grid)           | Equal columns or columns that fit the available width.                       |
| [Container](https://www.arene.style/docs/components/container) | Centered content with a width cap and inline padding.                        |
| `stylex.create()`                                              | A mixed entry with layout and appearance, or a custom grid template.         |

Containers own padding. Children have no margins; their parent sets the gap.
This keeps spacing in one place when you reorder or remove children. The reset
removes default margins, including heading and paragraph margins.

Stack and Grid share a closed spacing scale. `gap={4}` reads `space.s4`.
Stack also has padding props, with individual sides taking precedence over axis
padding and then all-side padding. Grid accepts `columns={1}`, `2` or `3`, or
`minWidth="narrow"` or `"xs"` for auto-fit columns. Choose columns or minWidth,
not both. The auto-fit minimum never exceeds the available width.

## Content widths

Container defaults to `size="xl3"`, a 48rem cap, with 1.5rem inline padding.
It centers itself and fills the available width up to that cap. Its other sizes
are `narrow`, `xs`, `sm`, `md` and `lg`.

Use `widths` from `theme/widths.ts` through `xstyle` when another component
needs a complete width rule. Each entry sets `width: "100%"` and a `maxWidth`.
It does not add centering or padding.

Use `width` from `theme/tokens.stylex.ts` inside a mixed entry, such as a popup
that also sets its positioning and appearance. This keeps the entry whole
instead of splitting out its width as another style.

| Key      | Width |
| -------- | ----- |
| `narrow` | 12rem |
| `xs`     | 20rem |
| `sm`     | 24rem |
| `md`     | 28rem |
| `lg`     | 32rem |
| `xl3`    | 48rem |

## Responsive direction

Override Stack's direction through `xstyle`. The default direction prop still
sets `data-orientation`; a media query changes the layout, not that attribute.
Do not use that attribute to infer the current responsive direction.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Stack } from "@/components/ui/stack"
import { Text } from "@/components/ui/text"
import { breakpoints } from "@/theme/breakpoints.stylex"

const styles = stylex.create({
  row: { flexDirection: { default: "column", [breakpoints.md]: "row" } },
})

export default function LayoutDirection() {
  return (
    <Stack gap={4} xstyle={styles.row}>
      <Text>Project name</Text>
      <Text tone="muted">Updated today</Text>
    </Stack>
  )
}
```

## Visibility

Import `visibility` from `theme/visibility.ts` and pass a style through `xstyle`.
Choose the visible display explicitly. `flexFromMd` is hidden below 48rem and
flex above it; `flexBelowMd` does the reverse. `inlineFlexFromMd` and
`inlineFlexBelowMd` are the inline-flex pair. There are also `flexFromSm`,
`blockFromSm`, `blockFromMd` and `blockFromXl` entries.

Each style names both display states. A later StyleX style replaces the whole
property, including its conditions. A style that only said when to hide would
discard the component's display value at other widths.

Hidden content is absent from the accessibility tree too. Keep essential
actions available at every width.

## Text and headings

[Text](https://www.arene.style/docs/components/text) defaults to a span and inherits its size, weight
and color. Set only the axes you need. Use `render={<p />}` for a paragraph.
[Heading](https://www.arene.style/docs/components/heading) defaults to an h2 with semibold weight and
tight tracking. `level` sets the document hierarchy and a default size for that
level. Set `size` to change the appearance without changing the level.

Use these components for standalone text. Inside a control whose style already
owns typography, ordinary text inherits that style without another wrapper.
A mixed entry can read `text` and its paired `leading` directly.

## A small page

The outer Container owns the inline padding. Stack owns the vertical spacing
and the header's responsive direction. Grid fits project summaries into the
available width. Each summary's mixed entry keeps its color and padding together.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { Container } from "@/components/ui/container"
import { Grid } from "@/components/ui/grid"
import { Heading } from "@/components/ui/heading"
import { Stack } from "@/components/ui/stack"
import { Text } from "@/components/ui/text"
import { breakpoints } from "@/theme/breakpoints.stylex"
import { color, radius, space } from "@/theme/tokens.stylex"

const styles = stylex.create({
  header: { flexDirection: { default: "column", [breakpoints.md]: "row" } },
  summary: {
    padding: space.s4,
    backgroundColor: color.muted,
    borderRadius: radius.lg,
  },
})

export default function LayoutPage() {
  return (
    <Container render={<section aria-label="Projects" />}>
      <Stack gap={6} paddingBlock={6}>
        <Stack gap={4} justify="between" xstyle={styles.header}>
          <Stack gap={2}>
            <Heading level={1}>Projects</Heading>
            <Text render={<p />} tone="muted">
              Your team's current work.
            </Text>
          </Stack>
          <Button>New project</Button>
        </Stack>
        <Grid minWidth="narrow" gap={4}>
          {["Website", "Mobile app", "Documentation"].map((name) => (
            <Stack key={name} gap={2} xstyle={styles.summary}>
              <Heading>{name}</Heading>
              <Text size="sm" tone="muted">
                Updated today
              </Text>
            </Stack>
          ))}
        </Grid>
      </Stack>
    </Container>
  )
}
```
