Skip to content

Authoring Reference

Vivek Sarin edited this page Nov 20, 2026 · 1 revision

FlowMotion authoring reference

This is the canonical authoring entry point for people and AI coding tools, including Claude, Codex, Cursor, and Copilot. It defines FlowMotion's YAML keywords and their behavior. Use the complete examples in the authoring cookbook as starting points for complex diagrams.

Compatibility: This reference describes the current development implementation, checked on 2026-11-19. Scene presentation, interactive playback, and the SVG download button are development features; do not assume an older installed release supports them. Match the reference and schemas to the plugin build you use.

Authoring contract

  1. Choose one input format per file. Prefer storyboard YAML for narrated scenes and event YAML for dependency-driven execution.
  2. Use only the keywords documented for that format. FlowMotion implements a subset of Mermaid and PlantUML, not their complete languages.
  3. Use stable IDs and reference existing elements. Do not use display labels as references.
  4. Quote hex colors and text containing YAML punctuation. Write booleans as true or false, not "true" or "false".
  5. Keep layout, presentation, packet direction, and execution order separate.
  6. Validate syntax and references, build the model, then inspect playback and the exported SVG. Parsing alone does not prove a diagram looks correct.
  7. Report unsupported requests rather than inventing fields such as position, x, y, onClick, next, disabled, or activeColor.

The tables below enumerate author-facing YAML keys, including accepted-but-ignored compatibility fields. Internal model properties and SVG attributes are not input keywords.

Choose a format

Format Identification Use when
Storyboard YAML or JSON Top-level elements and scenes You need nested layout, chapters, scene-specific colors/visibility, parallel messages, or guided presentation
Event YAML or JSON Top-level nodes, optionally flows and events You need graph layout, explicit dependencies, branching, waiting, or process durations
File embed Top-level src plus display options only A note reuses a diagram from another file
Text DSL First meaningful line is a supported diagram header A simple graph or an imported Mermaid/PlantUML-style description is enough
draw.io Recognized draw.io XML or SVG content You need authored coordinates or an existing drawing

A .flow extension does not select a grammar: the content does. Do not wrap a standalone .flow file in a Markdown fence. In a note, place its definition inside a flowmotion fence.

Shared display and embed keywords

Put display options at the top level of YAML definitions, or next to src in a note's embed block. Embed options override file options individually. For a text DSL or draw.io file, use an embed to set these options; do not append YAML to that file.

Key Type / values Default and behavior
src File path string Embed only. Relative to the containing note; / starts at the vault root. The runtime also tries a vault-root fallback for an unresolved relative path
controls Boolean Hidden unless enabled; shows the expanded playback controls, not the whole toolbar
interactive Boolean false. Wait for Next to play one beat or event interval
controlsPosition top, bottom top
mode fit, normal fit; Normal is unavailable inside slides
height Size string using px or vh; number in runtime Maximum height. Runtime numbers mean pixels; prefer explicit units for schema compatibility
width Size string using px, vw, or %; number in runtime Maximum width, centered. Prefer explicit units
header Boolean false. Storyboard scene name and beat counter above the diagram
footer Boolean false. Storyboard beat's say caption below the diagram
paper light, dark, none, or color string draw.io background sheet. none removes the sheet; Obsidian settings provide defaults

Size strings accept one to four digits before an optional decimal point and require a unit, for example 70vh, 900px, or 80% where that unit is allowed.

src accepts .flow, .yaml, .yml, .json, .svg, and .drawio at runtime. Prefer .flow, .drawio.flow, and .drawio.svg for plugin integration. An arbitrary SVG is not necessarily a valid draw.io source. Editor schema hints list a narrower set of extensions; the embed parser is authoritative for runtime resolution.

Only the keys in this table may accompany src. Do not add nodes, elements, scenes, animation, or other definition keys to an embed.

```flowmotion
src: ./architecture.flow
interactive: true
controls: true
header: true
footer: true
height: 70vh
```

Playback and export are different outputs

  • Interactive storyboards start at time zero. Next plays to the next beat start, or to the timeline end for the last beat.
  • All edges listed in one beat travel together. Next does not advance through each packet separately.
  • At a beat boundary, the next beat's initial appearance and caption can already be visible. Its motion waits for the next click.
  • For event diagrams, Next stops at the next event start/end boundary, including the final playback tail.
  • Interactive mode suppresses autoplay, continuous Play/Replay buttons, diagram-click playback, and looping. Expanded controls still allow reset, seek, and event-boundary stepping.
  • Reduced motion makes Next jump to the boundary. Ordinary non-interactive playback instead initially shows the finished state.
  • SVG ↓ downloads the entire animated timeline, not a still frame or only the current scene. It snapshots Obsidian theme colors into a standalone palette.
  • The SVG uses SMIL and repeats independently. It has no Next button and does not preserve interactive pauses, the current slider position, or player speed settings. SVG animation support depends on the viewer.
  • There is no export, gif, or svg configuration keyword. GIF export is not implemented.

