Introduction

Lini draws figures from plain text. Diagrams, mindmaps, charts, sequences, ER schemas, engineering drawings, floor plans and circuit schematics are all layouts of one small language, and every one of them compiles to clean, themeable SVG. From mindmap to blueprint, in the same file format.

{
  gap: 70; clearance: 20;
  .step { direction: column; gap: 6; padding: 6; }
  |icon| { width: 46; height: 46; }
  #coffee |icon| { fill: --amber-soft; stroke: --amber-ink; }
  #code   |icon| { fill: --sky-soft;   stroke: --sky-ink; }
  #bug    |icon| { fill: --rose-soft;  stroke: --rose-ink; }
  #ship   |icon| { fill: --lime-soft;  stroke: --lime-ink; }
  |-| { stroke: --gray-deep; font-size: 12; }
}
|block#coffee| .step [ |icon| "coffee"; "Coffee" ]
|block#code|   .step [ |icon| "code"; "Code" ]
|block#bug|    .step [ |icon| "bug"; "Bug" ]
|block#ship|   .step [ |icon| "rocket-launch"; "Ship" ]
coffee -> code -> bug
bug ~> coffee
code -> ship "tests pass"

That fence is the figure’s whole source: four steps, four wires, and a wavy one back to the kettle. You say what there is and what connects to what. Lini sizes the boxes, routes the wires around whatever is in the way, slides the label to where it fits, and paints from a palette that already knows about dark mode. Every one of those choices has a property that overrides it, resolved through a CSS-like cascade, so a figure starts pretty and stays yours.

The same six forms — a capsule for identity, a string for the label, braces for style, brackets for content, a class, a link — carry every layout:

Install

cargo install lini

lini figure.lini -o figure.svg     # compile to SVG
lini serve figure.lini             # live-reloading preview
lini fmt figure.lini               # canonical formatting (--check for CI)

Or skip the install: the playground runs the same compiler in your browser, and every fence in this book pastes straight into it.

Where to go

• The Tour starts with the language — six forms, one page — then walks each family in a few minutes apiece, and ends with style, colour & themes and the tooling.
• The Reference is the full language specification, one section per chapter, split straight from the repository’s SPEC.md.
• The gallery shows every sample the language ships, source beside figure.

The language

Six forms, and that is the whole syntax. Every page after this one adds a layout — a new way to arrange children. None of them adds a rule.

One line draws

draft -> review -> publish

Nothing was declared there. A link to a name nobody declared creates a box for it, labelled with the name.

A chain marks every hop, so that line is exactly draft -> review and review -> publish.

Declare a node when you have more to say about it

|oval#visitor| "Visitor"
|box#api| "API"
|cyl#db| "Postgres"

visitor -> api -> db

The bars carry the identity — a type, and an id after #. The quoted string is the label.

Only the bars are required, and both halves inside them are optional:

• |box#api| is a box named api with no label — a blank card, not a card reading “api”.
• |#api| is that same box. A node with no type is a |box|.
• |oval| is an oval nothing can link to, because an id is the one thing you reference.

Style is a block on the node

|box#edge| "Edge"
|box#core| "Core" { fill: --rose-wash; stroke: --rose-deep; radius: 14; }

edge -> core

A { } after the label is that node’s style: key: value; declarations, and the vocabulary is the same everywhere in the language.

Children go in brackets

{ gap: 76; }

|box#web| "Web" { fill: --rose-wash; stroke: --rose-deep; color: --rose-ink; }
|box#api| "API" { fill: --purple-wash; stroke: --purple-deep; color: --purple-ink; }
|group#store| "Store" { direction: column; gap: 26; padding: 22; } [
  |box#cache| "Cache" { fill: --purple-wash; stroke: --purple-deep; color: --purple-ink; }
  |cyl#db| "Postgres" { fill: --purple-wash; stroke: --purple-deep; color: --purple-ink; }
]

web -> api
api -> store.cache
api --> store.db

A [ ] holds content — children, in the order written.

A named container gives its children a path, which is how store.cache and store.db reach them from outside. There is no search: cache alone at the root would make a new box rather than find that one.

Four nodes here carry the same three declarations. That is the itch the next section scratches.

The stylesheet on top

Everything so far styled one node at a time. A { } block standing before any drawn statement is the stylesheet: it draws nothing, and it says what whole kinds of thing look like.

{
  gap: 80;
  |box| { radius: 4; }
  |-| { stroke: --gray-deep; font-size: 12; }
  .hot { fill: --rose-wash; stroke: --rose-deep; }
  |svc::box| { fill: --purple-wash; stroke: --purple-deep; }
}

|svc#web| "Web"
|svc#api| "API" .hot

web -> api "HTTPS"

Four kinds of entry, each reaching a different way:

• |box| { } is a rule — every node of that type. |-| is the link type, so that line styles every link on the page.
• .hot { } is a class, worn after the label: |svc#api| "API" .hot.
• |svc::box| { } is a define — a new type carrying its own defaults over a base one.
• gap: 80 is a bare declaration, and belongs to the root. The file is the body of an implicit root container, so its children are your top-level nodes.

An #id { } rule reaches exactly one node. When several of these touch the same property, the more specific one wins; the style page walks the ladder.

The six forms

Everything above is built from these, and there are no others:

