isostate Get started →

Open source · YAML-first · SVG-native

Isometric 3D scenes, written like diagrams.

Create beautiful, scroll-driven isometric visuals with simple YAML — like writing a Mermaid diagram, but in three dimensions. Compile once, embed anywhere. No 3D engine required.

  • YAML scene authoring
  • < 20 KB runtime
  • Zero browser deps
  • SVG no 3D engine

Simple by design

Three steps from idea to animation.

If you can write a diagram, you can create an isostate scene.

01

Write

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.

02

Compile

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.

03

Publish

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
    add:
      elements:
        - id: server
          asset: server-box
          at: [3, 4]
        - id: client
          asset: browser
          at: [7, 4]
      connections:
        - from: {element: client}
          to:   {element: server}
          style: {pattern: dotted, stroke: "#0f5f4f"}
          ambient:
            - name: flow   # animated data flow
Ground only
01 / 07

See it live

Scroll to watch a route come to life.

The route on the left advances as you read — exactly how it works when embedded in your docs or product page.

Scene 01

Start with an empty isometric floor.

The first scene is intentionally quiet: just the SVG floor grid. That gives every following object a visible entrance instead of starting from a finished diagram.

  • Floor and layers are defined once in YAML
  • No 3D engine or canvas setup required
  • The scene can build from nothing as readers scroll
YAML scene shell
header:
  layers:
    - {name: ground, order: 0}
    - {name: streets, order: 2}
    - {name: vehicles, order: 5}
floor:
  size: [18, 13]
  visible: true
scenes:
  - id: ground-only

Scene 02

Bring in the street and houses.

The route now has context: a straight road, two larger houses, and a few trees in the corner. These are ordinary elements and connections added by a scene delta.

Layering Ground shapes, roads, buildings, labels, and vehicles each sit on explicit layers.
YAML add elements
- id: neighborhood-enters
  add:
    elements:
      - id: start-house
        asset: route-house-start
        layer: buildings
        at: [1, 9]
        size: 2
      - id: end-house
        asset: route-house-end
        at: [15, 6]
        size: 2
    connections:
      - id: main-road
        route: [[3, 8], [14, 8]]
        style: {variant: road}

Scene 03

Add labels and the navigation arrow.

Start and end labels appear, along with a blue route arrow from origin to destination.

  • Text labels are generated from YAML
  • Connections can be arrows, routes, or roads
YAML connection
- id: route-appears
  add:
    elements:
      - id: start-label
        asset: text
        at: [3, 7]
        text: {value: Start}
      - id: end-label
        asset: text
        at: [14, 7]
        text: {value: End}
    connections:
      - id: navigation-arrow
        route: [[3, 7], [14, 7]]
        style: {pattern: dotted, stroke: "#2f80ed"}
        start: dot
        end: arrow

Scene 04

Place the car at the start.

The car enters on the road, not on top of the house. From here the scroll position drives a continuous movement along the straight segment.

Entrance The scene can reveal one object at a time without changing the page layout.
YAML element entrance
- id: car-start
  add:
    elements:
      - id: route-car
        asset: route-car
        layer: vehicles
        at: [3, 8]
        enter: slide-in-left
  update:
    connections:
      - id: navigation-arrow
        style:
          pattern: dotted
          strokeWidth: 7
        ambient:
          - name: flow

Scene 05

Move the car and activate the route.

The car moves from the start of the road to the middle while the navigation arrow switches into an animated active state. The route and the object tell the same story at the same time.

  • Element movement is authored as a scene update
  • The arrow gives the movement a navigation feel
YAML movement
- id: car-center
  update:
    elements:
      - id: route-car
        at: [8, 8]
        ambient:
          - name: pulse
    connections:
      - id: navigation-arrow
        style:
          pattern: dotted
          strokeWidth: 7
        ambient:
          - name: flow

Scene 06

Drive to the destination.

The car reaches the end of the road. Keeping the road straight makes the interpolation easy to read and avoids awkward corner turns.

YAML final movement
- id: car-finish
  update:
    elements:
      - id: route-car
        at: [14, 8]
        ambient:
          - name: pulse
    connections:
      - id: navigation-arrow
        style: {pattern: dotted}
        ambient:
          - name: flow

Scene 07

Finish at the destination.

The destination is highlighted and the final label appears in the bottom right of the scene.

YAML arrival state
- id: destination-reached
  add:
    elements:
      - id: arrival-label
        asset: text
        at: [17, 12]
        text:
          value: Arrived
          align: end
          fontSize: 24
  update:
    connections:
      - id: navigation-arrow
        style: {pattern: solid}
        ambient: []

Use cases

Anywhere a static diagram feels flat.

isostate is a generic tool for 3D isometric visualisation. Here are the places where visual sequences make the biggest difference.

01

Architecture Docs

Reveal system complexity one layer at a time. Readers understand each component before the next arrives.

02

Product Tours

Walk new users through your product visually. Show features in context instead of describing them in text.

03

Presentations

Step through scenes like a slide deck. One YAML file, one compelling story for your audience.

04

Technical Blogs

Give long articles a visual rhythm. Let the diagram build as the explanation unfolds.

05

Onboarding Flows

Show rather than tell. Guide new team members through infrastructure step by step.

06

Release Notes

Make changelogs worth reading. Show what changed, where it fits, and why it matters — visually.

Why isostate

Designed to stay out of your way.

YAML you can actually read

Write scenes the same way you write configuration. No visual editor, no custom syntax — just a format anyone on your team can review and extend.

Scroll or step — you decide

Use scroll-driven mode for immersive docs and storytelling, or manual step-through for presentations. Same source file, different controllers.

Customisable to your brand

Theme with CSS variables. Bring your own SVG assets. Choose your colours, stroke widths, and floor styles. isostate doesn't impose a visual style.

Static, portable, fast

Under 20 KB gzipped. Deploys to GitHub Pages, Netlify, a CDN, or bundled in an npm package. No server component, no lock-in, no hassle.

Ready to start?

Make your docs come alive.

You'll have your first scene running in minutes. Start with the getting-started guide or browse the examples to see what's possible.