explanatory-playground

# Explanatory Playground

Build dev-only visualizations that make invisible system behavior visible.

## Workflow

### 1. Clarify the target

Use AskUserQuestion to understand what needs visualization:

```
question: "What kind of system should the playground reveal?"
header: "System type"
options:
  - label: "State machine"
    description: "Finite states with transitions (auth flow, form wizard, game state)"
  - label: "Data flow"
    description: "Data transforming through a pipeline (API → transform → render)"
  - label: "Event system"
    description: "Publishers and subscribers, event propagation"
  - label: "Algorithm"
    description: "Step-by-step logic (sorting, pathfinding, search)"
```

Then ask what's confusing:

```
question: "What specifically is hard to understand?"
header: "Hidden aspect"
options:
  - label: "Current state"
    description: "I can't see what state the system is in right now"
  - label: "Why transitions happen"
    description: "I don't know what triggers changes or why"
  - label: "Data shape"
    description: "I can't see what the data looks like at each step"
  - label: "Timing/sequence"
    description: "Things happen too fast or in unclear order"
```

### 2. Identify what's hidden

Based on answers, determine what to surface:
- **State** — Values that change over time
- **Transitions** — Events that trigger changes
- **Relationships** — How parts communicate
- **Logic** — Conditions, thresholds, rules

### 3. Pick visualization approach

| System | Visualization | Library |
|--------|--------------|---------|
| State machines | Node-edge graph | react-flow |
| Data flow | Directed graph / Sankey | react-flow |
| Events | Timeline | custom or recharts |
| Algorithms | Step animation | custom |
| Render cycles | Component tree + diffs | custom |
| Animations | Timeline scrubber | custom |
| CSS/Layout | Box model overlay | custom |

See [references/patterns.md](references/patterns.md) for layouts, code, and implementation details.