A drawn node is |type#id| "label" .class { style } [ children ], and a link is the same tail on a different head: a -> b "label" .class { style }. A name goes bare only when it is being referenced, and the one thing you reference is an id — which is why types and classes always carry their sigil.

Where each family starts

A layout: on any container — the root, or any node — picks the family:

The nodes, links, cascade and colours are identical in every one. A layout only decides where its children go, and what its links mean.

Diagrams

Boxes, and the wires between them. This is the default family — nothing to declare — and the one every other page borrows its nodes and links from.

A row, or a column

{ direction: column; gap: 35; }

|oval#visitor| "Visitor"
|box#api| "API"
|hex#worker| "Worker"
|cyl#db| "Postgres"

visitor -> api -> worker -> db

Every container is a flow until told otherwise. direction: row reads left to right, column top to bottom, and gap: is the space between children.

That one word is the whole of it. Change column to row and the same four nodes read across the page instead of down it.

The shapes

{
  layout: grid; columns: repeat(5); gap: 26; padding: 24;
  |tile::column| { gap: 9; align: center; }
  |cap::block| { font-size: 12; color: --muted; }
}

|tile| [ |block| "block" { padding: 12 16; fill: --rose-wash; stroke: --rose-deep; }; |cap| "block" ]
|tile| [ |box| { width: 62; height: 42; fill: --rose-wash; stroke: --rose-deep; }; |cap| "box" ]
|tile| [ |rect| { width: 62; height: 42; fill: --orange-wash; stroke: --orange-deep; }; |cap| "rect" ]
|tile| [ |oval| { width: 64; height: 46; fill: --amber-wash; stroke: --amber-deep; }; |cap| "oval" ]
|tile| [ |hex| { width: 64; height: 46; fill: --lime-wash; stroke: --lime-deep; }; |cap| "hex" ]
|tile| [ |slant| { width: 64; height: 42; fill: --green-wash; stroke: --green-deep; }; |cap| "slant" ]
|tile| [ |cyl| { width: 56; height: 46; fill: --teal-wash; stroke: --teal-deep; }; |cap| "cyl" ]
|tile| [ |diamond| { width: 62; height: 46; fill: --sky-wash; stroke: --sky-deep; }; |cap| "diamond" ]
|tile| [ |poly| { points: 0 -26, 26 -6, 15 24, -15 24, -26 -6; fill: --blue-wash; stroke: --blue-deep; }; |cap| "poly" ]
|tile| [ |line| { points: -30 0, 30 0; marker-end: arrow; stroke: --purple-deep; stroke-width: 3; }; |cap| "line" ]
|tile| [ |path| { path: "M -30 24 Q 0 -26 30 24"; stroke: --purple-deep; stroke-width: 4; fill: none; }; |cap| "path" ]
|tile| [ |icon| { symbol: house; width: 34; height: 34; stroke: --red-deep; fill: none; }; |cap| "icon" ]
|tile| [ |sketch| { draw: move(0, 0) right(56):a down(34) left(56) close(); fill: --rose-wash; stroke: --rose-deep; }; |cap| "sketch" ]
|tile| [ |box| "badge" { width: 62; height: 42; fill: --gray-wash; stroke: --gray-deep; font-size: 11; } [ |badge| "3" ]; |cap| "+ badge" ]

Those are the primitives. Every template — |group|, |table|, |badge|, |mindmap|, and the rest — is a bundle of defaults over one of them, so anything you can do to a |box| you can do to a |group|.

A group frames its children

{
  gap: 60;
  |group| { direction: column; gap: 16; }
  .client { fill: --rose-wash; stroke: --rose-deep; color: --rose-ink; }
  .backend { fill: --purple-wash; stroke: --purple-deep; color: --purple-ink; }
}

|group#browser| "Browser" [
  |box#ui| "UI" .client
  |box#cache| "Cache" .client
]
|group#server| "Server" [
  |box#api| "API" .backend
  |cyl#db| "Postgres" .backend
]

browser.ui -> server.api "fetch"
server.api -> server.db
server.api --> browser.cache "store"

A |group| draws a frame around a region and lifts its label to a caption above the corner.

Links written inside a group’s own [ ] name that group’s children bare; written at the root, as these are, they need the path.

A grid, with cells and spans

{ layout: grid; columns: 120, 120, 120; gap: 16; align: stretch; justify: stretch; }

|box#head| "Header" { span: 3; fill: --sky-wash; stroke: --sky-deep; }
|box#nav| "Nav" { fill: --amber-wash; stroke: --amber-deep; }
|box#main| "Main" { span: 2 2; fill: --teal-wash; stroke: --teal-deep; }
|box#side| "Side" { fill: --amber-wash; stroke: --amber-deep; }
|box#foot| "Footer" { cell: 1 4; span: 3; fill: --sky-wash; stroke: --sky-deep; }

layout: grid needs columns: — fixed sizes, auto, or repeat(N) — and fills left to right, wrapping at the count.

• span: cols rows covers several tracks.
• cell: col row places one child exactly; the rest flow around it.
• Tracks are floors, not ceilings: a track grows to its widest child, so a grid never clips.

align and justify set to stretch are what fill each cell with its child — without them the spans would be invisible.

Out of the flow: pin and translate

