Scrollytelling design space

Design Space

A visual atlas for the thesis-backed patterns inside scrollytale-starter.

StructureLayoutTextTransition

Advanced/internal page. For everyday authoring, start with story-format.md. This page helps the runtime and AI reason about stories more deeply.

Overview

The source vocabulary comes from the thesis chapter on the scrollytelling design space and is organized into four dimensions:

• Structure
• Layout
• Transition
• Action

The copied icons live at:

• public/design-space/icons/
• docs/public/design-space/icons/

The runtime taxonomy lives in src/runtime/designSpace.js.

Why this page exists

To keep the academic model inside the starter without forcing ordinary authors to learn the whole taxonomy first.

What it powers

Docs, icon assets, normalized story metadata, AI prompting, and future runtime planning.

How It Maps To story.md

The starter keeps the same Markdown-first authoring model, but it now accepts richer design-space metadata.

Global Structure

You can still use the simple form:

structure: linear

You can also use the richer academic form:

structure:
  family: linear
  pattern: burger

Today the runtime still renders a linear DOM flow, but the extra pattern metadata is preserved for planning, AI prompting, and future runtime features.

Section Layout

You can still use the simple preset:

layout: scrolly-right

You can also attach design-space fields:

layout:
  preset: scrolly-right
  axis: vertical
  binding: float-to-text
  container: vis-container

This lets story.md describe both the starter preset and the academic layout language at the same time.

Scene, Segue, and Action

The thesis transition and action language now maps like this:

• scene: focus, guide, granularity, observation
• transition.segue: point-to-line, line-to-area, morph, division-merge, pack-unpack
• action.trigger: enter, exit, step, scroll
• action.affordance: header, in-line, tooltip

Example:

---
title: "Rental pressure across Melbourne"
structure:
  family: linear
  pattern: burger
data:
  sources:
    - id: rents
      path: ./data/rents.csv
---

---
id: widening-gap
layout:
  preset: scrolly-right
  axis: vertical
  binding: float-to-text
  container: vis-container
scene: granularity
transition:
  type: step
  segue: morph
action:
  trigger: step
  affordance:
    - tooltip
---

## The gap becomes visible at suburb level

::vis{type="line" data="rents" x="year" y="value" series="region"}
::

::step
The metro average hides the largest gaps.
::

::step
At suburb level, the spread becomes much wider.
::

Current Support Matrix

This page distinguishes three levels:

• Supported: runtime behavior exists now
• Metadata only: accepted and normalized, but not yet rendered as first-class behavior
• Still developing: not yet implemented in the runtime

Still Developing Highlights

Header navigation

Still developing

Needed for non-linear story entry points and chapter jumps.

Tooltip system

Still developing

Best implemented as a shared runtime component instead of one-off chart code.

In-line controls

Still developing

Useful for lightweight toggles and local exploration inside narrative paragraphs.

Segue transitions

Still developing

`morph`, `point-to-line`, and `pack-unpack` still need reusable visual transition primitives.

Structure

Pattern	Status	Notes
linear	supported	Default starter flow
parallel, bypass, branch, merge	metadata	Useful for authoring plans and future navigation work

Layout

Preset / Pattern	Status	Notes
chapter	supported	Default Markdown-first narrative section
hero	supported	Approximates an editorial opening
scrolly-left	supported	Sticky figure + text steps
scrolly-right	supported	Sticky figure + text steps
full-width	supported	Flow section without sticky scrolly
scrolly-overlay	supported	First-class overlay layout for text-over-vis scrolly sections
axis, binding, container, overlap metadata	metadata	Stored in normalized story objects

Transition

Pattern	Status	Notes
focus	supported	Scene label available now
guide	supported	Scene label available now
granularity	metadata	Accepted in syntax and normalization
observation	supported	Scene label available now
point-to-line	metadata	Needs reusable vis transition primitives
line-to-area	metadata	Same as above
morph	metadata	Same as above
division-merge	metadata	Same as above
pack-unpack	metadata	Same as above

Action

Pattern	Status	Notes
enter	metadata	Accepted in syntax, lifecycle hooks still thin
exit	metadata	Same as above
step	supported	Already wired via ::step + Scrollama
scroll	supported	Default scrolly motion model
header	Still developing	Needed for non-linear navigation
in-line	Still developing	Best added as embedded controls or toggles
tooltip	Still developing	Good candidate for shared runtime component

Why This Matters

This gives the project a shared language across:

• thesis writing
• case-study analysis
• story.md authoring
• AI prompting
• future runtime planning

The starter no longer has to choose between being academic or practical. The design space now acts as a bridge between the two.

Recommended Next Runtime Steps

1. Add scrolly-overlay as the next layout preset.
2. Turn transition.segue into reusable vis controllers instead of metadata only.
3. Add shared tooltip and header components so non-linear structures can become real runtime features.