Layout

Build a layout outside-in. Settle the shell and its region budgets before any content exists, then work inward. Content-first layouts drift into a padded column of cards, because every section ends up inventing its own container.

1. Scaffold: pick the shell, budget each region, and choose navigation
2. Structure: rank the content in each region, then pick the weakest container that groups it
3. Spacing: hold one content line per region, then tune gaps and density
4. Breakpoints: decide what each region does as width changes

This guide decides layout, not component APIs. Run npx astryx build "<idea>" to start from the closest template for your app type, and npx astryx component <Name> for a component's props.

Pick the shell and budget its regions before any content exists. Structural widths are the one place raw px belongs; everything inside them uses the spacing scale.

1. Pick the frame: AppShell for nav apps, Layout with LayoutPanel in a start or end slot for multi-pane tools, or a plain content column for documents and forms
2. Give every fixed region a width budget, so no region has to negotiate for space at render time
3. Read the content to set fill or capped: tables, charts, and boards fill their region; prose, forms, and lists cap with Layout contentWidth so lines never over-stretch
4. Set each region container policy, rows or card grid, before writing content

tsx
// Recommended budgets: SideNav 240–280, icon rail 64–72,
// side panel 340–420, filter rail 220–260.
<AppShell sideNav={<SideNav>{/* nav items */}</SideNav>}>
  <Layout
    content={<LayoutContent>{/* table fills its region */}</LayoutContent>}
    end={<LayoutPanel width={380} hasDivider>{/* detail */}</LayoutPanel>}
  />
</AppShell>
​
// Capped instead: 640 suits text and forms, 960 mixed content.
// Dividers stay full-bleed.
<Layout
  contentWidth={640}
  content={<LayoutContent>{/* settings form */}</LayoutContent>}
/>

Verify: every region has a width budget, a fill-or-capped decision, and a container policy written down before any content exists.

When the frame leaves navigation open, default to SideNav: it absorbs destinations you have not planned yet. App type and destination count are guiding indicators, not determining rules.

• SideNav, the default: grouping needed, customizable nav, items with secondary actions, or nav that collapses. Trackers, consoles, and settings usually start here
• TopNav: a shallow nav you expect to stay shallow, context that must stay visible, or a control- and filter-heavy page; add a TabList for a second level. Media libraries often sit here, over grid content
• Both: a genuine suite, where TopNav carries ecosystem-wide concerns (context switcher, global search) and SideNav carries product nav
• Neither: messaging and feeds use a column frame of rail, nav, stream, and panel

tsx
// Default: product nav on the side.
<AppShell sideNav={<SideNav>{/* items */}</SideNav>} />
​
// Shallow, stable nav on a control-heavy page.
<AppShell topNav={<TopNav>{/* items */}</TopNav>} />
​
// Suite: ecosystem concerns on top, product nav on the side.
<AppShell topNav={<TopNav />} sideNav={<SideNav />} />

Verify: you can state the reason in one sentence, and the choice still holds if the nav doubles in size. npx astryx build "<idea>" names the closest template, and its --skeleton shows the pairing already wired up.

Give every region one lead, then rank the rest with weight and color rather than size. Content uses two text colors, primary and secondary, and nothing dimmer: body copy needs no props at all.

• Body, the default: plain Text with no type, color, or size prop
• Lead: Heading at the level matching page depth, or body Text at a heavier weight
• Support: step to the secondary color, not to a smaller size
• Metadata: the supporting type, or a StatusDot or Token instead of prose

tsx
// Body copy takes no props. Text already defaults to body
// size in the primary color.
<Text>Credentials rotate every 90 days</Text>
​
<HStack gap={2}>
  <Text weight="semibold">Payments API</Text>
  <StatusDot variant="success" label="Healthy" />
  <Text color="secondary">v2.14</Text>
  <Text type="supporting">edited 3h ago</Text>
</HStack>

Squint test: blurred, you read lead, then support, then groups, in that order. If everything reads at once, raise contrast with weight and color, not borders and not smaller text.

Reach for the weakest container that reads as a group, and escalate only when it fails. Weakest to strongest:

1. spacing and gap: related items inside one group. The default rhythm
2. Divider: peers in a dense list or toolbar, or fencing a header from a scrollable body
3. Section: the default page-structure unit, related content under a heading. No border
4. Card: a self-contained widget (KPI tile, chart, gallery entry), or a hard boundary around critical content

tsx
// Records are rows in one Section, not one Card each.
// Recommended row height: 32–40px.
<Section padding={0}>
  <List header={<Heading level={3}>Members</Heading>} hasDividers>
    {/* ListItem per member */}
  </List>
</Section>

Decision test: records render as rows, Table for columnar and List for single-line; a self-contained widget or hard boundary is a Card; everything else is a Section.

A region can pin a header or footer while its body scrolls. Both are Layout slots, and padding set once on Layout reaches all three, so header, body, and footer share one content line.

• LayoutHeader in the header slot: the region title and its primary action
• Toolbar instead of LayoutHeader when the header carries interactive controls
• LayoutFooter in the footer slot: actions that commit the work and must stay reachable
• defaultHasDividers on Layout fences both at once, rather than hasDivider per slot