{ gap: 40; }

|box#card| "Card" { width: 160; height: 90; fill: --purple-wash; stroke: --purple-deep; } [
  |badge| "3"
  |block| "draft" { pin: bottom left; translate: 8 -6; color: --muted; font-size: 11; }
]
|box#plain| "Plain" { width: 100; height: 90; translate: 0 20; }

pin: lifts a child out of the flow and seats it on a point of its parent — a center, an edge, or a corner — as an overlay that never grows the parent. A |badge| is exactly that: a pinned block with the offset already set.

translate: x y nudges any node after it has been placed, without moving its siblings. So pin: center plus a translate: is an exact coordinate with no arithmetic.

Alignment and stretch

{
  gap: 24;
  |box| { fill: --teal-wash; stroke: --teal-deep; color: --teal-ink; }
}

|group#start| "align: start" { direction: column; align: start; width: 140; } [
  |box| "short"
  |box| "a longer one"
]
|group#stretch| "align: stretch" { direction: column; align: stretch; width: 140; } [
  |box| "short"
  |box| "a longer one"
]
|group#end| "justify: end" { direction: column; justify: end; height: 160; } [
  |box| "low"
]

justify runs along a flow’s axis; align runs across it. Both default to center.

stretch fills a child to the cross axis, and evenly spreads the main-axis slack. Neither does anything until the container is bigger than its packed children — an explicit width: or height:, or a grid’s fixed tracks, is what makes the slack to spread.

Go deeper

The layout model and flow, grid, stack & tree have the full rules; the box model covers sizing, padding and wrapping.

Links

You place the nodes; Lini routes the wires. A link is two ids and an operator, and the operator is the whole look.

The operator is the look

{
  direction: column; gap: 14;
  |row| { gap: 150; }
  |box| { width: 60; padding: 6; font-size: 13; }
  |-| { font-size: 12; }
}

|row| [ |box#a1| "a"; |box#b1| "b"; a1 -> b1 "->" ]
|row| [ |box#a2| "a"; |box#b2| "b"; a2 <-> b2 "<->" ]
|row| [ |box#a3| "a"; |box#b3| "b"; a3 --> b3 "-->" ]
|row| [ |box#a4| "a"; |box#b4| "b"; a4 ---> b4 "--->" ]
|row| [ |box#a5| "a"; |box#b5| "b"; a5 ~> b5 "~>" ]
|row| [ |box#a6| "a"; |box#b6| "b"; a6 *-* b6 "*-*" ]
|row| [ |box#a7| "a"; |box#b7| "b"; a7 -<> b7 "-<>" ]
|row| [ |box#a8| "a"; |box#b8| "b"; a8 - b8 "-" ]

An operator is [start marker][line][end marker], glued together with no spaces. That is the whole grammar:

So --> is a dashed arrow, and *-* a solid line with a dot at each end. A bare line op leaves both ends plain.

The ER cardinality markers ride the same scheme — Tables & entities shows them.

Labels ride the route

{
  gap: 120;
  |box| { fill: --purple-wash; stroke: --purple-deep; color: --purple-ink; }
}

|box#client| "Client"
|box#server| "Server"
|box#store| "Store"

client -> server "request"
server -> store { along: 0.25, 0.75; } [ "read" "write" ]
store --> client [ "rows" { color: --teal-ink; font-weight: bold; } ]

One label follows the head, and slides along the route to keep clear of nodes.

Several labels, or a styled one, ride the link’s own [ ] — and along: fixes each as a fraction of the route, so 0.25, 0.75 puts them at the quarter and three-quarter marks.

A label cuts its wire where it sits, so it reads over any background.

Chains and fans

{
  gap: 60;
  |box| { fill: --sky-wash; stroke: --sky-deep; color: --sky-ink; }
  |cyl| { fill: --teal-wash; stroke: --teal-deep; color: --teal-ink; }
}

|box#lb| "LB" { fill: --rose-wash; stroke: --rose-deep; color: --rose-ink; }
|column#apps| { gap: 20; } [
  |box#a| "app-1"
  |box#b| "app-2"
  |box#c| "app-3"
]
|cyl#db| "DB"

lb -> apps.a & apps.b & apps.c
apps.a & apps.b & apps.c -> db

a -> b -> c is a chain: two links, every hop marked.

& groups endpoints, and which side you group decides the shape:

• lb -> a & b & c fans out.
• a & b & c -> db fans in.
• Both sides grouped is a cartesian product — every left to every right.

A fan shares its trunk wherever the geometry allows, which is what makes the two bundles above read as buses rather than as six separate wires.

Steering: sides, clearance and dotted paths

{ gap: 70; clearance: 20; }

|box#a| "a"
|box#b| "b"
|box#c| "c"

a -> b -> c
a:top -> c:top "skip"
c:bottom -> a:bottom "retry"

Without a side the router picks the edges by geometry. a:top forces one.

clearance is the gap a wire keeps from every node and every other wire. Set it on a container and it cascades to the links written inside.

It shapes the drawing as well as spacing it: corners round to fit the clearance, and a parallel run steps aside so two wires never share a track.

Three routing strategies

{
  gap: 40;
  |group| { layout: grid; columns: repeat(2); gap: 44 60; padding: 24; }
  |box| { fill: --amber-wash; stroke: --amber-deep; color: --amber-ink; }
}

|group#o| "orthogonal" [
  |box#o1| "a"; |box#o2| "b"
  |box#o3| "c"; |box#o4| "d"
  o1 -> o4
  o2 -> o3
]
|group#n| "natural" { routing: natural; } [
  |box#n1| "a"; |box#n2| "b"
  |box#n3| "c"; |box#n4| "d"
  n1 -> n4
  n2 -> n3
]
|group#s| "straight" { routing: straight; } [
  |box#s1| "a"; |box#s2| "b"
  |box#s3| "c"; |box#s4| "d"
  s1 -> s4
  s2 -> s3
]

routing: is scene config, like clearance:

• orthogonal (the default) — horizontal and vertical legs through the free space between nodes.
• natural — smooth curves that bend around what they would hit, and are free to cross.
• straight — one segment between the bodies, avoiding nothing.

A group can route its internals one way while the root routes another, which is what the figure above is doing.

Styling a link

{
  gap: 70;
  |-| { stroke: --gray-deep; stroke-width: 1.5; font-size: 12; }
  .hot { stroke: --red-deep; stroke-width: 2.5; color: --red-ink; }
}

|box#a| "a"
|box#b| "b"
|box#c| "c"

a -> b "cold"
b -> c "hot" .hot

A link is styled exactly like a node. stroke, stroke-width and stroke-style dress the wire; color and the font-* family dress its labels.

The cascade is the same one too: |-| { } is the rule for every link, a class applies to whichever nodes or links wear it, and a link’s own { } wins.

There is no separate link-* vocabulary to learn.

Go deeper

Links in the reference covers endpoints, scope and capsule endpoints; the full routing contract — priority, crossings, self-loops — is ROUTING.md.

Trees & mindmaps

layout: tree reads |topic| nesting as the hierarchy and draws the branch wires for you. A mindmap is that same tree wearing a preset.

Nesting is the whole structure

{
  layout: tree;
  |topic| { fill: --purple-wash; stroke: --purple-deep; color: --purple-ink; }
}

|topic#ceo| "Chief Executive" [
  |topic#eng| "Engineering" [
    |topic| "Platform"
    |topic| "Product"
  ]
  |topic#ops| "Operations" [
    |topic| "Support"
    |topic| "Finance"
  ]
]

There are no links in that source. Every wire was generated — one fan per parent — and lini desugar will show you them.

A tree scope holds exactly one root topic. Inside a topic’s [ ]:

• a |topic| is a branch;
• anything else is that topic’s own content, which is how an icon or a caption rides along. The last figure on this page uses it.

Which way it grows

{
  layout: tree; direction: row; gap: 48 20;
  |topic| { fill: --rose-wash; stroke: --rose-deep; color: --rose-ink; }
  |-| { stroke: --rose-deep; }
}

|topic#req| "Request" [
  |topic#triage| "Triage" [
    |topic| "Approve"
    |topic| "Reject"
    |topic| "Escalate"
  ]
  |topic#auto| "Auto-close" [
    |topic| "Duplicate"
  ]
]

