Components Chart
state-chart
Native state machine diagram — states as a numbered list, transitions as nested inline-code refs.
Use to show a finite-state machine — the discrete states a system can be in and the events that move between them. Authors write a numbered list; each state's index becomes its stable ref so transitions cite numbers, not names. The numbering is the layout: state i renders at row i, so there is no auto-layout problem to solve.
When to use
- Finite, named states with discrete events. When the slide is about a system with a small set of named places it can be in (Draft / Submitted / Approved / Archived) and the events that move between them (submit, approve, reject). The numbered authoring forces you to enumerate every state up front; the inline refs force you to be explicit about every transition.
- Sequential authoring as a forcing function. Numbering the states makes the author commit to an order. Reading the list top-to-bottom is reading the machine from start to terminal. This is the same forcing function that
list-stepsandagendaapply — a sequence the reader can scan in one pass. - Native theming without Mermaid overhead. Mermaid's
stateDiagram-v2works but requires a CSS override cascade with!importantto theme cleanly (seedocs/theming.md). A native state chart uses palette tokens directly — no overrides, no mmdc subprocess, no version-coupled SVG class names.
When not to use
- More than ~8 states. Vertical stacks of ten or more states stop reading as a machine and start reading as a list. If the system has many states, group them into phases and show one phase at a time, or step back to a higher-level abstraction. The chart's job is to make the topology obvious in one glance.
- Hierarchical or parallel states. v1 grammar is one flat list of states with one outgoing arrow per nested bullet. Composite states, orthogonal regions, history nodes — anything Mermaid's
stateDiagram-v2does and this layout doesn't — belong in a Mermaid fence via thediagramcomponent. - Continuous processes. If the diagram is really a workflow with stages that overlap or block (queue depth, throughput, capacity), a
ganttorkanbanchart reads better. State charts are for discrete, mutually-exclusive states the system flips between.
Slots
| Slot | Selector | Required | Description |
|---|---|---|---|
title | h2 | yes | Slide heading framing the state machine. |
eyebrow | p > code | no | Optional eyebrow naming the machine or domain. |
states | ol > li | yes | One li per state. Index is the stable ref. Trailing inline code is a closed metadata vocabulary: start, end, or one of the chart-status keywords (on-track, at-risk, blocked, done, live, decision, deferred, warn, pilot, fail). Multiple metadata tokens allowed; order is irrelevant. Unknown trailing codes are left in the rendered label. |
transitions | ol > li > ul > li | no | Outgoing transitions from a state — one per nested bullet. Each carries a single inline-code arrow event=>N or =>N (event optional). Target is a state index or the literal self for self-loops. Whitespace inside the inline code is insignificant. |
Anatomy
┌─────────────────────────────────────────┐
│ header │
│ State machine heading │
│ │
│ [Draft ] → [Review] → [Pub ] │
│ │
│ (back-edge: Review → Draft) │
│ │
│ footer 1/19 │
└─────────────────────────────────────────┘Variants
lr — Left-to-right
Lays the machine out horizontally (Mermaid direction LR) instead of the default top-to-bottom column. Forward skips bow below the row, back-edges above. Compose with inline for a horizontal chip row.
<!-- _class: state-chart lr -->
## Build pipeline.
1. Source `start`
- `compile => 2`
2. Compiled
- `test => 3`
3. Tested
- `deploy => 4`
- `fail => 1`
4. Deployed `end` inline — Inline
Drops the SVG edge layer; transitions render inline as chips inside each state node. Pure HTML — graceful fallback if the SVG layer is undesirable, or for very dense decks.
<!-- _class: state-chart inline -->
## Connection retry.
1. Connecting `start`
- `retry => self`
- `ok => 2`
- `fail => 3`
2. Connected `live`
- `disconnect => 1`
3. Failed `end` curved — Curved
Routes skip and back edges as single Bézier arcs instead of the default orthogonal racetracks (round-out, straight run, round-in). Each curve's peak is solved so its arc still clears the widest node in its span. Orthogonal to direction — compose with lr.
<!-- _class: state-chart curved -->
## Document approval (curved).
1. Draft `start`
- `submit => 2`
- `discard => 5`
2. In Review `on-track`
- `approve => 3`
- `revise => self`
- `reject => 1`
3. Approved
- `publish => 4`
4. Published `live`
- `archive => 5`
5. Archived `end`