Skip to content
Docs

Screens

Screens is the layer where each screen 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. Three top-level sections: Shells, Pages, Overlays.

What Screens captures

Three things, all in one file:

  • Shells — the persistent chrome that wraps a group of screens (sidebar nav, top nav, etc.).
  • Compositions — one per screen. The zones defined by the screen's variant, each filled with content chips.
  • Global overlays — rules that map a signal (e.g. "destructive action") to an overlay pattern (e.g. modal_dialog), applied across the project.

Shells

Each shell has:

  • Name + purpose — a short description of what this shell is for.
  • Pattern from the shell library (sidebar_nav, top_nav, two_tier_nav, minimal, collapsible_sidebar).
  • Configuration — which side the nav sits on, whether the header is sticky, whether a footer is present.
  • Screen IDs — the screens this shell wraps. A screen belongs to exactly one shell.

Compositions

One per screen. Each composition has:

  • Screen ID — the screen this composition is for.
  • Shell ID — the shell that wraps it.
  • Zones — named slots defined by the screen's variant (list, detail, kpis, columns, hero, aside, ...). Each zone has a zoneName and an ordered array of content references (chips).

Each chip names a content type from the catalog (Heading, DataTable, Filter, CardGrid, Button, IngredientList, ...) plus optional rationale and metadata. Chips render with a Lucide icon and label.

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

Global overlays

Each rule has:

  • Signal — what triggers it (e.g. "creating an entity of medium complexity").
  • Pattern from the overlay library (right_panel, modal_dialog, bottom_drawer, slide_over, full_screen_overlay, popover, inline_expansion).
  • Configuration for the pattern.

Per-screen overlays override the global rules for one specific screen — those live on the composition.

The canvas

[Screenshot TODO: Screens home view with three stacked sections — Shells (gallery of pattern thumbnails), Pages (silhouette-dominant cards for each screen), Overlays (rule cards). One Page card highlighted, showing the drill-in affordance.]

Screens renders as a home grid + drill flow:

  • Home view — three stacked sections (Shells / Pages / Overlays), each a card grid. Single vertical scroll.
  • Shell drill — click a shell card → full-page editor. Pick pattern, configure chrome, assign screens.
  • Page drill — click a page card → PatternSchematic in compose mode. Variant silhouette with chip-hosting zones. Click a zone to select; edit chips in the right panel.
  • Overlay select — click an overlay card → right panel opens with the overlay's detail. Grid stays visible (overlays are small enough that the right panel is sufficient).

The file written

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

The skill

/screens populates the layer.

  • Reads: design/architecture.json + design/ontology.json + design/screens.json if it exists.
  • Writes: design/screens.json.

Behavior:

  • Creates a default shell from the project shape. Single-persona → one shell. Multi-persona with admin → two shells.
  • Picks variant-aware zone defaults per composition. A card_grid : with_filters screen gets filters + grid zones, prefilled with sensible chips. A wizard : centered screen gets steps + form + actions.
  • Sets global overlay defaults from task shapes. Multi-field creation → modal_dialog. Inline edit → inline_expansion.
  • Asks where multiple defaults would be reasonable (right panel vs slide-over for detail editing; modal vs inline expansion for confirmation).

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

The recipe example

The recipe-scaling tool's Architecture produces:

Shells

  • main-shell — pattern top_nav (app name left, preferences right). Sticky header, no footer. Wraps recipes-list, recipe-detail, preferences.

Compositions

  • recipes-list (template card_grid, variant with_filters):
    • filters zone → Filter chip.
    • grid zone → RecipeCard chip.
  • recipe-detail (template detail_page, variant with_aside):
    • header zone → Heading, Image chips.
    • body zone → IngredientList, ScalingControl chips.
    • aside zone → SavedRatios chip.
  • preferences (template settings, variant sectioned):
    • body zone → SettingsSection chips, one per group.

Global overlays

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

What Screens is not for

  • Template choice. That's Architecture — template + variant lives on the Screen.
  • Visual treatment. Colors, typography, spacing, density. Denote captures none of it. The implementer adapts the chip-list 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

  • Spec — rolls Screens and the upstream layers into a single SPEC.md the implementer reads.
  • Architecture — the input Screens reads from.
  • The four layers overview — where Screens sits in the pipeline.