The spec

A spec has a layout, edges, and optional steps. The full types have doc comments, so your editor shows each field. For the full reference, run npx flowfig docs.

Boxes

Field	Meaning	Default
id	The name that edges and steps use. It must be unique.	required
label	The title in the box.	required
sub	A smaller line under the label.	none
shape	"box", "decision" (a diamond) or "store" (a data cylinder).	"box"
source	The code this draws: path or path#symbol. flowfig verify checks it.	none
lines	The least number of text lines that a content card keeps.	none
width	The width in px. This value replaces the width that layout picks.	from layout
at	In a lanes figure: the time column of the box, from 0.	the order of first use in the steps
from	In a timeline figure: the start date of the item, as YYYY-MM-DD. A box with only from is a milestone.	none
to	In a timeline figure: the last day of the item, as YYYY-MM-DD.	none
mark	"start" draws a dot before the box. "end" draws a ring after the box. Use it on a state lifecycle.	none

Groups

layout is a group. A group holds boxes and other groups.

Field	Meaning	Default
children	The boxes and groups in the group, in order.	required
id	The name that an edge can use to reach the whole group.	none
label	The title of the frame. Only a group with a label has a frame.	none
direction	"row" puts the children side by side. "column" stacks them.	"row"
gap	The smallest space between the children in px. It grows to fit the labels of edges that cross the group.	column: 28; row: fits the widest label, at least 56
align	"start", "center" or "end", across the direction.	"center" (a column stretches)

Edges

Field	Meaning	Default
from	The id of the box or group where the edge starts.	required
to	The id of the box or group where the edge ends.	required
id	The name that beats use.	from->to
label	The text on the edge.	none
around	"above" or "below" routes the edge over or under the boxes between.	none
quiet	true draws the edge only while a step uses it.	false
source	The code this edge draws: path or path#symbol. flowfig verify checks it.	none

Steps

Each step is one story. The player shows one tab for each step. With no steps, the figure is a still map.

Field	Meaning	Default
label	The tab title.	required
flow	The beats, in play order.	required
caption	The line under the figure while no beat has a say.	none
nodes	The ids of the boxes to highlight for the whole step.	none

Beats

A beat is an edge id, an array of edge ids that run at the same time, or an object:

Field	Meaning	Default
edges	One hop or an array of hops. A hop is an edge id or { edge, back, data, async, source }.	none (a pause)
say	The line of narration for the beat.	none
show	{ boxId: content } fills the content card of a box until the step ends.	none
light	The ids of the boxes to highlight for this beat only.	none
ms	The length of the beat in ms.	speed (900)

In a hop, back: true runs the packet from to to from. data is a small card on the packet. async: true marks a message that does not wait for an answer. On the rail, an async hop has a dashed arrow and an async tag. The hops of one beat share a parallel band on the rail.

Content is an array of rows, or a React node in the player. A row is { text, tag, tone, meta, mark, mono }. Only text is required. The tones are blue (the default), purple, green, orange and gray.

Figure options

Field	Meaning	Default
rail	true draws the rail under the map. "only" draws the rail alone.	false
lanes	true draws swimlanes: a column group of labeled groups, one lane per role.	off
timeline	true draws a timeline: one labeled group per track, with the boxes at their dates.	off
today	In a timeline figure: the date of the today line, as YYYY-MM-DD.	none
speed	The time in ms for a packet to cross one edge.	900
theme	{ accent, fg, muted, bg, surface, border, font }. Each key is optional.	built-in
autoplay	Start to play when the figure mounts. Only the React player reads it.	true
check	Run the check rules in the browser. Only the React player reads it.	false