# Paperchart State Diagram

> Render a state diagram (Mermaid `stateDiagram-v2` equivalent). Rounded-rect states laid out in layers by longest-path from the start pseudostate; back-edges (retry / reset transitions) drawn as loop-back arrows. Supports start (●) and end (⊙) pseudostates, labeled transitions, dashed transitions (error paths), and an accent state/transition.

- Skill: `shuakami/paperchart-state-diagram` (Agent Skill)
- Install (CLI): `npx skillmds@latest add shuakami/paperchart-state-diagram`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shuakami/paperchart-state-diagram/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: shuakami (https://skillmd.com/u/shuakami)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shuakami/paperchart-state-diagram

---


# paperchart — state diagram

States as rounded rectangles, transitions as curved arrows with event labels.
Automatic layered layout; cycles (retry / reset transitions) are drawn as
back-edges that don't distort the forward flow.

## When to use

- UI state machines (idle → loading → success / error).
- Request lifecycle diagrams.
- Game or protocol state transitions.

## Input shape

```json
{
  "data": {
    "direction": "LR",
    "states": [
      { "id": "init",    "label": "•",         "start": true },
      { "id": "idle",    "label": "idle",      "caption": "awaiting input" },
      { "id": "loading", "label": "loading",   "caption": "fetching data",  "accent": true },
      { "id": "ok",      "label": "success" },
      { "id": "err",     "label": "error",     "caption": "surface to user" },
      { "id": "end",     "label": "⊙",         "end": true }
    ],
    "transitions": [
      { "from": "init",    "to": "idle" },
      { "from": "idle",    "to": "loading", "label": "submit" },
      { "from": "loading", "to": "ok",      "label": "200",    "accent": true },
      { "from": "loading", "to": "err",     "label": "fail",   "dashed": true },
      { "from": "ok",      "to": "idle",    "label": "close" },
      { "from": "err",     "to": "idle",    "label": "retry" },
      { "from": "ok",      "to": "end",     "label": "exit" }
    ]
  }
}
```

## Pseudostates

- `start: true` renders a filled dot (●) instead of a rounded rect.
- `end: true` renders a filled dot with an outer ring (⊙).
- Give them an `id` and a placeholder `label` (e.g. "•" / "⊙"); the label is
  not drawn over pseudostates, only the symbol.

## Direction

`LR` (default) or `TD`. Works the same as flowchart.

## CLI

```bash
paperchart state-diagram -i data.json -o state.png
paperchart state-diagram --defaults -o state.png
```