Open source · YAML-first · SVG-native
Create beautiful, scroll-driven isometric visuals with simple YAML — like writing a Mermaid diagram, but with isometric depth. Compile once, embed anywhere. No 3D engine required.
Simple by design
If you can write a diagram, you can create an isostate scene.
Describe your scene in YAML — elements, layers, connections, transitions. Small enough to review in a pull request, expressive enough to tell a full visual story.
Run isostate at build time. It validates your scene, catches broken links and missing assets, then produces a tiny optimised browser bundle — nothing heavy ships.
Drop the output on any static host. Choose scroll-driven storytelling, step-through presentation mode, or a static snapshot — one YAML source, your format.
A scene description looks like this
scenes:
- id: intro
elements:
- id: server
asset: server-box
at: [3, 4]
- id: client
asset: browser
at: [7, 4]
connections:
- id: request-path
from: {element: client}
to: {element: server}
style: {pattern: dotted, stroke: "#0f5f4f"}
ambient:
- name: flow # animated data flowScroll to scrub · Choose a scene to explore
Architecture → workflow → process
Bring a software story to life with photorealistic assets, flowing connections, and objects that move as you read. Every scene below is a small YAML delta.
Scene 01 / Request
A browser starts the journey. The small document is our request: follow it as the system picks up the work.
- id: request-received
elements:
- id: browser
asset: architecture-browser
at: [1, 8]
- id: request
asset: process-document
at: [1, 7]Scene 02 / API
The gateway rises into place and the same document moves toward it. A dotted connection carries the request from the browser into the API.
- id: api-entry
add:
elements:
- id: gateway
asset: architecture-api-gateway
at: [4, 8]
enter: rise-from-ground
update:
elements:
- id: request
at: [4, 7]Scene 03 / Service
A service and its database enter together. The request continues across the architecture while the completed gateway settles into a green status.
- id: service-and-data
add:
connections:
- id: service-to-data
from: {element: service}
to: {element: database}
style: {pattern: dotted}
message: {kind: orb, count: 1}
update:
elements:
- id: request
at: [7, 7]Scene 04 / Work
A queue and worker arrive above the service. The document changes direction and moves into the background workflow. The architecture now explains what happens over time.
- id: background-work
add:
elements:
- id: worker
asset: architecture-worker
at: [7, 2]
activity: {state: processing}
update:
elements:
- id: request
at: [7, 1]Scene 05 / AI review
An AI reviewer slides into the workflow. The request travels to the agent while the worker finishes. Animated messages make the direction of the handoff visible.
- id: ai-review
add:
elements:
- id: reviewer
asset: ai-reviewer
at: [10, 2]
enter: slide-in-right
activity: {state: processing}
update:
elements:
- id: request
at: [10, 1]Scene 06 / Approval
The agent hands its prepared result to a person. An amber connection and waiting status mark the approval boundary; the handoff asset shows who is passing work to whom.
- id: human-approval
add:
elements:
- id: approver
asset: human-approver
at: [13, 2]
activity:
state: waiting
color: "#c68927"
update:
elements:
- id: request
at: [13, 1]Scene 07 / Delivered
Approval turns green. The in-flight document and temporary handoff leave the scene, and the delivered result enters beside the browser. One journey, told with additions, movement, and exits.
- id: result-delivered
add:
elements:
- id: result
asset: workflow-end
at: [1, 2]
enter: fade-in-grow
remove:
elements:
- id: request
exit: fade-out-shrinkVisual authoring
Use the editor to place assets, tune scenes, and export the same `.isostate.yaml` that the CLI validates and compiles. It is the faster way to find anchors, object positions, and scene timing without giving up source-controlled text.
Use cases
isostate is a generic tool for isometric visualisation. Here are the places where visual sequences make the biggest difference.
Reveal system complexity one layer at a time. Readers understand each component before the next arrives.
Walk new users through your product visually. Show features in context instead of describing them in text.
Step through scenes like a slide deck. One YAML file, one compelling story for your audience.
Give long articles a visual rhythm. Let the diagram build as the explanation unfolds.
Show rather than tell. Guide new team members through infrastructure step by step.
Make changelogs worth reading. Show what changed, where it fits, and why it matters — visually.
Why isostate
Write scenes the same way you write configuration. Use it directly or export it from the visual editor — a format anyone on your team can review and extend.
Use scroll-driven mode for immersive docs and storytelling, or manual step-through for presentations. Same source file, different controllers.
Theme with CSS variables. Bring your own SVG assets. Choose your colours, stroke widths, and floor styles. isostate doesn't impose a visual style.
Under 20 KB gzipped. Deploys to GitHub Pages, Netlify, a CDN, or bundled from npm or JSR. No server component, no lock-in, no hassle.
Opt in to pointer interactivity with `element-click`, `element-enter`, and `element-leave` events, or export any scene as a standalone SVG or PNG. A dev-time diagnostics overlay shows grid anchors and connector routes while you tune positions.
Already have a flowchart? Run `isostate mermaid2dsl` to turn a supported Mermaid diagram into a starting `.isostate.yaml` scene — deterministic output, no `mermaid` package shipped to the browser.
Ready to start?
You'll have your first scene running in minutes. Start with the story-first docs or browse the examples to see what's possible.