Storyboard keyword reference

Document

Key Type / values Meaning
title Text, at most 500 characters Optional; defaults to storyboard. Also supplies the generated diagram ID/download filename
speed Number, 300-20000 Default beat duration in milliseconds; default 2200, not a speed multiplier
elements List, at most 300 Cards, groups, and arrows
scenes Nonempty list Scenes in playback order; every scene needs at least one beat

All shared display keys except src can also appear on a storyboard definition.

Elements

Key Applies to Meaning
id All; required Unique across the entire elements list. One to 64 characters from A-Z a-z 0-9 _ . > -; prefer letters, numbers, _, and -
type All; required rectangle, cylinder, group, or arrow
content Cards List of title/subtitle objects; a title entry is required
content[].type Card content title or subtitle
content[].text Card content Text, at most 500 characters
width Cards Number, 0-2000. Overrides natural card width; omit for automatic sizing
minCardHeight Cards Number, 0-2000. Minimum content-area height; header and padding are added
label Groups/arrows Mapping: groups use title; arrows use text
label.title Groups Visible group heading; omit the label for a layout-only group
label.text Arrows Static connector label, separate from a packet's data
children Groups List of existing card/group IDs; never arrow IDs
layout Groups Mapping of direction, gap, and align
layout.direction Groups column (default) or row
layout.gap Groups Number, 0-400; default 12
layout.align Groups stretch (default), center, or start. Column stretch expands child widths; row layout uses natural widths and top alignment unless centered
start Arrows; required Mapping containing id
start.id Arrows Existing source card/group ID
end Arrows; required Mapping containing id
end.id Arrows Existing target card/group ID
quiet Arrows Boolean; default false. Faint dashed connector styling
line Arrows solid (default), dotted, or thick
route Compatibility only Accepted string; currently ignored. Does not select a routing algorithm

Layout invariants:

  • Exactly one non-arrow element must be ungrouped: the layout root.
  • Every other card/group belongs to one parent group. Nesting cannot contain cycles.
  • Arrows remain outside children; they do not participate in the root count.
  • Grouping positions elements; it does not create arrows or execution dependencies.
  • Cards reserve room for their largest row set across all beats. Hiding an element does not reclaim its space.
  • An unlabeled layout-only group has no visible outline or label to style.

Scenes and beats

Key Scope Meaning
label Scene Optional name; defaults to scene 1, scene 2, etc.
caption Scene Accepted string but ignored; use a beat's say instead
presentation Scene Appearance settings for this entire scene; see the next table
beats Scene Nonempty list of steps. At most 300 beats across the storyboard
say Beat Caption text; display requires footer: true
ms Beat Number, 200-60000 milliseconds; overrides the document's speed for this beat
edges Beat One arrow ID, one edge object, or a list of IDs/objects. Omit for a beat without packet travel
edges[].edge Edge object Required existing arrow ID
edges[].data Edge object Optional packet label; omitted means an unlabeled moving dot
edges[].back Edge object Boolean; default false. true moves from the arrow's end to its start
show Beat Mapping from card IDs to row lists; new rows replace that card's previous row set
light Beat List of IDs to highlight during this beat. Use card IDs for visible node highlights; group IDs are accepted but do not highlight their children

Beats play sequentially. Every edge in a beat starts together and travels for min(1200, beatDuration * 0.45) milliseconds. An active connector can remain highlighted for the full beat after its packet arrives.

Rows begin appearing when that beat's packets arrive. With no edges, they start after min(250, beatDuration) milliseconds. The fade-in lasts 250 milliseconds. Rows remain until another show replaces them for the same card; changing scenes alone does not clear them. Use show: {cardId: []} to clear rows at that beat's reveal time.

The last beat is followed by a 1200-millisecond playback tail. This is part of the final interactive interval, not an extra authored beat.

Scene presentation

Key Structure Meaning
presentation.defaults Mapping Category-wide defaults for this scene
presentation.defaults.nodes Node settings All rectangle/cylinder cards
presentation.defaults.groups Group settings All visible group outlines/labels
presentation.defaults.arrows Arrow settings All connectors
presentation.nodes Map: card ID to node settings Per-card overrides
presentation.groups Map: group ID to group settings Per-group overrides
presentation.arrows Map: arrow ID to arrow settings Per-arrow overrides
Setting Nodes Groups Arrows Meaning
visible Yes Yes Yes Boolean, default true. false hides the element without changing layout
opacity Yes Yes Yes Number, 0-1; default 1
fill Yes Yes No Fill color
stroke Yes Yes No Outline color
color No No Yes Connector and arrowhead color
highlight Yes No Yes Boolean, default true. Allows automatic beat/packet highlighting; true alone does not activate an idle element
arrowheads No No Yes start, end, both, none; default is the original arrow's end head
packet No No Yes Boolean, default true. Show packet motion independently from the connector

