Skip to content
Docs

Layout

Layout is the layer where spatial arrangement gets decided. Structure says what pages exist. Layout says where everything goes on each page. Global shells define the persistent chrome (nav position, header, footer). Per-page region wireframes define how the inside of each page is partitioned. Surface patterns govern how secondary content appears (right panels, modals, drawers, overlays).

What Layout captures

Three top-level concepts, all in one file.

Global shells

A shell is the persistent chrome that wraps a set of pages. Most projects have one shell. Some have multiple: a consumer app shell, an admin shell, an auth shell, an onboarding shell.

Each shell has:

  • A name and a pattern ID from a shell library (sidebar_nav, top_nav, two_tier_nav, minimal, collapsible_sidebar).
  • Configuration overrides for the pattern (which side the nav sits on, whether the header is sticky, whether a footer is present).
  • An array of architecture node IDs from Structure, the pages assigned to this shell.

A page can only be in one shell. The shell decides the outer frame. The page's per-page layout decides the inside.

Per-page region wireframes

A region is a named semantic zone inside a page. Standard types: main, sidebar, inspector, toolbar, header, footer, left_pane, right_pane, aside.

Each region has:

  • A type from the standard set.
  • A size (CSS grid-style, like 1fr, 320px, 2fr).
  • A content reference pointing at a pattern assignment from Map or a content type label.
  • fixed, whether the region has fixed positioning.
  • scrollable, whether the region scrolls independently.
  • Optional nested children (from split operations) with a direction (horizontal or vertical).

Regions form a tree. Splitting a region produces two children with a direction. This is how you build asymmetric arrangements: a main region split horizontally into a list and a detail, a sidebar split vertically into filters and saved views.

Each per-page layout also records:

  • The architecture node ID this layout is for.
  • The shell ID.
  • A layout pattern ID from the library (single_column, two_column_split, three_column, card_grid_layout, stacked_sections, split_pane, asymmetric_wide_narrow, full_bleed, dashboard_grid, centered_form).

Surface patterns

Surfaces are how secondary content appears on top of or alongside the primary page content.

Two tiers:

Global surface rules apply across the whole project. They map a signal (e.g., "creating an entity of medium complexity") to a surface pattern (e.g., modal_dialog) so the same interaction always produces the same surface regardless of which page it fires from.

Per-page surface assignments override the global rules on specific pages. They map a trigger (e.g., "edit ingredient") to a surface pattern (e.g., slide_over) with configuration.

Surface patterns available: right_panel, modal_dialog, bottom_drawer, slide_over, full_screen_overlay, popover, inline_expansion.

The canvas

Layout renders as two connected editors.

Shell editor

Small, schematic thumbnails of the shells in the project. You select a shell pattern from the library, configure the chrome (where nav sits, whether there is a header, whether there is a footer), and assign pages to the shell.

Per-page wireframe editor

The main working surface. For a selected page, the inside is drawn as labeled rectangles representing regions. You can split a region horizontally or vertically, resize a boundary by dragging, assign content to a region (a pattern assignment from Map, or a content type label), mark a region as fixed or scrollable, and add nested splits for asymmetric arrangements.

Wireframes are schematic. Not rendered, not pixel-perfect. Like an architect's floor plan. Clear enough to make spatial decisions, not so detailed that the decisions spill into visual design.

A surfaces panel on the side lets you add per-page surface assignments. You pick a trigger (from the task steps that involve this page), pick a surface pattern, and set configuration.

The file written

Layout writes one file: design/layout.json. The top-level object has three arrays (shells, pageLayouts, globalSurfaces).

The pageLayouts array references architecture nodes by ID, which means renaming a page in Structure propagates silently into the Layout file. The same is true for pattern assignment references from Map.

The skill

/layout is the skill that populates the Layout layer.

Reads:

  • design/architecture.json (the page inventory from Structure)
  • design/governance.json (pattern assignments from Map, pattern implications drive default region arrangements)
  • design/tasks.json (task steps drive surface assignments)
  • design/layout.json (if it exists, preserves hand-drawn arrangements)

Writes:

  • design/layout.json

Behavior:

  • Creates a default shell based on the project shape. Single-persona projects start with a minimal shell. Multi-persona projects with admin and consumer surfaces start with two shells.
  • Prepopulates per-page region wireframes from pattern implications. A list_detail pattern → two_column_split layout pattern with a sidebar region and a main region. A dashboard pattern → dashboard_grid. A wizard pattern → centered_form with a single_column layout.
  • Prepopulates default surface assignments from task shapes. A multi-field creation task → modal_dialog with form inside. An inline edit action → inline_expansion.
  • Asks about surface-level choices where more than one default would be reasonable. Right panel or slide-over for detail editing. Modal or inline expansion for confirmation.

You confirm, adjust, or redraw directly on the canvas. The skill writes the commits.

How Layout relates to Map and Structure

Map decides the pattern. Structure decides the page. Layout decides the arrangement.

Each layer is narrower than the one before. Map has the widest decision space (which pattern from twenty, what configuration). Structure narrows it (which page, where in the hierarchy). Layout narrows it further (how the regions divide inside the page, what surface patterns are used).

This is deliberate. A wireframe editor that tried to do pattern assignment would be making arrangement decisions before the pattern was decided. A page inventory that tried to do wireframes would be making spatial decisions before the inventory was settled. The layers stay narrow so each one is reviewable on its own.

The recipe example

The recipe portion calculator's Structure and Map output produces this layout.

Shells

  • main-shell, pattern top_nav (a simple top bar with the app name on the left and a preferences link on the right). Config: sticky header, no footer. Page IDs: recipes-list, recipe-detail, preferences.

Page layouts

  • recipes-list, shell main-shell, layout pattern card_grid_layout. Regions: a main region filling the width with a grid of recipe cards. No sidebar. Scrollable. Surface assignments: none at this level.
  • recipe-detail, shell main-shell, layout pattern asymmetric_wide_narrow. Regions: a main region (2fr) containing the recipe photo at top, scaled ingredient list in the middle, and the scaling control docked at bottom; a sidebar region (1fr) showing saved scaling ratios. Surface assignments: edit ingredient → inline_expansion (tap the ingredient quantity to edit in-place); save ratio → popover (a small confirmation near the scaling control).
  • preferences, shell main-shell, layout pattern single_column. Regions: a centered main region with stacked preference sections.

Global surfaces

  • confirm destructive action → modal_dialog. Applies across the project so delete-a-recipe always confirms the same way.

Three pages, one shell, a handful of surfaces. The project is small, so the layout file is small.

What Layout is not for

  • Pattern decisions. Map territory. Layout references pattern assignments; it does not pick the pattern.
  • Page inventory. Structure territory. Layout references pages by ID; it does not add or remove them.
  • Visual treatment. Colors, typography, spacing, density. Those come from the aesthetic direction and the token source in Project Settings.
  • Pixel-perfect design. Wireframes are schematic. The point is to make spatial decisions, not paint the final screen.

The discipline is that Layout commits the arrangement only. Every visual decision is deferred to build time.

Where to next

  • Plan assembles everything into a build plan Claude Code can execute.
  • Structure is the input Layout reads from.
  • The design system pointer for the visual direction that Layout deliberately does not cover.