Editing states

Every state holds a block of source that renders live — JSX for React projects, <template> for Vue projects (single-file component syntax). The editor exposes that source in three parallel surfaces — the code editor, the Layers panel, and the canvas itself — all of which modify the same source.

The code editor

The Code panel — one of the floating panels you open from the dock along the bottom — is a code editor with syntax highlighting. It is a plain text editor — not a WYSIWYG layer — so the source on disk is exactly what is typed. The editor is the authoritative surface when anything unusual is needed (custom expressions, conditional rendering, comments in the code).

You don't have to wrap a state in a single root element. Type as many top-level elements as the state needs — for React, Statecraft tidies them into a fragment (<>…</>) for you once you pause typing, so you never fight React's one-root rule. Vue templates are multi-root natively, so nothing is added.

Parse errors are shown inline in a red banner as they happen. Runtime errors from the preview iframe are shown the same way. An error in one state does not affect the rendering of sibling states.

The component palette

The Components panel (open it from the dock) is a palette drawn from the active project's design system. Components are grouped by the category field in the YAML — Form, Layout, and so on.

Clicking a component inserts its snippet into the JSX at the current cursor position. The snippet is whatever the design system's YAML declares it to be, so design-system authors have full control over what shows up when a component is added.

Components can also be dragged from the palette onto the canvas. A live preview of the component follows the cursor. Dropping on an element in a frame inserts as a child / sibling; dropping on an empty frame populates it; dropping on empty canvas spawns a new canvas element. See Selecting & arranging elements for the full drag behaviour.

The Layers panel

The Layers panel (open it from the dock) is a tree view of the current state's JSX. Clicking a node selects the matching element on the canvas; dragging a node reorders it in the tree, which rewrites the JSX.

The Layers panel reaches elements the canvas cannot select directly — absolutely-positioned overlays, hidden elements, deeply nested children. It also shows the element hierarchy at a glance.

Grouping elements

Select two or more sibling elements and press Cmd+G to wrap them in a container, or Cmd+Shift+G to wrap them in a flex container ("Flex Group"). The new container becomes the selection, and a single Cmd+Z reverts the whole group. Cmd+Shift+U ungroups — it lifts a selected container's children back out and removes the wrapper.

By default Group uses a plain <div> and Flex Group an inline-flex <div>. To wrap in your own layout components instead, open the Details card (top-left) and pick them under Frame defaults → Grouping — per project, or save a workspace-wide default that every project on that design system inherits.

Sketching variants on the canvas

When a design decision needs two or three alternatives side by side, drag an element out of a state frame onto the empty canvas. It becomes a canvas element — a free-floating bit of JSX rendered through the same design system, with all the same editing behaviour as a state's content. Hold Alt / Option to copy instead of move, so the original stays put while the variant lives on the canvas.

Canvas elements are for tinkering outside the flow — neither they nor their inner elements can be targets of transitions, and they don't appear in Play. When a variant is ready, drag it back into a state frame to promote it into the flow.

Adding text

The Text tool — the T key, or the text button in the dock — drops a text element and puts you straight into inline edit. Click a frame to place it inside, or click empty canvas to spawn a new frame around it.

If your design system declares a typography ramp, the Text button gains a dropdown to pick a style — Heading 1, Body, Caption, and so on — so new text lands in your system's real type styles instead of a bare <p>. With no ramp declared, it falls back to plain HTML roles (Heading 1–6, Paragraph, Caption, …).

To restyle text that already exists, select it and use the Text style dropdown in the Properties inspector. It swaps the element to another declared style (or HTML role) while keeping the words you wrote.

Inline text editing

Double-clicking a text node enters inline edit mode. The first double-click drills into a container; a second double-click on a leaf element puts the cursor in the text. Press Enter to confirm, Esc to cancel.

Inline text edits apply to three kinds of targets, in priority order: visible text content between tags, string props that map to a display label (Ant Design's Alert message, MUI's and Radix's label), and plain attribute strings. Non-leaf elements do not enter edit mode — double-click drills past them instead.

Undo and redo

Every edit — JSX changes, prop changes, element reorders, inline text edits — goes through a shared undo stack. Cmd+Z undoes, Cmd+Shift+Z redoes. The stack is per-session; it does not persist across reloads.

Adding, renaming, and removing states

States are managed from the States panel (open it from the dock). The + button at the bottom of the list creates a new one — or use the Add state button at the bottom-right of the canvas, next to Add comment and Add sticky. Each state has a name, a width preset, a height preset, and a handle for reordering. The pencil (rename) and trash (delete) icons are anchored on the right of each row. Renaming changes the displayed label only — the underlying state id is stable, so transitions and comments keep pointing at the right state.

You can also rename or delete a frame without opening the panel: hover a frame's title on the canvas (or select it) and the same pencil and trash icons appear right next to its name. The trash is hidden when only one frame remains, so you can't empty the canvas, and Cmd+Z brings back anything you delete.

New states auto-arrange left-to-right by their order in the States panel. To place a frame deliberately, drag it by its name — it stays where you drop it, and the auto-layout leaves it alone from then on. Drag a box around several frames (or Shift/Cmd-click their names) to select and move them together; reordering in the States panel still arranges any frames you haven't placed by hand.

Deleting a state removes it and any transitions that reference it. Comments pointing at the deleted state are not removed from the workspace, but they become orphaned (see Comments & feedback).