tsx
// padding on Layout reaches every slot, so all three align.
<Layout
  padding={4}
  defaultHasDividers
  header={<LayoutHeader>{/* title + primary action */}</LayoutHeader>}
  content={<LayoutContent>{/* rows */}</LayoutContent>}
  footer={<LayoutFooter>{/* Save and Cancel */}</LayoutFooter>}
/>

Verify: scroll the body. The header and footer stay put, their dividers run full-bleed, and all three still share one left content line.

Master-detail: selecting a row opens a fixed-width side panel instead of navigating away.

• LayoutPanel in the start or end slot of Layout, holding a fixed width budget
• hasDivider to fence it from the content region; isScrollable so long detail scrolls on its own
• For user-adjustable width, pair useResizable() with a ResizeHandle on the panel inner edge: after the panel in a start slot, before it in an end slot with isReversed
• The handle then owns the divider, so the panel sets hasDivider={false}
• Render an EmptyState when nothing is selected, so the region never collapses

tsx
// Recommended panel width: 340–420.
<Layout
  content={<LayoutContent>{/* rows */}</LayoutContent>}
  end={
    <LayoutPanel width={380} hasDivider isScrollable label="Details">
      {/* detail fields, or EmptyState when nothing is selected */}
    </LayoutPanel>
  }
/>
​
// Resizable: handle first in an end slot, and isReversed so
// dragging left widens the panel.
end={
  <>
    <ResizeHandle isReversed hasDivider resizable={panel.props}
      label="Resize details" />
    <LayoutPanel width={panel.size} hasDivider={false} />
  </>
}

Verify: at narrow widths the panel yields width instead of squeezing content (see Breakpoints), and only one element between the regions draws a border.

The container owns padding and child gaps; children zero their margins, and interior spacing is always a token. Pick one content line per region and hold it constant, not the padding: container_inset = content_line - component_intrinsic_inset.

• Text and Heading carry no inset, so the container takes the full padding
• List, Tab, Menu, and nav items carry a small inset, so the container gives up its padding and the component owns the line
• Table cells carry a larger inset, so the container gives up its padding and the cell owns the line

tsx
// Target content line = 16px.
// Heading has 0 inset, so the Section takes the full padding.
<Section padding={4}><Heading level={3}>Members</Heading></Section>
​
// List has ~8px built in, Table cells 12–16px, so the Section
// gives up its padding and the component owns the inset.
<Section padding={0}><List>{/* items */}</List></Section>

Verify: draw one vertical line down the left of the region. Every label touches it; only hover and selected backgrounds cross it.

Grouping comes from contrast between tight and generous gaps, not one repeated value. If every gap is the same step, proximity does no work.

• Tight gaps bind: the smallest steps, used inside an item or field
• Generous gaps separate: several steps up, used between sections
• Reach for the in-between steps to tune cadence, rather than rounding everything to the same two values

tsx
// Tight binds at gap={1}–{2}, generous separates at gap={4}–{6}.
// In-between steps tune cadence: gap={3} = 12px, gap={5} = 20px.
<VStack gap={6}>
  <VStack gap={1}>
    <Text weight="semibold">Retention</Text>
    <Text color="secondary">Logs are kept for 30 days</Text>
  </VStack>
  <VStack gap={1}>{/* next label and value */}</VStack>
</VStack>

Verify: with every border removed, you can still name the groups from spacing alone. If you cannot, the intervals are too uniform. Form fields are the exception: FormLayout owns their spacing.

Match density to how often a region is used, and give every control in a row the same size so heights share a baseline.

• Compact: high-volume regions scanned fast, like logs, monitors, and large datasets
• Balanced: most Table and List surfaces
• Spacious: low-frequency or high-stakes rows, like settings or a short selection list

tsx
// Pair density with one control size: compact with sm,
// balanced with sm or md, spacious with md or lg.
<Table data={rows} columns={columns} density="compact" hasHover />
<Button label="Retry" size="sm" variant="ghost" />

Verify: every interactive element in a row shares one size, and that size is paired with the density of the region it sits in.

Lock what each region does as width changes, and pair every line of the contract with the prop or hook that enforces it.

• Divide: how many regions survive at each width
• Reveal: which regions earn their width only when there is room, and open on demand below that
• Resize: content flexes while fixed regions hold their budgets, and text stays capped by contentWidth so line length holds
• Swap: navigation becomes MobileNav at the AppShell mobileNav breakpoint; the side panel becomes a Dialog or BottomSheet, driven by useMediaQuery

tsx
// Recommended thresholds: 3 regions above 1024, 2 from 768,
// 1 below. Text reads best at 40–60 characters per line.
//   >1024  SideNav 256 | content | side panel 380
//   <=1024 panel moves to a Dialog     (useMediaQuery)
//   <=768  nav collapses to MobileNav   (mobileNav "md")
const isNarrow = useMediaQuery('(max-width: 1024px)');
​
<AppShell sideNav={<SideNav />} mobileNav={{breakpoint: 'md'}}>
  <Layout
    content={<LayoutContent>{/* rows */}</LayoutContent>}
    end={isNarrow ? undefined : <LayoutPanel width={380} hasDivider />}
  />
</AppShell>

Verify: every contract line names a mechanism, so the comment cannot drift from the behavior.