Three directions, and each one is a different document:

• column (the default) grows down — an org chart.
• row grows right — an outline, like this one.
• bilateral grows both ways from a centred root — a mindmap.

gap: reads two numbers here: the distance between generations first, then the separation between siblings.

The mindmap preset

|mindmap#launch| "Launch" [
  |topic#product| "Product" [
    |topic| "MVP scope"
    |topic| "Docs and a playground"
  ]
  |topic#market| "Marketing" [
    |topic| "Site"
    |topic| "Launch post"
  ]
  |topic#sales| "Sales" { side: left; } [
    |topic| "Leads"
    |topic| "Pricing page"
  ]
  |topic#team| "Team" [
    |topic| "Hiring plan"
  ]
]

|mindmap| is the visible root topic with a whole scene preset folded in — none of the colour above is written:

• direction: bilateral, and routing: natural for the smooth arms.
• A palette walk: each first-level branch takes the next hue and tints its whole subtree — wash fill, deep stroke and wire, ink text.
• A depth ramp that sizes the type down by level.
• A max-width, so a long topic wraps into a card instead of running away.

Bilateral fills the right side first. side: left on a first-level topic overrides the split, which is what moved Sales across.

Flaring one arm

{
  .lini-level-1 { font-weight: bold; }
  .lini-level-2 { font-size: 12; color: --muted; }
  #build |-| { stroke-style: dashed; }
  .now {
    fill: --rose-wash; stroke: --rose-deep; color: --rose-ink;
    stroke-width: 2.5; font-size: 15; padding: 10 16;
  }
  |when::block| { font-size: 11; color: --muted; }
}

|mindmap#plan| "Plan" [
  |topic#build| "Build" [
    |icon| { symbol: gear; width: 18; height: 18; stroke: --purple-deep; fill: none; }
    |topic#compiler| "Compiler"
    |topic| "Formatter"
  ]
  |topic#ship| "Ship" .now [
    |icon| { symbol: rocket; width: 20; height: 20; stroke: --rose-deep; fill: none; }
    |topic| "Binary"
    |topic| "Crate"
    |when| "this quarter"
  ]
  |topic#docs| "Docs" { side: left; } [
    |topic| "The tour"
    |topic| "Reference"
  ]
  |topic#test| "Test" { side: left; } [
    |topic#conformance| "Conformance"
    |topic| "Snapshots"
  ]
]

