How to Create Guided Stories with Chapters for Archify Presentations

Archify converts static architecture diagrams into interactive guided stories by embedding chapter metadata in your JSON specification and enabling the guided: true render option, which automatically injects a play button and chapter navigation UI.

Archify is an open-source visualization tool that transforms complex system diagrams into interactive presentations. When you need to walk stakeholders through an architecture step-by-step, you can create guided stories with chapters for Archify presentations that sequentially highlight nodes and edges. The runtime automatically builds the navigation interface and handles the animation state based on author-defined chapter metadata.

Understanding the Guided Story Architecture

A guided story in Archify consists of three interconnected components that work together to create a linear narrative experience.

The Core UI Components

The story interface is constructed from three specific DOM elements defined in the Archify source:

• Play button – The toggle control that starts and pauses playback. In examples/web-app.html at line 4530, this appears as <button class="guided-view-play" id="guided-view-play"> with an embedded icon span and label.

• Chapter index – A hidden navigation container that holds the list of chapters. The markup at line 4540 of examples/web-app.html shows this as <nav class="guided-view-index" id="guided-view-index"><ol class="guided-view-chapters" id="guided-view-chapters"></ol></nav>.

• Chapter elements – Individual list items representing each step. The CSS rules in experiments/mco-showcase/mco-runtime.html (lines 2522-2639) define the styling for .guided-view-chapter, .guided-view-chapter-index, and .guided-view-chapter-title classes.

The runtime scans your architecture JSON and populates these elements dynamically, showing the chapter UI only when a chapters array is present.

Chapter Roles and State Transitions

Each node or edge in your diagram can participate in a chapter by declaring a chapter role in its metadata:

• enter – The element appears or becomes highlighted when the chapter starts.
• stay – The element remains visible and emphasized throughout the chapter.
• stay – The element remains visible and emphasized throughout the chapter.
• leave – The element dims or disappears after the chapter completes.

These roles map to CSS data attributes (data-chapter-preview-role) that drive visual changes without requiring additional JavaScript animation logic.

Defining Chapters in Your Architecture JSON

To create a guided story, you add a top-level chapters array to your architecture specification and reference chapter IDs from individual nodes and edges.

The Chapter Schema

The JSON structure requires two main sections:

{
  "nodes": [
    { 
      "id": "frontend", 
      "label": "Frontend", 
      "data": { 
        "chapter": { "id": "login", "role": "enter" } 
      } 
    },
    { 
      "id": "api",      
      "label": "API",      
      "data": { 
        "chapter": { "id": "login", "role": "stay" } 
      } 
    }
  ],
  "edges": [
    { 
      "from": "frontend", 
      "to": "api", 
      "data": { 
        "chapter": { "id": "login", "role": "enter" } 
      } 
    }
  ],
  "chapters": [
    { 
      "id": "login",   
      "title": "User logs in",   
      "description": "Show auth flow." 
    },
    { 
      "id": "fetch",   
      "title": "Data fetch",     
      "description": "Show cache miss → DB fallback." 
    }
  ]
}

The chapters.id field serves as the unique key referenced by nodes.data.chapter.id and edges.data.chapter.id. The runtime uses these references to determine which elements to activate during each step of the presentation.

Rendering the Guided Story

Once your JSON includes chapter definitions, you enable the guided view by passing the guided: true option to the renderer.

Basic Implementation

Import the Archify runtime and render your specification:

<div id="archify-root"></div>
<script type="module">
  import { Archify } from './archify/runtime.js';
  
  fetch('my-story.architecture.json')
    .then(r => r.json())
    .then(spec => Archify.render('#archify-root', spec, { guided: true }));
</script>

When guided: true is set, the runtime performs three actions:

1. Injects the play button and chapter index markup into the DOM.
2. Builds the ordered list of chapters from your JSON.
3. Wires event listeners to handle play/pause and chapter progression.

The resulting HTML structure matches the templates found in scripts/guide-template.html, producing output like:

<button class="guided-view-play" id="guided-view-play"
        aria-label="Play guided story" aria-pressed="false"
        title="Play guided story (P)">
  <span id="guided-view-play-icon">▶︎</span>
  <span id="guided-view-play-label">Play story</span>
</button>

<nav class="guided-view-index" id="guided-view-index" aria-label="Story chapters">
  <ol class="guided-view-chapters" id="guided-view-chapters">
    <li class="guided-view-chapter" data-chapter-id="auth" data-chapter-position="current">
      <span class="guided-view-chapter-index">01</span>
      <span class="guided-view-chapter-title">User authentication</span>
    </li>
  </ol>
</nav>

State Management During Playback

As the story progresses, the runtime updates several DOM elements:

• #guided-view-state – Displays "Ready", "Playing", or "Pause".
• #guided-view-count – Shows the current position (e.g., "Chapter 01 / 03").
• SVG element styles – Applies opacity and filter changes based on data-chapter-role attributes.

Customizing the Chapter UI

The visual appearance of guided stories is controlled through CSS variables and selectors defined in the runtime.

Styling Options

The default theme in experiments/mco-showcase/mco-runtime.html provides distinct visual states:

• enter – Typically rendered in green to indicate new elements.
• stay – Displayed in cyan to show active components.
• leave – Shown in red to indicate exiting elements.

You can override these styles by targeting the CSS variables such as --arrow-emphasis and --frontend-stroke, or by writing custom selectors for .guided-view-chapter elements. The chapter index remains hidden by default (display: none) and only appears when valid chapters are detected in the architecture JSON.

Summary

• Guided stories in Archify are created by adding a chapters array to your architecture JSON and referencing chapter IDs from node and edge metadata.
• Chapter roles (enter, stay, leave) control the visibility and emphasis of diagram elements during each step of the presentation.
• The play button and chapter index are automatically injected into the DOM when rendering with { guided: true }, as implemented in examples/web-app.html.
• Visual styling is handled through CSS data attributes and variables defined in experiments/mco-showcase/mco-runtime.html, requiring no additional animation JavaScript.

Frequently Asked Questions

What JSON schema defines chapters in Archify?

Archify uses a top-level chapters array where each object requires id, title, and description properties. Nodes and edges reference these chapters via data.chapter.id and specify their behavior using data.chapter.role (enter, stay, or leave). This schema is formally documented in archify/references/authoring-contract.md.

How do I control when nodes appear and disappear during a story?

Use the chapter role attribute in your node or edge data. Set "role": "enter" to highlight elements when a chapter begins, "role": "stay" to keep them visible throughout, and "role": "leave" to dim them after the chapter ends. The runtime applies these states through CSS selectors targeting data-chapter-preview-role attributes.

Can I customize the appearance of the guided story UI?

Yes. The chapter navigation and play button styles are defined in experiments/mco-showcase/mco-runtime.html (lines 2522-2639) using standard CSS. You can override the default colors by modifying CSS variables like --arrow-emphasis or by writing custom rules for .guided-view-chapter and .guided-view-play classes.

Where is the play button implementation located?

The play button markup is defined in examples/web-app.html at line 4530, while the controller logic resides in the bundled runtime script (archify-runtime.js) that the CLI generator automatically includes. The button toggles playback state and emits chapter-change events that drive the visual transitions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}