YAML schema

A Beck document is a YAML mapping that opens with a root type: declaring what kind of diagram it is. The type picks the layout engine and the top-level keys; everything else — theming, animation, fenced-block rendering — is shared. Only ids are required; every other field has a default, filled in before the diagram is laid out.

The flow block has its own page: Flow & animation. For a visual tour of these constructs, see the syntax cheatsheet.

type: architecture   # architecture | sequence | state | class
meta:    { ... }     # optional — title, direction, theme, fit, spacing
nodes:   [ ... ]     # the boxes
groups:  [ ... ]     # optional — labelled boundaries
edges:   [ ... ]     # optional — the connections
flow:    { ... }     # optional — scripted animation (see the flow reference)

meta

Shared by every diagram type; all keys are optional. (direction and spacing.rank only affect the layered types — architecture, state, class.)

spacing keys:

narrate keys (a mapping value; a bare boolean just toggles enabled):

Captions are supplied by a narrate flow step or a connector note: (see edges, messages, transitions below); meta.narrate only paces and toggles them.

nodes (type: architecture)

A list of nodes. Each needs a unique id; everything else is optional.

Node kinds

kind is a shorthand that sets three defaults at once. Each is independently overridable.

groups (architecture and class)

A list of labelled boxes drawn around member nodes (namespace boxes, in a class diagram).

Membership is a tree: every node or group belongs to at most one parent, and a group cannot nest inside itself. A node can also join a group inline with its own group key. An edge's from/to may target a group id.

edges (type: architecture)

A list of connections. from and to are required and must resolve to a declared node or group.

A feedback edge — one that runs back against the flow and would have to jump over the nodes between its endpoints — automatically loops out on a clear face (over the top for LR/RL, out the left for TB/BT) instead of jogging through the forward chain, so the forward edges stay straight. An adjacent back-and-forth pair (two nodes wired both ways, with nothing between them) is left inline as two parallel lines. Pin fromSide/toSide to force a specific loop face — e.g. both bottom to route the return under the row — or set curve: straight for a direct line.

Edge kinds

The packet-motion column describes the default animation along an edge of that kind; see Flow & animation for the exact values and how to override them.

participants and messages (type: sequence)

A sequence diagram lays participants out as columns (in declared order) and draws messages as rows, in authored order. Without a flow:, the message order is the animation — one packet per message. See the sequence diagrams guide.

participants entries take the same fields as architecture nodes (id, title, subtitle, kind, icon, accent, …); layout keys (rank, order, group) are ignored.

messages entries:

A list entry of the form - section: <label> (instead of a message) opens a tinted, dashed band around every message until the next section (or the end), and becomes a phase seek point in the derived animation. It takes an optional accent (token or CSS colour, default neutral) that colours the band's border, fill, and floating label.

Activation bars are automatic: a non-reply message starts a bar on its receiver when a later reply: true from that receiver back to the sender closes it. Nested request/reply pairs nest the bars.

states and transitions (type: state)

A state machine on the layered engine — states are pills, transitions are labelled edges. States referenced only by transitions are auto-created, so a terse machine needs nothing but transitions:. The token "[*]" (quote it — YAML) is the UML entry/exit pseudo-state: use it as a from for the initial dot, as a to for the final bullseye. See the state diagrams guide.

states entries (all optional refinements):

transitions entries:

classes and relations (type: class)

UML class cards — a «stereotype» + name header and field/method compartments — joined by relations with the classic end markers. groups (namespace boxes) work exactly as in architecture diagrams. See the class diagrams guide.

classes entries:

relations entries — note the direction conventions:

Parents rank above children automatically (inherits/implements are flipped internally so the hierarchy reads top-down). Class diagrams are structural, so they don't animate by default: without a flow: the diagram renders a still frame. Script a flow: if you want a guided tour.

steps and links (type: flowchart)

A decision/process graph on the layered engine. Steps referenced only by a link (never declared under steps:) are auto-created as plain process cards, so a terse flowchart needs nothing but links:. The token "[*]" (quote it — YAML) is the start/end pseudo-step: use it as a from for the start terminator, as a to for the end terminator. See the flowchart guide.

steps entries (all optional refinements):

links entries:

root and topics (type: mindmap)

A nested topic tree drawn as a two-sided "butterfly": a central root, first-level branches split left/right, subtrees fanning outward. meta.direction is accepted but ignored — the layout is fixed. See the mind map guide.

root — the centre topic. Either a plain string (shorthand for title) or a mapping:

topics — the first-level branches, and (via children) every deeper topic. Same fields as root, plus:

Depth roles. Shape and size follow depth: the root (210×68) and every rank-1 branch (190×56) are cards; from rank 2 outward a heading is a light pill. A topic with items/body stays a card at any depth. Icons appear only on the root and rank-1 cards.

Accent cycling and inheritance. The root resolves to primary. Each first-level branch takes the next token from the cycle info, primary, success, warn, danger (wrapping; neutral is reserved for ghost branches). Every descendant inherits its parent's resolved accent unless it authors accent: explicitly — which then flows to its own children. Edges are undirected parent → child curves with no arrowhead, in a muted blend of the child's accent and the edge colour, fanning from a single point on each parent.

Status colours. complete/done → success · in progress → warn · blocked → danger · review → info · planned → neutral · anything else → the branch accent.

A mind map renders static — no packets or narration, identical to the reduced-motion frame. A flow: is accepted for forward-compatibility but is not animated.

chart series (type: chart)

A small, static data chart — bar, line, pie/donut, or scatter. Charts carry no nodes or edges and share only the meta block. Every series colour is derived from --beck-primary by the chosen palette, so the chart adopts your palette and flips light/dark. See the chart guide.

Top-level keys:

Each series entry:

Palettes. analogous steps the hue either side of the primary (categorical, the default); monochromatic mixes the primary toward the surface (ordered magnitude); complementary alternates the primary with its opposite, lightening per pair (two-way comparison); sequential fades the primary toward neutral (one continuous scale). Each is a pure color-mix/relative-colour expression over the tokens — swap --beck-primary and every series follows.

Charts render static — no flow or animation.

Icons

Set a node's icon to one of these named keys. Many keys are aliases that share a glyph. An unknown key falls back to the node kind's default icon, so a typo never drops the glyph. See every glyph rendered live in the icon reference.

For anything outside the set, pass raw inline <svg>…</svg> markup as the icon value. Use fill="currentColor" or stroke="currentColor" and a 0 0 24 24 viewBox so the glyph inherits the node's accent and theme.

Colours and theme tokens

Anywhere a colour is accepted (accent, edge color, flow-step color), you can give either a token or a raw CSS colour. Tokens follow the theme and recolour in light and dark mode; raw colours are frozen.

Under the hood every colour is a --beck-* CSS custom property that defaults to your site's --color-* palette, with a literal fallback. That is why a diagram adopts the host page's colours and dark mode with no configuration. Override a token by defining the host ramp (preferred) or by setting the --beck-* variable on an ancestor — see Match your theme and colours.

Light and dark are handled purely by redefining the surface, text, and edge variables under [data-theme="dark"]; the accent tokens ride your host ramps in both modes. There is no per-theme JavaScript and no hardcoded hex in the renderer.