Skip to content
Docs

Screens

Screens is the layer where each page gets composed. Architecture says which screens exist and what template + variant gives each its structure. Screens fills in the chrome (shells), the per-zone content (chips), and the overlay rules — once per surface the page appears on.

What Screens captures

Three things, all in one file:

  • Shells — the persistent chrome that wraps a group of pages (sidebar nav, top nav, tab bar, and so on).
  • Compositions — one per page per surface. The zones defined by that surface's variant, each filled with content chips.
  • Global overlays — rules that map a signal (e.g. "destructive action") to an overlay pattern (e.g. a modal dialog), applied across the project.

Shells

Each shell has:

  • Name + purpose — named by role (Main, Public), never by platform.
  • Pattern from the shell library: sidebar_nav, top_nav, two_tier_nav, collapsible_sidebar, minimal, and the mobile patterns tab_bar and mobile_stack.
  • Why this pattern — the written rationale for the choice.
  • Surfaces — which surfaces this shell serves. A product usually pairs a web shell with a mobile shell that shares its role.
  • Assigned pages — the pages this shell wraps.

Compositions

One per page per surface. Each composition has:

  • The page and surface it belongs to, and the shell that wraps it (or none — login pages and Mini Apps run chromeless).
  • Zones — the named slots defined by that surface's variant (list, detail, hero, aside, ...). Every zone carries a one-sentence purpose and an ordered list of content chips.
  • Chips — each names a content type from the 18-type catalog (data table, list, detail, form, filters, actions, navigation, media, metrics, ...) and carries its own what (the concrete content: "recipe rows: thumbnail, title, cook time") and why (the upstream signal that put it there). Chips render with a Lucide icon and label.
  • Actions — an item page's primary actions live in an actions chip with plain-word labels ("Scale servings", "Share", "Print"). Read-only pages still get theirs.
  • On mobile — a composition can carry a floating action button for the one action that deserves it.
  • Per-page overlays — overrides of the global rules for this page.

This is chip fidelity — labeled tags that name what content goes where, in what order, and why. Not rendered mockups. Spatial intent is the decision Screens commits; visual rendering is the implementer's job.

Mini App compositions

A Mini App composes like a page, plus its flow controls: whether stepping forward, going back, and skipping are available. It never gets a shell — the takeover is its chrome.

Global overlays

Each rule has a signal (what triggers it), a pattern from the overlay library (modal_dialog, right_panel, slide_over, bottom_drawer, full_screen_overlay, popover, inline_expansion, and the mobile action_sheet), and optional surfaces — a phone-only action-sheet rule is normal.

The canvas

[Screenshot TODO: Screens home view with four stacked sections — Shells, Pages, Mini Apps, Overlays — and the surface switcher in the page header.]

Screens renders as a home grid + drill flow:

  • Home view — stacked sections: Shells (pattern thumbnails), Pages (silhouette cards), Mini Apps (takeover-framed cards, shown only when the project has them), Overlays (rule rows).
  • Page drill — click a page card → the page view: the compose canvas up top, then purpose, page template, why this template, and where it appears. Click a zone to edit its chips in the right panel; click a chip to edit its what and why.
  • Shell drill — click a shell card → the shell view: name, a live render of the chrome, purpose, the pattern picker, why this pattern, and the assigned pages.
  • Overlay rules — click a rule → its detail panel opens on the right; the grid stays put.

On multi-surface projects the surface switcher in the header flips every view to that surface's shells and compositions.

The file written

design/screens.json — one file, top-level shells[] + compositions[] + globalOverlays[].

The skill

/screens populates the layer.

  • Reads: everything in design/sources/, design/project.json, design/architecture.json (the per-surface layouts), design/ontology.json, and design/screens.json if it exists.
  • Writes: design/screens.json.

Behavior:

  • Creates shells per surface from the project shape — a web shell and, on mobile surfaces, its tab-bar counterpart sharing the same role.
  • Composes each page on each surface that already has a layout, with variant-aware zone fills and a written purpose for every zone and chip. Surfaces without a layout are skipped and reported; give them one in Architecture first.
  • Puts primary actions on item pages, even read-only ones, and elevates at most one to a floating action button on the phone.
  • Sets global overlay defaults from task shapes, tagging platform-specific rules to their surfaces.
  • Refines one surface without touching the others.

You confirm, adjust, or recompose directly on the canvas.

The recipe example

The recipe-scaling tool's Architecture produces:

Shells

  • Main — top_nav on desktop web (app name left, preferences right). Wraps Recipes, Recipe, Preferences.

Compositions (desktop web)

  • Recipes (card_grid : with_filters): filters zone → filters chip; grid zone → cards chip ("recipe cards: photo, name, servings").
  • Recipe (detail_page : with_aside): header → page title + media chips; body → list chip (scaled ingredients) + form chip (target servings); aside → list chip (saved ratios); actions chip with "Scale servings", "Save ratio", "Share".
  • Preferences (settings : sectioned): body → one form chip per settings group.

Global overlays

  • "Confirm destructive action" → modal_dialog. Applies across the project so deleting a saved ratio always confirms the same way.

What Screens is not for

  • Template choice. That's Architecture — the template + variant per surface lives on the screen.
  • Visual treatment. Colors, typography, spacing, density. Denote captures none of it. The implementer adapts the chip arrangement to the target project's design system.
  • Pixel-perfect drawing. Fidelity is deliberately low. Labeled chips, not mockups.

The discipline: Screens commits content in zones at chip fidelity. Everything visual is deferred to the implementer.

Where to next