Precedence is: original appearance, this scene's category defaults, then its per-ID overrides. Explicit scene colors take priority over state colors; a highlight may still change outline width.

Presentation resets at every scene; it is not inherited from the preceding scene. Repeat any settings you still need.

Visibility is not transitive:

  • Hiding a node hides its content rows, but not connected arrows.
  • Hiding a group hides its outline and heading, not its children.
  • Hiding an arrow hides its connector, labels, and arrowheads, but not its packet. Set packet: false to hide the packet.
  • arrowheads changes the decoration, not travel direction. Use back: true for a response packet.
  • There is no disabled state. Use opacity and highlight: false to de-emphasize an element.

Scene presentation applies for a whole scene, not per beat. Split a sequence into scenes when connector visibility or emphasis must change after a request.

Card rows and small graphs

show.<cardId> is a list of at most 20 row objects.

Key Values Meaning
type row (default), graph Row renderer
tone gray (default), blue, purple, green, orange Accent color
tag Text Small left label
text Text Main row text
meta Text Secondary text
mark Text Right-hand marker
mono Boolean Monospace row text; default false
nodes List of at most 12 names Graph row only: graph node names
links List of two-name lists Graph row only: edges such as [input, output]
lit List of graph node names Graph row only: highlighted graph nodes, not diagram card IDs

Use the text fields for type: row, and nodes, links, and lit for type: graph. Titles, captions, labels, and ordinary row text fields are limited to 500 characters.

Event-diagram keyword reference

Document and layout

Key Type / values Meaning
diagram Mapping Optional graph-wide settings
diagram.id ID Defaults to diagram; affects generated SVG IDs and filename
diagram.direction LR, RL, TB, BT Layout direction; default LR
diagram.edgeLabels Boolean Default false. Show flow payloads as static connector labels
groups List, schema maximum 200 Optional nesting definitions
nodes Nonempty list, at most 200 Graph nodes
flows List, at most 400 Connectors
events List, at most 1000 Optional explicit animation script
animation Mapping Playback settings below
animation.autoplay Boolean Default true; plugin settings, reduced motion, and interactive mode can prevent autoplay
animation.loop Boolean Default true; interactive progression stops instead
animation.speed Number, 0.1-10 Playback multiplier; default 1, unlike storyboard speed

Shared display options also apply. IDs contain one to 64 characters from A-Z a-z 0-9 _ . -. Prefer IDs that start with a letter. Labels and other ordinary text fields are limited to 120 characters.

Groups, nodes, and flows

Key Scope Meaning
id Group/node/flow; required Unique within its category; a node and group cannot share an ID
label Group/node Display text; node default is its ID, group label is optional
parent Group Existing enclosing group ID; no nesting cycles
shape Node Default rect; see all values below
group Node Existing containing group ID
lines Node Detail text under the title; schema allows at most 60 lines
style Node/flow Mapping of static style properties below
from Flow; required Existing source node ID, not a group
to Flow; required Existing target node ID, not a group
payload Flow Default packet text; also a static label if diagram.edgeLabels: true
line Flow solid (default), dotted, thick
head Flow Target decoration; default arrow
tail Flow Source decoration; default none
headLabel Flow Target-end label; use at most 20 characters for schema compatibility
tailLabel Flow Source-end label; use at most 20 characters
curve Flow Boolean, default false. Request a curved connector

All shape values: rect, round, stadium, diamond, circle, cylinder, hexagon, subroutine, parallelogram, start, end, bar, class.

All head/tail values: none, arrow, circle, cross, triangle, diamond, diamond-filled.

Style key Type Behavior
style.fill Color string Node fill in idle state
style.stroke Color string Node outline in idle state; connector color on flows
style.color Color string Node label/detail text
style.strokeWidth Number, 0-12 Node outline width in idle state or flow line width

The schema accepts the same style object on nodes and flows, but flows use stroke and strokeWidth, not fill or color. Active node states can override idle styles. Use storyboards when scene-specific appearance is required.

Events

Key Type / values Meaning
id ID; required Unique event ID
type Event type; required One of the types in the following table
flow Flow ID Required for transfer
node Node ID Required for process, emit, complete; use on wait for a visible waiting state
payload Text Packet label override
after Event ID or list Dependencies that must finish before this event starts
until Event ID or list wait: wait for these events to finish; also establishes ordering dependencies
select Event ID or list branch: direct child events to take; must be nonempty
duration Number, 0-60000 Milliseconds; defaults depend on type
fail Boolean, default false A finished process leaves its node in an error state
Event type Default duration Scheduling and visual effect
transfer 1500 ms Moving packet along flow
process 1200 ms Node processing state and progress bar
emit 600 ms Node activity and progress bar
complete 0 ms Marks a node completed
wait 0 ms Waits until all until targets finish; explicit duration is also a minimum interval from its start
fork 0 ms Dependency marker; child events sharing it in after can run concurrently
join 0 ms Starts after its live predecessors finish; skipped only if all after paths are skipped
branch 0 ms Selects listed direct child events; choice is authored, not calculated from live data

