/diagram-builder

name: diagram-builder
description: Use when the user wants to build or extend a diagram deck of nested sections and components authored in plain YAML — an architecture map, a timeline diagram, a planner board, a process-flow diagram, a slide-style presentation, a side-by-side comparison, or a mind-map. Not for charts, plots, or numeric/data visualization — route those to the dataviz skill. Triggers — "build a diagram", "architecture diagram", "diagram deck", "timeline diagram", "flow diagram", "planner board", "comparison diagram", "add a page/section/component to the diagram".

Diagram Builder

Diagram-builder draws a diagram of any kind — a system architecture, a timeline, a slide-style presentation, a process flow, a comparison, a mind-map, a planner board — as nested boxes authored in plain YAML and rendered by a generic engine: no framework, no server, opens under `file://`. Its whole material is two primitives — a recursive **section** that ARRANGES and a **component** that CARRIES — and its work is to find the form that teaches THIS idea best and lower it into that geometry. Everything domain-specific lives in the data; nothing about a domain lives in the engine. Everything on the canvas invites the reader toward the centre: the layout centres its content, a click opens a bottom-centre panel, a chip spotlights a relation.

idea
 └─ document        the deck: title, subtitle, version, palette, pages
     └─ page        one act/view (also the ROOT section: its columns + sections)
         └─ section     a grid zone; nests other sections freely (a grid of grids)
             └─ component   a leaf: a card, a divider, a lane label, a declared hole
   filters (page-level only) light a relation across components

The governing definition (the anchor)

Internalize this before anything else. Every design decision is judged against it, and the adversarial critique at the end of the cycle is run against it:

> A diagram is a **semantic design tool: nested boxes, one inside another**. > Some boxes are **sections** — they group other sections or groups of > components. Sections divide into **columns**, vertically and horizontally. > **Components expand horizontally and vertically** — a merge on **two axes**: > a span of columns plus a row-span of rows — and they sit in columns, or in > cells flowing downward. The objective is **compaction and symmetry**: the > canvas **fills** inside a **centered width cap** (max-width ≈ 1280px — a > medium resolution, no horizontal scroll). It neither expands to arbitrary > width nor leaves holes — **full rectangles**.

The engine implements this model: both merge axes are real, the canvas fills to the centered cap, cells keep a readable minimum width (columns collapse before a cell degrades), a guardrail asserts form-scoped invariants against the real rendered geometry, and a strict schema rejects any unknown field loudly at build time. So design, discuss, and critique against the definition knowing the engine renders it — the exact geometry and the field-by-field schema live in `reference.md`, the dialect's terms and value sets in `GLOSSARY.md`.

The nine principles

Nine principles, not a menu of features. Every capability of the engine is a consequence of one of them, so hold the principles and the possibilities open by themselves.

How the canvas works

**1 · Everything you see is a merged cell.** There is no other geometry: one uniform cell, and two axes to merge it on. Width is REACH; height is MAGNITUDE. A merge consumes rows or columns that must already exist — something has to sit beside it creating them. Ask: what do I want bigger, in which direction, and what holds it up?

**2 · A grid holds cells or zones, and mixing them changes what every dial means.** One nested section among components turns the whole level into a row of zones: `columns` stops creating tracks, `span` becomes a relative weight, `rowspan` ceases to exist, and the cell invariants stop measuring that level. You will mix sometimes — a timeline of sections divided by separators is a good reason. Mix knowing what you give up.

**3 · You author a sequence, not positions.** There is no cell coordinate, only `order`. That same order is the packing order and the stacking order when everything collapses to one column. And filling runs forward: nothing goes back to fill the hole a tall cell left. Whatever belongs beside something tall goes before it.

How you speak through it

**4 · Every field is a slot with a character, not a meaning.** The field decides SIZE and PROMINENCE; you decide the meaning. The kicker is small — a qualifier, a code, a step. The title is the loud one, and that is where a number goes when the number is the message. The description is brief and clamps. The detail is unbounded, behind a click. Read a slot's character wrong and the layout fights you: a lane label pressed into service as a section heading grows, steals space, and distorts the grid — a section that needs a heading has one.

**5 · Every visual channel carries one claim.** Position, size, colour, border style, kicker — independent of each other. Double them to reinforce (a bar that grows and turns red says magnitude twice) or split them to say two things. A channel's meaning is PER PAGE and declaring it is obligatory — but no schema field holds it: you declare it in the CONTENT, as a legend band, a section heading, or a box that spells the code out. An undeclared channel is decoration.

**6 · The grid does not draw relations: it lights them.** There are no arrows. Every relation is shared membership in a chip — a directed path, which `order` makes readable, or a concept that cuts across sections. A relation needs two ends; a chip with a single member dims the page and lights nothing. The same key on two pages projects one onto the other.

What judges it

**7 · Structure is the assertion.** Distinct things are distinct sections; parts of one thing are components inside i