Skip to content
Docs

Structure

Structure is the layer where pattern assignments become a concrete page inventory. Map says what patterns exist. Structure says how many pages there are, where each one sits in the navigation hierarchy, and how pages connect to each other. Every page on the canvas is a node in an architecture graph with typed edges between them.

What Structure captures

Structure is a graph. Two top-level arrays: nodes (the pages) and edges (the navigation between pages).

Architecture nodes

Each page is a node with:

  • A name and a level (L1 top-level, L2 sub-page, L3 nested).
  • A wireframe type from a predefined set (landing, dashboard, product grid, product detail, article, settings, profile, search, error, generic, and more). The wireframe type drives the schematic thumbnail rendered on the canvas.
  • A parent node ID (null for L1 roots).
  • A group identifier for section clusters (e.g., "main", "account", "admin").
  • A position on the canvas (x, y).
  • Entity IDs from Extract that are displayed on this page.
  • A reference to a pattern assignment from governance.json (this is the link between Map and Structure).
  • A route (e.g., /dashboard, /recipes/:id).
  • A composition (single, sidebar-main, main-sidebar, dashboard, split, stacked) describing how UI regions arrange on this page.
  • Persona access, the persona IDs that can reach this page.
  • A landing view flag, which persona, if any, lands here by default.
  • Task IDs from Extract whose view concept drove this page (powers an overlay that highlights which pages support which tasks).

Each edge is a typed navigation step between two nodes. Edges have a type (e.g., "primary nav", "drill into detail", "modal invoke", "cross-section jump") and whatever labeling and metadata is needed for that type.

Edges matter because they represent the transitions users actually make. A list_detail pattern implies a specific kind of edge (click a row, navigate to detail). A dashboard with a "view full report" link implies a different edge. Capturing these edges explicitly means the navigation intent survives into the build plan.

The canvas

Structure renders as a ReactFlow canvas. Two views available through a toggle.

Sitemap view

Nodes are pages, rendered as schematic wireframe thumbnails based on the wireframe type. Edges are parent-child hierarchy lines (which page nests under which).

You can drag pages between parents, reorder within a level, split one page into two, or combine two into one. The hierarchy tree is editable directly on the canvas.

Same nodes, different edges. Edges are the typed navigation edges from the architecture graph. You see which pages link to which. You can draw new edges or adjust edge types.

Each node is selectable. Selecting a page opens a side panel where you can edit its name, level, wireframe type, route, composition, entity references, and pattern assignment reference.

The file written

Structure writes one file: design/architecture.json. The top-level object has two arrays: nodes and edges. Each node has the shape described above. Each edge references two node IDs plus its type and metadata.

The file is the full architecture graph in one place. Claude Code reads it to derive routes, to build the navigation config, and to decide which pattern goes on which page.

The skill

/structure is the skill that populates the Structure layer.

Reads:

  • design/entities.json, design/personas.json, design/tasks.json (Extract output)
  • design/governance.json (pattern assignments from Map, each assignment implies candidate pages)
  • design/architecture.json (if it exists, merges and preserves hand-placed positions)

Writes:

  • design/architecture.json

Behavior:

  • Starts from pattern assignments. Each assignment is a candidate page. Multiple assignments that share an entity and an adjacent task may collapse into one page with tabs or sections.
  • Derives routes from entity names and task verbs. Recognizable conventions (/recipes for the list, /recipes/:id for the detail, /settings for preferences) are used by default.
  • Groups pages into sections based on the entities they display and the personas that access them.
  • Draws typed edges automatically from pattern implications: list_detail patterns generate a drill edge from list to detail; dashboards generate "view full report" edges to their source pages.
  • Leaves positions at reasonable defaults. You reposition on the canvas; the positions are written back to disk.

How Structure relates to Layout

Structure says which pages exist. Layout says what goes where on each page.

This is a deliberate split. A page's place in the navigation hierarchy is a different decision from how its regions arrange spatially. Structure commits the first. Layout commits the second.

A page in Structure has a composition field (single, sidebar-main, stacked, etc.) that hints at the shape, but the actual region content, sizing, and surface pattern choices are Layout territory. Structure is the inventory; Layout is the floor plan.

The recipe example

The recipe portion calculator's pattern assignments from Map produce this architecture.

Nodes

  • recipes-list, name "Recipes", level L1, wireframeType product_grid, parent null, group "main", route /, composition stacked, entityIds [Recipe], patternAssignmentId points at the card_grid assignment, personaAccess [Home Cook], landingView Home Cook (lands here by default), taskIds [browse].
  • recipe-detail, name "Recipe", level L2, wireframeType product_detail, parent recipes-list, group "main", route /recipe/:id, composition main-sidebar, entityIds [Recipe, Ingredient, ScalingRatio], patternAssignmentId points at the detail_page with scaling control, personaAccess [Home Cook], taskIds [scale, save-ratio].
  • preferences, name "Preferences", level L1, wireframeType settings, parent null, group "account", route /preferences, composition stacked, entityIds [], personaAccess [Home Cook], taskIds [].

Edges

  • recipes-list → recipe-detail with type "drill" (user taps a recipe card, navigates to the detail).
  • recipe-detail → recipes-list with type "back" (native browser or explicit back control).
  • recipes-list → preferences with type "global nav" (the preferences link lives in a top bar visible from the list page).
  • preferences → recipes-list with type "global nav".

Three pages, four edges. A small app with the full architecture explicit.

What Structure is not for

  • Region arrangement. That is Layout. Structure says "this page uses main-sidebar composition." Layout says what goes in main, what goes in sidebar, and how they are sized.
  • Pattern decisions. That is Map. Structure references a pattern assignment; it does not re-decide the pattern.
  • Content. Copy, sample data, and exact labels are derived later from the entity model.
  • Aesthetic direction. That lives in Project Settings.

The discipline is that Structure commits to the inventory and the navigation graph. Everything about arrangement within a page is pushed to Layout.

Where to next

  • Layout takes the page inventory and commits region arrangements.
  • Map is the input Structure reads from.
  • The six layers overview for where Structure sits in the pipeline.