visual-screen-flow

A Claude Code skill for prototyping apps that have many screens or complex, branching state. Instead of building and inspecting pages one at a time, it lays every screen of a flow on one infinite canvas, connected with arrows and annotations — where each node renders a real, runnable component from your repo, not a wireframe.

The core idea

        ┌─────────┐   on success   ┌───────────┐   open cart   ┌────────┐
        │  Login  │ ─────────────▶ │ Dashboard │ ────────────▶ │  Cart  │  ...
        └─────────┘                └───────────┘               └────────┘
         (real LoginForm)          (real Dashboard)            (real CartView)
        └──────────────── lane: auth ───────────────┘  └──── lane: purchase ────┘

   note: locked account → support link instead of the form

• Screens are real components. Each node on the canvas renders the same code that ships, resolved from your repo by a stable ref.
• The flow overlay is separate. Arrows, grouping shapes, sticky notes, swimlanes, and node positions live in a portable <name>.flow.json manifest — never inside component code.

The one non-negotiable rule: separation

The canvas-only visualization data and the real components are stored separately, always:

Lives in the flow manifest (*.flow.json)	Lives in your repo
arrows, shapes, sticky notes, swimlanes	the real component source for every ref
each screen's position / size / lane	the registry/resolver mapping ref → component
component.ref (a reference only) + overlay props	element hooks for screen.element addresses

The manifest references each component by a stable key or import path and never embeds component source. Where components live is discovered per repo — the skill adapts to your conventions instead of imposing its own. This keeps real code clean and reusable while flow overlays stay iterative and throwaway.

Install

Copy the skill directory into your Claude Code skills folder:

# user-level (all projects)
cp -R visual-screen-flow ~/.claude/skills/

# or project-level
mkdir -p .claude/skills && cp -R visual-screen-flow .claude/skills/

It triggers automatically when you prototype multi-screen / multi-step / branching UI (checkout, onboarding, wizard, auth, state machines, error/empty/loading states, "show me the whole flow", …) — even if you never say "canvas".

What's inside

visual-screen-flow/
├── SKILL.md                          # the skill: when to trigger + the workflow
├── references/
│   ├── flow-manifest-schema.md       # authoritative *.flow.json schema
│   ├── component-discovery.md        # find where a repo keeps components + resolve refs
│   ├── rendering-options.md          # React Flow / tldraw / minimal custom renderer
│   └── capability-layer.md           # optional: let an LLM mutate the canvas via typed actions
├── assets/
│   └── checkout.flow.json            # a complete worked example
└── scripts/
    └── validate_flow.py              # schema + separation-rule validator (stdlib only)

Validate a manifest

python3 visual-screen-flow/scripts/validate_flow.py path/to/checkout.flow.json
# cross-check refs against where real components live:
python3 visual-screen-flow/scripts/validate_flow.py checkout.flow.json --registry 'src/**/*.tsx'

The validator fails if any screen or annotation carries embedded component code (code/source/jsx/html/tsx/template/render) — enforcing the separation rule — and checks unique ids, dangling arrow/note/lane references, and the arrow style enum.

Design lineage

The architecture is inspired by the llm-ready-screen-flow-prototype reference: a canvas of nodes + edges over a registry of real UX components, with an LLM-and-UI-shared capability layer. This skill generalizes that into a framework-agnostic, repo-discovered, file-based format.

License

MIT — see LICENSE.