plan.docs ~> plan.test

Everything on that figure is reachable from the stylesheet:

• A tier at a time. Every topic wears a generated .lini-level-N class, root at 0 — so one rule restyles a whole generation.
• One arm at a time. A branch link cascades as if it were written inside its parent, so #build |-| { } dashes exactly the wires under Build and nothing else.
• One topic. A class does what it does anywhere else: .now flares Ship out of the palette walk.
• Content rides along. The two |icon| children and the |when| block are ordinary content in a topic’s [ ], not branches, so they decorate without joining the hierarchy.

Authored cross-links between topics stay legal and never alter the tree — plan.docs ~> plan.test is the wavy one, drawn over the generated ones.

Go deeper

Flow, grid, stack & tree has the placement rules; the |topic| and |mindmap| bundles are in templates.

Tables & entities

A |table| is a grid with ruled gutters; an |entity| is that table shaped like a database card. Neither adds grammar — cells are bare strings, and relationships are ordinary links.

Cells are strings, in row order

|table#plans| "Plans" { columns: 120, 80, 90; } [
  "Plan"  "Seats" "Price"
  "Free"  "1"     "$0"
  "Team"  "10"    "$120"
  "Scale" "50"    "$480"
]

columns: fixes the track widths and the count, so the rows need no separators — the count is what breaks them. The first row becomes the header band, and the table’s label is its caption.

lini fmt knows that count too, and pads the cells into aligned columns, so the source keeps the shape of the thing it draws.

Alignment, a footer, and one cell that speaks up

{
  |table| { fill: --purple-wash; stroke: --purple-deep; }
  .bad { color: --red-ink; font-weight: bold; }
}

|table#regions| "Edge regions" { columns: 110, 90, 80, 90; align: start, end, end, center; } [
  "Region"   "Requests" "p95"    "Status"
  "us-east"  "18.2M"    "84 ms"  "Healthy"
  "eu-west"  "11.4M"    "96 ms"  "Healthy"
  "ap-south" "6.8M"     "142 ms" "Degraded" .bad
  |footer| "Total"; |footer| "36.4M"; |footer| "—"; |footer| "3 regions"
]

align: takes one value per column — start, end or center — and moves the header with the body, so a numeric column lines up on its digits.

A cell is a node like any other, which is the whole trick here:

• Give one a class or a { } and it styles itself, as Degraded does.
• Wrap a last-row cell in |footer| and it joins the muted footer band.
• Reach them all with |cell| { }, or just one table’s with |table#regions| |cell| { }.

Entities and the crow’s foot

{
  gap: 120;
  |entity| { fill: --rose-wash; stroke: --rose-deep; }
}

|entity#users| "Users" { columns: auto, auto, auto; } [
  "PK" "id"    "int"
  ""   "email" "varchar"
  ""   "name"  "varchar"
]
|entity#orders| "Orders" { columns: auto, auto, auto; } [
  "PK" "id"      "int"
  "FK" "user_id" "int"
  ""   "total"   "decimal"
]

users +-< orders "places"

An |entity| is a table whose label is a title spanning every column, over left-aligned rows. Two auto columns is the default; a third gives you the PK / FK gutter.

The relationship is a plain link wearing a crow’s-foot operator:

Each marker composes [min][max]: the ring o or the bar + hugs the line, and the crow < sits against the entity. Either end takes one, so users +-< orders reads one-to-many.

They are sugar over marker: crow, one, zero-or-many and the rest — so marker-end: still overrides a single end when you need it to.

A schema, wired field to field

{
  layout: grid; columns: repeat(3); gap: 60 90; clearance: 16;
  |entity| { fill: --sky-wash; stroke: --sky-deep; }
  #post { fill: --purple-wash; stroke: --purple-deep; }
  #post_tag { fill: --amber-wash; stroke: --amber-deep; }
}

|entity#author| "Author" { cell: 1 1; } [ "id" "int"  "name" "varchar" ]
|entity#post| "Post" { cell: 2 1; } [
  |cell#pid| "id"; "int"
  "author_id" "int"
  "title" "varchar"
]
|entity#post_tag| "PostTag" { cell: 3 1; } [
  |cell#pref| "post_id"; "int"
  "tag_id" "int"
]
|entity#tag| "Tag" { cell: 3 2; } [ "id" "int"  "name" "varchar" ]

author -< post "writes"
post.pid -< post_tag.pref
tag -< post_tag

Entities lay out like any other node — a grid here, but a flow, or pin and translate, work the same.

A relationship lands on the card’s edge by default. To wire a specific field, give that cell an id and link the path — |cell#pid| "id" makes the cell addressable, so post.pid -< post_tag.pref leaves and arrives at those two rows rather than at the two cards.

The join table needs no special treatment either: it is an entity like the others, and the two links into it are what make the many-to-many.

Go deeper

The |table|, |cell|, |header|, |footer| and |entity| bundles are in templates; the operators in links.

Text, icons & images

Text is content, not a shape — a bare string is a text node wherever it stands. Icons are Phosphor glyphs drawn as paths. Images embed.

A string is a node

