Mermaid to isostate

Turn existing Mermaid diagrams into isostate visual stories.

The fastest path is not a fixed Mermaid renderer. Put your Mermaid source into a small workspace, install the isostate skills, let your AI agent create the YAML and assets, then use the editor to tune the result until every connection and label is clear.

Start with source control

1. Create a conversion folder.

Keep Mermaid input, generated assets, YAML, and compiled bundles in one folder. This makes the AI output reviewable and gives the editor a predictable place to read and write files.

mkdir mermaid-isostate-work
cd mermaid-isostate-work
npm init -y
mkdir assets public
touch diagram.mmd scene.isostate.yaml

Install the skills

2. Teach the AI both the DSL and the conversion workflow.

The authoring skill covers valid isostate YAML, assets, text, connections, and scene stops. The Mermaid skill adds the conversion workflow: extract the diagram facts first, then design a visual story without losing any source information.

npm install @sebastianwessel/isostate
npm install --save-dev @sebastianwessel/isostate-cli yaml

npx skills add sebastianwessel/isostate \
  --skill authoring-isostate-scenes
npx skills add sebastianwessel/isostate \
  --skill converting-mermaid-to-isostate-stories

Add the input

3. Place the Mermaid diagram in the folder.

The Mermaid file remains the source material, not a rendered widget on this page. For flowcharts, sequence diagrams, state diagrams, and `graph` aliases, the agent should preserve every participant, state, edge, label, return, async path, and branch.

# diagram.mmd
flowchart TD
  Request --> Router
  Router --> Auth
  Auth -- ok --> App
  Auth -- denied --> Response
  App --> Cache
  Cache -- hit --> Response
  Cache -- miss --> DB
  DB --> Response
  App -. async .-> Queue
  Queue --> Worker
  Worker --> DB

Generate the first story

4. Ask your AI to create assets and the isostate YAML.

The prompt should make data correctness non-negotiable. Visual choices are allowed, but they must make the original Mermaid easier to understand. Ask the AI to generate a small, consistent set of 3D isometric SVG assets, wire them into `header.assets`, then use routed connections and cumulative scenes to tell the flow.

Use the converting-mermaid-to-isostate-stories skill and
the authoring-isostate-scenes skill.

Read ./diagram.mmd and create a production-quality isostate story.

Hard requirement: Mermaid fidelity wins over visual polish.
- inventory every node, edge, edge label, branch, async edge, and direction
- create a source-fidelity table before writing YAML
- preserve labels such as ok, denied, hit, miss, and async as visible route labels
- split meaningful decisions into separate story beats
- introduce each element with its label before activating its first connection
- use real isostate connections with routed paths, not SVG arrow assets

Asset requirement:
- design a small enterprise-grade 3D isometric SVG asset set in ./assets
- create separate SVG assets for roles such as client/request, router, auth,
  app/service, cache, database, queue, worker, response, success, and error
- keep each asset browser-loadable, one logical object per file, with checked
  anchors in header.assets
- use consistent camera angle, light direction, stroke weight, shadows, and
  material palette across the whole asset set
- prefer polished product/enterprise metaphors over generic colored cubes;
  each asset should still read clearly at one grid cell
- create assets as standalone SVG files first, then reference them from YAML;
  do not hide important meaning inside text labels alone
- do not use emoji or font glyphs as semantic markers
- use generated primitives only for zones, route markers, and simple underlays

Scene requirement:
- write cumulative scene stops in scene.isostate.yaml
- place nodes on an intentional grid with at least one empty grid lane between
  major branches when space allows
- use a square or near-square authored grid by default, such as 16x16, then let
  the compiler derive the real floor from actual usage
- center important objects inside their region rectangles; do not place zone
  labels, node labels, or assets near a corner unless that is the point of the
  story beat
- keep canvas labels short: one word when possible, two words at most; move
  longer explanations into page copy, speaker notes, or comments
- keep labels in clear grid cells near their related objects; route labels
  belong beside the segment or near the receiving endpoint they explain
- keep completed routes muted, active routes animated, and branches separated
- use camera focus for each story beat so the active region fills the preview;
  reset only for final overviews
- finish with an overview where the original Mermaid flow is reconstructable

Verification:
- run npm exec -- isostate validate scene.isostate.yaml
- run npm exec -- isostate compile scene.isostate.yaml --out public/scene.isostate.js
- review every scene stop for missing labels, reversed arrows, misleading routes,
  crowded labels, and asset metaphors that contradict the Mermaid roles

Verify the result

5. Validate and compile before you trust the scene.

Validation catches DSL mistakes. Review catches semantic mistakes: missing Mermaid labels, reversed arrows, collapsed branches, overly compact layouts, or decorative assets that hide the actual flow.

npm exec -- isostate validate scene.isostate.yaml
npm exec -- isostate compile scene.isostate.yaml \
  --out public/scene.isostate.js

Make it production-ready

6. Fine-tune in the editor.

Use the editor for the work humans judge best visually: spacing, asset scale, label placement, route lanes, camera focus, and scene timing. The output remains normal `.isostate.yaml`, so the corrected version can go back into source control.

Open the website editor:
https://sebastianwessel.github.io/isostate/editor/

Load scene.isostate.yaml, fine-tune positions, labels,
route lanes, camera focus, and scene timing.
Export the corrected YAML back to the folder.

Open the editor