Draw a state diagram

A type: state document draws a state machine — states as pills, transitions as labelled arrows, with the UML entry dot and exit bullseye. The layered engine lays it out (so direction: LR reads like a pipeline and TB like a lifecycle), and the derived animation walks a packet through the transitions on loop.

The tersest machine

You don't have to declare states at all — any id a transition mentions is created as a pill. "[*]" is the entry/exit pseudo-state (quote it — the brackets are YAML syntax otherwise): a transition from "[*]" draws the entry dot, one to "[*]" draws the exit bullseye:

yaml

type: state
meta: { direction: LR }
transitions:
  - { from: "[*]", to: draft }
  - { from: draft, to: review, label: submit }
  - { from: review, to: published, label: approve }
  - { from: published, to: "[*]" }

beck

Refining states

Add a states: list to give a state a proper title, an accent, or a subtitle — anything not listed keeps its auto-created pill. Back-transitions (reject, retract) route side by side with their forward counterparts automatically:

yaml

type: state
meta: { direction: LR }
states:
  - { id: review, title: In Review, accent: warn }
  - { id: published, title: Published, accent: success }
transitions:
  - { from: "[*]", to: draft }
  - { from: draft, to: review, label: submit }
  - { from: review, to: draft, label: reject }
  - { from: review, to: published, label: approve }
  - { from: published, to: review, label: retract }
  - { from: published, to: "[*]" }

beck

Self-transitions

A transition from a state to itself draws a compact loop — retries, heartbeats, re-entrant states:

yaml

type: state
meta: { direction: LR }
states:
  - { id: open, title: Open, accent: primary }
transitions:
  - { from: "[*]", to: open }
  - { from: open, to: open, label: retry }
  - { from: open, to: closed, label: resolve }

beck

Scripting the animation

The derived flow traces each transition in machine order. For a guided story — highlight the happy path, fail a state, park a status pill — add a flow: block; state ids work anywhere node ids do. See Animate the flow.

To caption the walk without scripting a flow, add a note: to a transition — it becomes a narration line under the diagram as that transition fires. See Narrate the story.

Full field tables: states and transitions in the YAML schema. Generating one from C#: StateDiagramBuilder.