Repository navigation
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.
| 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. |
Each element has an id. Refer to the id in the beats.
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: rectangledraws a card.type: cylinderdraws a card in the shape of a database. -
widthsets the width of the card.minCardHeightsets the minimum height.
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 }-
childrenlists the elementids inside the group. -
layout.directioniscolumn(the default) orrow. -
layout.gapsets the space between children. The default is 12. -
layout.alignisstretch(the default),center, orstart.
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.
An arrow connects two elements.
- id: order
type: arrow
start: { id: customer }
end: { id: shop }
label: { text: POST /orders }-
startandendname the elements the arrow joins. -
label.textsets the text on the arrow. -
quiet: truedraws the arrow faintly, so that it does not compete for attention. -
linesets the connector style tosolid,dotted, orthick.
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. |
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.
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 examplenew. -
tone: the colour of the row. The options aregray(the default),blue,purple,green, andorange. -
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.
In edges, you can write an object instead of an id:
-
edge: the arrow'sid. -
data: a short text that travels along the arrow during this beat. -
back:trueto animate the arrow in the reverse direction, from its end to its start.
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: trueshows the scene label above the diagram. -
footer: trueshows the caption (say) of the current beat below the diagram.
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.
- The
captionkey in a scene is accepted, but it is not shown. Usesayin each beat. - The
routekey on an element is accepted, but it is ignored.
-
Reusing diagrams for the
headerandfooteroptions. - Known limitations.
© 2026 @vrsarin. FlowMotion documentation.