{ direction: column; gap: 14; align: start; }

"Plain text stands on its own."
"Styled in place." { color: --rose-ink; font-weight: bold; }
"Two lines,\nwith a break." { font-style: italic; }
|box#card| { fill: --purple-wash; stroke: --purple-deep; } [
  "A heading" { font-weight: semibold; font-size: 17; color: --purple-ink; }
  "and a line of body text under it." { color: --purple-ink; }
]

Where the string stands is what it becomes:

• On its own — a free text node.
• Inside a shape’s [ ] — that shape’s text. Several strings are several nodes, stacked, because a shape’s content flows as a column.

Either way it takes a style block of text properties — color, the font-* family, letter-spacing, text-decoration, translate, rotate — and wears classes like anything else.

Anything that needs a border, padding or an id wraps in a |block|: the frameless box.

Wrapping

{
  gap: 20; align: start;
  |box| { max-width: 170; fill: --teal-wash; stroke: --teal-deep; color: --teal-ink; }
}

|box#a| "Ship the release notes to every customer who asked"
|box#b| "Rotate the signing keys before the audit window opens" { align: start; }
|box#c| "Archive dashboards nobody opened this quarter" { align: end; }

max-width caps a box’s automatic width, and the text wraps to honour it, breaking at whitespace first. The wrapped size is the measured size, so those three cards sit at their true heights rather than at a guess.

There is no text-align. Lines align by the box’s own packing knob — align in a column box, justify in a row — which is why b and c above differ without either one naming text.

Icons

{
  gap: 26;
  .tag { fill: --sky-wash; stroke: --sky-ink; color: --sky-ink; }
}

|icon| "bell"
|icon| "heart" { fill: --rose-wash; stroke: --rose-ink; }
|icon| "cloud" { fill: none; stroke: --sky-deep; }
|icon| "chat-circle" .tag [ "3" ]
|sign#docs| "folder-simple" .tag [ "Docs" ]

|icon| draws a Phosphor icon named by its label — or by symbol: — as inline paths. No icon font, and only the glyphs a figure actually uses are embedded.

It paints like a box:

• fill is the soft body, stroke the line.
• fill: none makes it a single-tone line icon, as cloud is above.
• It is a square that grows with its [ ] text.

|sign| is the larger preset with room for a word, and it takes links like any other node.

Icons make cards

{
  layout: grid; columns: repeat(3); gap: 20;
  |card::box| { padding: 16 20; }
  |stat::block| { font-size: 22; font-weight: bold; }
  |cap::block| { font-size: 12; color: --muted; letter-spacing: 1; }
}

|card| { fill: --rose-wash; stroke: --rose-deep; } [
  |icon| "bell" { fill: --rose-wash; stroke: --rose-ink; }
  |stat| "128" { color: --rose-ink; }
  |cap| "ALERTS"
]
|card| { fill: --purple-wash; stroke: --purple-deep; } [
  |badge| "!"
  |icon| "lock" { fill: --purple-wash; stroke: --purple-ink; }
  |stat| "24" { color: --purple-ink; }
  |cap| "KEYS"
]
|card| { fill: --lime-wash; stroke: --lime-deep; } [
  |icon| "users" { fill: --lime-wash; stroke: --lime-ink; }
  |stat| "1.4k" { color: --lime-ink; }
  |cap| "TEAM"
]

Nothing here says direction. A shape’s children stack as a column, so an icon over a number over a caption is just three children in order.

The rest is the language you already have — a define per role, a class-free { } where one card differs, and a |badge| pinned to the middle card, which is the same overlay the diagrams page pinned to a card.

That icon is one node type everywhere: the same |icon| is a sequence participant’s glyph, or a tree topic’s decoration.

Images

|image#logo| { src: "assets/logo.svg"; width: 120; height: 60; }
|image#photo| { src: "https://example.com/site.png"; width: 320; height: 180; fit: cover; }

|image| needs src, width and height. What happens next depends on where the source lives:

• A local path is read once and embedded, so the output stays self-contained — an SVG asset as a nested, id-isolated <svg>, a raster as a base64 data URI.
• A URL passes through untouched.

fit: maps the picture into its box: auto letterboxes, and contain, cover and stretch do what CSS says.

Go deeper

Statements & the label covers text content, paint, stroke & text the text family, and nodes icons and images.

Sequences

layout: sequence reads a diagram on a time axis: participants across the top, messages down the page in the order you wrote them.

Two lines are a diagram

{ layout: sequence; }

user   -> server "login"
server --> user "token"

The links are the messages, and source order is time: the first line written is the first row drawn.

Nothing was declared here either. An endpoint nobody declared creates a participant, appended in first-use order, so a quick exchange needs no header block at all. -> is a call, --> a return.

Participants you declare

{ layout: sequence; }

|box#user| "Customer" [ |icon| "user" { fill: none; stroke: --rose-deep; } ]
|box#shop| "Storefront" { fill: --sky-wash; stroke: --sky-deep; }
|cyl#db| "Orders" { fill: --orange-wash; stroke: --orange-deep; }

user -> shop "place order"
shop -> db "reserve stock"
db --> shop "reserved"
shop --> user "order #1024"

Declaring the participants buys three things at once: their left-to-right order, their type, and their paint.