Events with no after can start at zero. File order does not serialize them. An ordinary event is skipped if an after dependency is skipped or excluded by a branch. A join can continue from the remaining live paths.

Every selected branch child must include the branch ID in its own after. All referenced events must exist. after/until dependencies must be acyclic. A reverse message needs a separate reverse flow; back is a storyboard edge keyword, not an event keyword.

If events is omitted or empty, FlowMotion derives node processes and flow transfers from the graph. Incoming packets precede node processing; outgoing packets follow it. Back edges are drawn but not scheduled. To control repetition, author separate uniquely identified events; there is no event type loop.

The event timeline has an 800-millisecond final tail. Parallel event examples are in the cookbook.

Colors and safe text

Use valid CSS color names, quoted hex colors such as '#2563eb', or numeric rgb()/rgba()/hsl()/hsla() strings accepted by the parser. Prefer hex or RGB for portability. Do not use arbitrary CSS, url(...), var(...), or expressions as input colors. tone is an enum, not a CSS color.

Scene settings do not expose arbitrary CSS, animation code, or event handlers. Do not insert HTML/scripts into labels. Mermaid-style link callbacks are not an execution API.

Text DSL keywords and compatibility

For complex diagrams, use the complete YAML references above. These links describe the text DSL's implemented subset:

Surface Authoring reference
Headers and supported diagram families Diagram types
Flowchart shapes, line operators, arrow labels, chained arrows, &, groups Writing diagrams
classDef, class, :::, style, linkStyle, click Writing diagrams
Sequence participants/messages and unsupported control-block behavior Diagram types
Activity, state/class, Gantt, mind map, architecture, and C4 entry points Diagram types

The FlowMotion-specific text directives are:

Directive Meaning
%% @duration <nodeId> <ms> Node process duration, 0-60000 ms
%% @fail <nodeId> Leave that node's process in an error state
%% @speed <multiplier> Playback multiplier, 0.1-10
%% @loop off Do not loop; on enables looping
%% @autoplay off Do not autoplay; on enables autoplay

Known compatibility-only constructs are not promises of behavior: sequence alt, loop, par, activation, and notes do not implement execution branching or parallel control blocks. Gantt compatibility settings listed on Diagram types are ignored. Storyboard caption and route are ignored too.

Use event branch/fork/join or simultaneous storyboard edges for real authored execution. For draw.io, use the drawing format and a display-only embed; there is no documented YAML-to-draw.io execution override.

Validation and sources of truth

This page is the human/AI authoring contract, not a replacement for validation. The matching checkout's runtime parsers decide what runs. Its schemas describe supported keys, enums, completion, and stricter editor checks; timeline and rendering code define behavior.

Evidence Source in the main repository
Generated event schema schema/diagram.schema.json
Generated storyboard schema schema/storyboard.schema.json
Schema definitions and shared display keys src/schema/diagram.ts, src/schema/story.ts, src/schema/common.ts
Runtime YAML parsing and references src/core/parse.ts, src/story/parse.ts
Embed resolution and display parsing src/core/embed.ts, src/core/view.ts
Scheduling and automatic graph animation src/core/timeline.ts, src/story/timeline.ts, src/core/auto.ts
Visibility, highlighting, rows, and packet positions src/render/frame.ts, src/render/presentation.ts
Text syntax subset src/text/parse.ts, src/text/kinds.ts
Export and interactive playback src/render/svg.ts, src/export/html.ts, src/runtime/player.ts, src/runtime/mount.ts

Source paths are relative to the repository checkout, not the vault. Consult those files from the same revision as the installed plugin. Unknown fields can be ignored by some runtime parsers, so a rendered preview is not evidence that an invented key works.

Use lintSource from src/schema/index.ts for schema and reference diagnostics. Use buildModel from src/model.ts to check layout and scheduling. A src block must be parsed with parseEmbed and its file resolved in the vault; it is not a standalone diagram for buildModel.

See the cookbook validation procedure for a runnable example. External JSON Schema alone cannot prove ID references, acyclic dependencies, valid nesting, or correct animation.

Maintenance rule

When adding or changing an author-facing keyword, update its parser, schema, generated JSON schemas, this reference, and the related cookbook or topic page together. Validate the complete examples against the same checkout. Do not document an accepted-but-ignored field as implemented behavior.

Related pages

Clone this wiki locally