Reference

Core concepts

The vocabulary used across the app and these docs. Every later page builds on the seven terms below: workspace, project, state, transition, canvas element, snapshot, and design system.

Workspace

A workspace is the top-level container. Every project, design system, and member belongs to exactly one workspace. Workspaces hold their own list of design systems, their own member list, and their own subscription status. A single account can belong to many workspaces and switch between them from the account menu.

Members hold one of three roles: owner, editor, or viewer. Owners manage membership and billing; editors can modify projects and design systems; viewers have read-only access. See Workspaces, members & roles for the exact capability breakdown.

Project

A project is one feature's set of screens. The canvas renders every project as a horizontal grid of live-rendering frames — one frame per state — so the whole feature is visible at once.

Each project is bound to a single design system, chosen at creation time. All states in the project share that design system's components, tokens, and providers.

State

A state is one screen the feature can be in: idle, loading, success, error, and so on. Each state holds:

  • a block of JSX that renders live in a preview iframe,
  • a frame size — a width and height preset (see Devices, themes & zoom),
  • a name used in transitions and the Play-mode URL.

JSX is the source of truth for a state's UI. The visual tools around the canvas (the Properties inspector, the Layers panel, drag-to-reorder, inline text editing) modify that JSX programmatically rather than maintaining a parallel representation.

Transition

A transition connects two states by an event name — submit, retry, open. Transitions are declared in the Transitions panel; they attach to clickable elements via a data-transition attribute that the JSX references.

Transitions are how Play mode knows what to do when a button is clicked — clicking an element with data-transition="submit" navigates to whichever state that transition points at. See States & transitions.

Canvas element

A canvas element is a free-floating block of JSX that sits on the canvas outside any state frame. It's the same underlying thing as a state's root JSX — rendered through the same design system, with the same inner editing behaviour (selection, Properties inspector, Layers, inline text edit, comments) — just not tied to a state in the flow.

Canvas elements are the scratch surface for variants. Drag an element out of a frame to spin up a side-by-side alternative, paste a snippet with nothing selected to drop it on the canvas, or drag a component from the palette directly onto empty space. When the variant is ready, drag it back into a frame to promote it into the flow.

Canvas elements persist with the project and are included in snapshots, but they're hidden from Play — the canvas is a private studio surface, not part of the shareable deliverable.

Snapshot

A snapshot is an immutable, point-in-time copy of a project. Saving a snapshot freezes every state's JSX, the transition graph, the frame sizes, the goal and description, and any free-floating canvas elements. The version-history dropdown in the toolbar lists them most-recent first and lets any workspace member open one in a read-only view.

Snapshots are also the unit comments attach to. A comment on a snapshot stays pointed at whatever the element looked like at that point, even if the live project has moved on. See Snapshots & version history and Comments & feedback.

Design system

A design system is a YAML file stored on the workspace that describes where components come from and how to render them. It covers four things:

  • Source — the module the components are imported from (an npm package, a hosted ESM bundle, or plain HTML).
  • Scope — which exports become JSX tags.
  • Providers and style cache — any wrappers the library needs at the root of the iframe.
  • Tokens and components — the design tokens and the component insert-menu entries.

New workspaces start empty. Open Settings → Design systems → Browse gallery to install starters from the catalog — the Core group at the top carries Ant Design, Material UI, Radix, shadcn/ui, and plain HTML; ~27 more (Chakra, Mantine, Fluent, Bootstrap, …) sit below by category. Workspaces can also add their own by authoring YAML directly, compiling a bundle with the desktop app, or forking a gallery entry. See Bringing your library on for the paths and the YAML reference for the schema.

How the pieces fit

A typical working session is: pick a workspace, open a project, edit JSX in one or more states, sketch variants as canvas elements alongside them, wire transitions between states by attaching events to clickable elements, and save a snapshot when the version is worth coming back to. The design system chosen at project creation determines what components the JSX can use.