That paint carries down the page. A participant lends its own fill and stroke to its apparatus — the lifeline and every activation bar — so colouring a header colours its whole timeline.

An actor is just a box wrapping an |icon|: the name stays the header, and the glyph becomes the picture.

What the operators mean

{
  layout: sequence;
  |box| { fill: --purple-wash; stroke: --purple-deep; color: --purple-ink; }
}

|box#shop| "Storefront"
|box#pay| "Payments"

shop -> pay "charge $42"
pay -> pay "verify card"
pay --> shop "receipt"
shop ~> pay "queue settlement"

Three operators, three different things on the page:

• -> a call. It opens an activation bar on its target; the next return from that target closes it, and nested calls stack outward.
• a -> a a self-message. Internal work, hooked back onto the same lifeline. It opens no bar.
• ~> async. Drawn wavy, and expecting no reply.

Repeating a span

{
  layout: sequence;
  |box| { fill: --rose-wash; stroke: --rose-deep; color: --rose-ink; }
  |cyl| { fill: --teal-wash; stroke: --teal-deep; color: --teal-ink; }
  |loop| { fill: --amber-wash; stroke: --amber-deep; }
}

|box#shop| "Storefront"
|box#pay| "Payments"
|cyl#db| "Orders"

shop -> pay "charge $42"
pay --> shop "receipt"

|loop| "each item" [
  shop -> db "reserve stock"
  db --> shop "in stock"
]
|note| "one round trip per line item" { place: over shop db; }

A |loop| frame wraps the rows that repeat, draws them once, and uses its label as the guard.

Its [ ] groups messages for layout but opens no scope — the wires inside still name the sequence’s own participants, which is why shop and db need no path.

A |note| is a callout bound to lifelines by place::

• over shop — on one lifeline.
• over shop db — spanning from one to another.
• left shop / right shop — beside one.

Branching

{
  layout: sequence;
  |box| { fill: --purple-wash; stroke: --purple-deep; color: --purple-ink; }
  #pay { fill: --rose-wash; stroke: --rose-deep; color: --rose-ink; }
  |alt| { fill: --purple-wash; stroke: --purple-deep; }
}

|box#user| "Customer"
|box#shop| "Storefront"
|box#pay| "Payments"

user -> shop "submit card"
shop -> pay "authorize"
|alt| "accepted" [
  pay --> shop "approved"
  shop --> user "receipt"
  |else| "declined"
  pay --> shop "refused"
  shop --> user "ask for another card"
]

An |alt| holds two or more compartments split by |else|. Each label is that branch’s guard, and the |alt|’s own label guards the first compartment.

|opt| is the same frame with a single branch, for a step that only sometimes happens.

Go deeper

The full sequence reference covers activation control, frame nesting, note placement and the spacing knobs.

Charts

layout: chart reads all of its children, fixes one shared scale from their data, then draws — bars, lines, areas, dots and bubbles on one plane, and the part-to-whole layout: pie.

Categories and one series

|chart| "Deploys per weekday" { categories: "Mon", "Tue", "Wed", "Thu", "Fri"; } [
  |bars| { data: 4, 9, 6, 12, 7; }
]

categories: names the x axis and data: gives one value per category — the two counts must match, and a mismatch is an error rather than a short bar.

Nothing here says how anything should look. The chart’s label became the title, the value axis fitted itself to the numbers, and the colour came off the palette.

More than one series

|chart| "Revenue by region ($k)" {
  categories: "Q1", "Q2", "Q3", "Q4"; bars: stacked;
} [
  |bars| "NA" { data: 40, 45, 50, 60; }
  |bars| "EU" { data: 30, 35, 33, 40; }
  |bars| "APAC" { data: 20, 25, 30, 38; }
]

Every series is a child node, and its label is its legend entry — the legend appears on its own the moment there are two.

bars: on the chart decides how the bar series combine:

• grouped (the default) — side by side.
• stacked — piled into a total, as here.
• overlay — drawn over one another.

Series walk the palette in order, so three series are three distinct hues with no colour declared.

Lines, axes and a reference mark

|chart| "Latency (ms)" { categories: "p50", "p90", "p99"; } [
  |axis#ms| { side: left; }
  |mark| "budget" { at: 250; axis: ms; stroke: --red-deep; stroke-style: dashed; }
  |line| "before" { data: 40, 180, 420; curve: smooth; marker: circle; }
  |line| "after" { data: 30, 120, 260; curve: smooth; marker: circle; }
]

|line| draws one shape through its data. curve: smooth interpolates without overshooting any point, and marker: puts a mark on every datum.

Write an |axis| only when you have something to say about it — here, only to carry an id so the |mark| can anchor to it.

A mark is placed in data space, not pixels. It tracks the scale, and survives a direction: row flip unchanged.

A formula, and a band across it

|chart| "Edge requests per second" { samples: 96; } [
  |axis#rps| { side: left; range: 0 900; }
  |axis#hour| "Hour of day (UTC)" { side: bottom; range: 0 24; step: 4; }
  |area| { fn: (70 + 620 * exp(-((x - 10.5)^2) / 7) + 470 * exp(-((x - 19)^2) / 11)); }
  |band| "over ceiling" { range: 9.5 11.5; axis: hour; fill: --amber; }
  |mark| "autoscale ceiling" { at: 600; axis: rps; stroke: --red-deep; stroke-style: dashed; }
]

