layout

Layout

Choose the structure that serves the user's task. Inventory actual routes, shared regions, tokens, and primitives before creating a new shell.

Work

• Name the primary task and rank its content. Separate reading surfaces, comparison surfaces, and workspaces instead of applying one dashboard template everywhere.
• Map regions in DOM/reading order, key alignments, width limits, and scroll ownership. Identify what persists across routes.
• Choose whether to preserve, repair, refine, or recompose the existing layout. A broad improvement request permits meaningful restructuring while preserving product constraints.
• Define the mechanics of narrow-screen change by content pressure: what wraps, stacks, moves into a drawer, or scrolls locally. Follow the page's content priority when one exists, and keep essential actions and data accessible.
• Use intrinsic sizing, shrinkable grid/flex children, and local overflow for wide data. Do not hide page overflow to conceal a sizing defect.
• Reuse primitives and shared dimensions. Add a shell only when it owns a real repeated relationship.

Deliver

A region map or implementation with responsive behavior, shared ownership, and acceptance checks. Do not invent testimonials, metrics, or pricing to fill a section skeleton.

## Layout plan

Surface: Shells: Regions in reading order: Shared dimensions: Responsive behavior: Acceptance checks:

Test real long labels, sparse and dense content, narrow/intermediate/wide sizes, and text enlargement. At a fixed width, compare short and long routes and open overlays for movement of persistent regions.

A planning request needs a clear structure; a build request needs a rendered result. Use `$craft` when composition, typography, and visual character also need development. It is not required for a small sizing repair.

## Worked example

```markdown
## Layout plan

**Surface:** Dashboard plus public site; detected primitives reused, no new shell library
**Shells:** Detected marketing, dashboard, and auth preserved; no new shell added
**Regions in reading order:** Dashboard: nav → header → main; marketing: nav → hero → how it works → features → footer; auth: centered card with no chrome
**Shared dimensions:** Reuse detected shell tokens; limits set from actual table width and longest labels
**Responsive behavior:** Nav becomes drawer at narrow widths from content pressure; sections stack; tables scroll locally with shrinkable cells
**Acceptance checks:** Long labels wrap without breaking headers; empty and error states hold shell size; persistent regions do not shift when overlays open

Gotchas

• overflow: hidden on the page hides the too-wide element until the next long label; fix the child that will not shrink, often a flex or grid item missing min-width: 0.
• A region that jumps between routes usually takes its size from each page's content; give persistent regions a shared size.
• A scroll container inside another scrolling region traps the wheel and confuses keyboard scrolling.
• A shared width typed into several files drifts apart; define it once.
• Sample content hides layout failures; test the longest real label, an empty state, and an error state.

Boundaries

• Do not use to decide what a page says or which content comes first; use $hierarchy instead.
• Do not use to choose token values or theme pairs; use $tokens instead. A missing token system is not a blocker: reuse detected values and note the gap.
• Do not use for visual character, typography, and polish beyond structure; use $craft instead.