Screens and devices
A screen is one entry with an id and a layout tree; devices are viewport presets that set insets, chrome and $env comparisons.
Screens and devices
A screen is one entry in screens with a unique id (the target of navigate(id)) and a layout root node; a device is a viewport preset that sets dimensions, safe-area insets and platform chrome without locking the spec to one phone.
Examples
A named screen with a style and device:
Two screens, one navigating to the other, with a desktop preset on the second:
Anatomy
| Field | Type | Notes |
|---|---|---|
id | string | Required. Unique; the target of navigate(id). |
layout | LayoutNode | The root node. A screen without one renders nothing. |
title | string | Human label. |
summary | string | What the screen is for: who is on it, the one job they came to do, and what is deliberately not here. Aim for 100 words or fewer. |
route | string | URL path, for code generation. |
style | string | Overrides project.defaultStyle. |
device | string | The preset this screen is designed at; overrides project.defaultDevice. |
stateVars | Record<string, StateVarDef> | See State & expressions. |
status | "draft" | "in-review" | "approved" | "deprecated" | Workflow metadata; does not affect rendering. |
priority | "P0" | "P1" | "P2" | Workflow metadata. |
Device presets
The renderer ships presets that set viewport dimensions, safe-area insets, and platform chrome:
iphoneSE · iphone15 · ipadMini · ipadPro · mweb · web-sm · web-md · web-lg · web-xl · desktop · auto
Specs are not locked to them — a preset is just a viewport plus insets, and auto fills whatever space the host gives it. Presets matter for two things: safeArea padding resolves against the preset's insets, and $env.device expressions compare against its class (mobile, tablet, desktop). effectiveDevicePreset is the one resolver for screen → project → fallback, the orientation swap and auto's measured width; $env.breakpoint (xs < sm < md < lg < xl, by viewport width) compares by rank, so $env.breakpoint >= md reads naturally.
Stability
Screen fields listed above are part of the format contract in api-report.md. Workflow metadata (status, priority, summary) is validated but does not affect rendering; treat it as provisional for anything beyond authoring tools.
Requirements
A document carries its requirements beside the screens that answer them — what the product must do, the criteria that say it does, and links validate() checks.
State and expressions
Each screen declares stateVars as a string map; showWhen/hideWhen take a small expression language over that state, $env and $hover (the pointer inside the nearest hoverGroup).