A series may compute its values instead of listing them. fn: is an expression in x, sampled samples: times across the domain, with the whole expression engine available — locals, the ternary, and any function the stylesheet binds. Two Gaussians make the morning and evening peaks here.

range: on an axis is the visible window, and it is doing two different jobs above:

• On the x axis it is the formula’s domain — what fn: sweeps.
• On the value axis it leaves headroom above the mark.

Points, labels and hover

|chart| "Score vs. thinking budget" { width: 460; height: 280; } [
  |axis| "tokens per task (k)" { side: bottom; }
  |axis| "eval score (%)" { side: left; range: 40 90; }
  |line| "GLM-5.2" { data: 9 52, 16 63, 27 72, 48 79, 88 83; labels: "off", "low", "mid", "high", "max"; curve: smooth; marker: circle; tooltip: always; }
  |dots| "GLM-5.1" { data: 5 47, 12 54, 20 58, 29 62, 40 65, 54 68, 68 69, 86 71; }
]

x y pairs make a numeric x axis — a scatter, rather than the categories of the first two figures.

labels: is the per-datum text, one entry per point. Where a label fits it sits on the plot; where it does not it falls to a hover card, and tooltip: always forces every one inline for export. Every marked point also carries a native <title>, so the figure is readable by hover in any viewer.

Left to fit itself, the value axis would start at zero and crush these scores into the top strip. range: 40 90 is the window that actually matters.

Dates and calendar ticks

|chart| "p95 latency, eu-west (ms)" { width: 560; } [
  |axis#t| { side: bottom; step: 2 week; }
  |band| "incident" { range: "2026-01-24" "2026-02-14"; axis: t; fill: --amber; }
  |mark| "rollback" { at: "2026-02-09"; axis: t; stroke: --red-deep; stroke-style: dashed; }
  |line| { data: "2026-01-05" 240, "2026-01-12" 232, "2026-01-19" 251, "2026-01-26" 384, "2026-02-02" 412, "2026-02-09" 301, "2026-02-16" 262, "2026-02-23" 244, "2026-03-02" 231, "2026-03-09" 225, "2026-03-16" 219; curve: smooth; marker: dot; }
]

A point’s x may be a quoted ISO date, and the dates are what make the axis a time axis — there is no scale: to write.

Ticks are then calendar-aware: the span picks the unit, the ticks land on real boundaries, and the label follows that unit. step: overrides it with a calendar interval — 2 week here, or month — and a plain number is an error.

Everything else measured on that axis is written in the same literals. The |band| shading the incident and the |mark| on the rollback both take dates, because a dated domain is a domain like any other — the other kind is an error either way round. All the arithmetic is UTC, so the figure renders the same in every timezone.

Bubbles, and a third number

|chart| "Cost by service ($k / month)" { width: 460; height: 300; } [
  |axis| "requests/s" { side: bottom; }
  |axis| "p99 latency (ms)" { side: left; }
  |bubble| "billing" { at: 300 60; value: 4; }
  |bubble| "auth" { at: 1200 45; value: 7; }
  |bubble| "cart" { at: 900 105; value: 9; }
  |bubble| "media" { at: 2100 155; value: 40; }
  |bubble| "search" { at: 3400 215; value: 26; }
  |bubble| "feed" { at: 4200 95; value: 17; }
]

A |bubble| is one mark per node rather than a series of data: at: places it on the plane, and value: sizes it.

The scale is by area, so four times the cost is twice the radius. That is what lets a bubble carry a third number without a third axis.

The label rides inside the bubble where it fits and beside it where it does not — and each bubble, being its own node, takes the next hue in the palette walk.

Radar

|chart| "Profiles" { direction: radial; categories: "Speed", "Range", "Armour", "Cost", "Stealth"; } [
  |axis| { range: 0 5; }
  |line| "Scout" { data: 5, 4, 2, 3, 5; }
  |area| "Cruiser" { data: 3, 3, 5, 4, 2; fill: --purple; }
]

direction: radial bends the category axis into a ring — one spoke per category — and turns the value axis into the radius. A |line| then closes into a polygon, and an |area| fills one.

The data is untouched by that flip, which is the rule for every direction: the plane is projected differently, never re-authored.

Part to whole

|pie| "Spend by channel" { hole: 0.5; } [
  |slice| "Ads" { value: 40; }
  |slice| "SEO" { value: 25; }
  |slice| "Email" { value: 20; }
  |slice| "Direct" { value: 15; }
]

layout: pie turns each |slice|’s value: into an angle; the values need no normalising, since the whole is their sum. hole: is the inner-radius fraction, so 0.5 is a donut and the default 0 a full pie.

Go deeper

The full chart reference covers log and reversed scales, per-datum paint, segmented formulas, format: and the tooltip rules.

Drawings

layout: drawing reads a figure as a dimensioned sheet: every child sits on one shared datum, and the links become annotations whose values are measured off the geometry rather than typed.

A plate and two dimensions

{ layout: drawing; density: 3; }

|rect#plate| { width: 120; height: 70; }

plate:left (-) plate:right { side: bottom; tol: 0.2; }
plate:top (-) plate:bottom { side: right; }