Skip to content

Storyboards

Vivek Sarin edited this page Nov 20, 2026 · 2 revisions

Storyboards

A storyboard is a step-by-step animation. It shows cards and arrows, and it reveals them one step at a time with a caption for each step. Use a storyboard when you want to walk your reader through a process, rather than show a fixed diagram.

FlowMotion detects a storyboard by its top-level scenes: key. A storyboard is written in YAML or JSON, in a flowmotion block or in a .flow file.

For every keyword, default, limit, and layout invariant, use the authoring reference. The cookbook contains complete parallel-call and row/graph examples.

Parts of a storyboard

Part What it is
title The title of the storyboard. Optional.
speed The default length of each step, in milliseconds. The range is 300 to 20000. The default is 2200.
elements The cards, groups, and arrows. Up to 300 elements.
scenes The chapters of the story. Each scene has a label and a list of beats.

Elements

Each element has an id. Refer to the id in the beats.

Cards

A card is a box with a title and an optional subtitle.

- id: customer
  type: rectangle
  content:
    - { type: title, text: Customer }
    - { type: subtitle, text: Places an order }
  width: 180
  • type: rectangle draws a card. type: cylinder draws a card in the shape of a database.
  • width sets the width of the card. minCardHeight sets the minimum height.

Groups

A group places other elements inside a labelled box.

- id: checkout
  type: group
  label: { title: Checkout }
  children: [customer, shop]
  layout: { direction: row, gap: 24, align: center }
  • children lists the element ids inside the group.
  • layout.direction is column (the default) or row.
  • layout.gap sets the space between children. The default is 12.
  • layout.align is stretch (the default), center, or start.

Exactly one card or group must be outside all groups: the layout root. Every other card or group has one parent. Arrows do not belong in children. A group without a label is a layout container with no visible outline or heading.

Arrows

An arrow connects two elements.

- id: order
  type: arrow
  start: { id: customer }
  end: { id: shop }
  label: { text: POST /orders }
  • start and end name the elements the arrow joins.
  • label.text sets the text on the arrow.
  • quiet: true draws the arrow faintly, so that it does not compete for attention.
  • line sets the connector style to solid, dotted, or thick.

Scenes and beats

A scene is a chapter. A beat is one step inside a scene. FlowMotion shows the beats in order.

scenes:
  - label: Step 1
    beats:
      - say: The customer places an order.
        edges: order
        show:
          customer:
            - { tag: cart, tone: blue, text: "2 items" }
      - say: The API accepts it.
        light: [shop]
        show:
          shop:
            - { tag: status, tone: green, text: Accepted, mark: new }

Each beat can use these keys:

Key What it does
say The caption shown for the beat.
ms The length of this beat, in milliseconds (200 to 60000). It overrides speed.
edges The arrows to animate in this beat. Give one id, or a list of ids.
show The rows to reveal inside a card. The key is the card's id.
light The elements to highlight in this beat.

Scene presentation

Use presentation to change the appearance of elements for one scene. Define category-wide settings under defaults, then override them by element ID under nodes, groups, or arrows.

scenes:
  - label: Focus on the request
    presentation:
      defaults:
        nodes: { opacity: 0.3, highlight: false }
        arrows: { visible: false, packet: false }
      nodes:
        customer: { opacity: 1, fill: '#e8f4ff', highlight: true }
      arrows:
        order: { visible: true, arrowheads: both, packet: true }
    beats:
      - say: The customer places an order.
        edges: [{ edge: order, data: request }]
        light: [customer]
  - label: Original appearance
    beats:
      - say: Presentation settings reset in the next scene.
Elements Presentation options
Nodes visible, opacity (0–1), fill, stroke, highlight
Groups visible, opacity, fill, stroke
Arrows visible, opacity, color, arrowheads, packet, highlight

arrowheads accepts start, end, both, or none. It changes the connector's appearance, not packet direction. Use back: true on a beat's edge to send a packet from the arrow's end to its start.

Colours accept a name, hex value, or rgb()/hsl() value. Scene colours take precedence over highlight colours; node highlights can still change outline width. Set highlight: false to suppress node or arrow highlights. Set packet: false to hide packets without stopping the timeline.

Hiding a node hides its rows. Hiding a group hides its outline and label, not its children. Hiding an arrow hides its line, label, and arrowheads, but not its packets. Visibility does not change layout or implicitly hide connected elements.

Each scene starts with the original appearance; presentation settings do not carry over. A storyboard without presentation settings retains its existing appearance and behaviour.

Presentation changes apply to the whole scene. To change visibility after a request, use another scene. This reset affects presentation only: card rows persist until another show replaces them.

Rows inside a card

Each row in show can use these keys:

  • tag: a small label on the left.
  • text: the main text.
  • meta: a secondary line.
  • mark: a marker on the right, for example new.
  • tone: the colour of the row. The options are gray (the default), blue, purple, green, and orange.
  • mono: shows the text in a fixed-width font, for code or identifiers.

A row can also be a small graph. Set type: graph, then use nodes (the names), links (pairs of names, such as [a, b]), and lit (the nodes to highlight).

Use show: {cardId: []} to clear that card's rows at the beat's reveal time. Rows begin appearing after packet travel, or after a short delay when there are no edges. The fade lasts 250 milliseconds.

Arrows in more detail

In edges, you can write an object instead of an id:

  • edge: the arrow's id.
  • data: a short text that travels along the arrow during this beat.
  • back: true to animate the arrow in the reverse direction, from its end to its start.

Showing a storyboard in a note

Use a src: block, the same as for any other diagram file. Storyboards can also use the header and footer options:

```flowmotion
src: ./order-story.flow
header: true
footer: true
height: 70vh
```
  • header: true shows the scene label above the diagram.
  • footer: true shows the caption (say) of the current beat below the diagram.

Playback

Storyboards normally use the same playback controls as other diagrams. Click the diagram to pause or play it. Add top-level interactive: true, or set it in the src: block, to play one beat per Next click instead. Edges listed in the same beat animate together.

The storyboard's speed is a beat duration in milliseconds, not a playback multiplier. The toolbar's Speed selector changes the playback rate. See Playback and timing for boundary and reduced-motion behavior.

Select SVG ↓ to download the whole animated storyboard with the current theme colors. The SVG plays independently and does not preserve interactive pauses. See Exporting diagrams.

Notes

  • The caption key in a scene is accepted, but it is not shown. Use say in each beat.
  • The route key on an element is accepted, but it is ignored.

Related pages

Clone this wiki locally