# How to Create Guided Stories with Chapters for Archify Presentations

> Learn to create guided stories with chapters in Archify presentations. Embed chapter metadata in JSON and enable guided mode for interactive storytelling and chapter navigation.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-09

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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:

```json
{
  "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:

```html
<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`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html), producing output like:

```html
<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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html).
- Visual styling is handled through **CSS data attributes** and variables defined in [`experiments/mco-showcase/mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) at line 4530, while the controller logic resides in the bundled runtime script ([`archify-runtime.js`](https://github.com/tt-a1i/archify/blob/main/archify-runtime.js)) that the CLI generator automatically includes. The button toggles playback state and emits `chapter-change` events that drive the visual transitions.