Lini

Lini — writing beautiful diagrams

Lini compiles plain text to clean, themeable SVG: composable nodes, a CSS-like cascade, compile-time layout. One core drives every diagram family. This file is self-sufficient for real work; SPEC.md (the full language), ROUTING.md (wire geometry), and samples/ (the showroom — one file per feature cluster) go deeper.

The loop

Write → compile → look at the render → refine. Never ship a diagram you haven't seen.

lini d.lini -o d.svg                 # compile; errors are file:line:col with fixes
lini --check --strict d.lini         # full compile, nothing written; warnings fail — the pre-finish gate
lini fmt d.lini                      # canonical formatting in place (--check: exit 1 if it would change)
lini --static d.lini -o s.svg && resvg s.svg d.png   # rasterize, then READ d.png

--static inlines CSS variables and outlines text — required before resvg (it can't resolve var()). Outlining covers the bundled Latin charset; a run with CJK, Arabic, arrows, or emoji stays <text> and warns (O001) — check the PNG for it. --strict / --no-warn bind every form (SVG, --check, --json diagnostics for tooling). Also: --watch (with -o), --format html, --embed-font (browser-only @font-face), --theme NAME|FILE|light/dark. Exit codes: 0 ok · 1 error (or fmt --check would reformat) · 2 I/O · 3 bad CLI. In this repo the binary is target/release/lini (cargo build --release if missing). lini desugar d.lini prints the lowered form when sugar confuses; lini serve opens a live playground.

A complete file

A file is one optional { } stylesheet, then drawn statements in source order. The stylesheet configures and styles; it draws nothing, and must come first.

{                                          // the stylesheet — setup only
  layout: grid;  columns: repeat(2);  gap: 30;   // scene config (root declarations)
  --brand: #ff6600;                        // a themeable colour variable
  w = 120;  scale(n) = (100 * 1.2^n);      // bindings — baked numbers / functions
  |box| { radius: 6; }                     // a rule: style every box
  |-| { stroke: --gray-deep; }             // a rule: style every link
  .hot { stroke: --red-deep; }             // a class definition
  |svc::box| { fill: --teal-wash; stroke: --teal-ink; }  // a define: new type over a base
  |room::group| { gap: 40; } [             // a define with a BODY: intrinsic children + links,
    |box#in| "in"; |box#out| "out"         //   re-materialised per instance; ids local,
    in -> out "flows"                      //   reachable from outside as `garden.out`
  ]
}

|svc#api| "API"                            // instances — the canvas
|cyl#db| "Postgres" { fill: --rose-wash; }
|room#garden|
api -> db "queries" .hot                   // a link with a label and a worn class
users -> api                               // undeclared id → auto-creates |box#users| "users"
garden.out -> api                          // a dot-path into a body

Every drawn statement is a node (|…|), a text leaf ("…"), or a link (bare name + operator). The full node anatomy — only the bars are required, order fixed — is |type#id| "label" .class1.class2 { key: value; } [ children ]; a link takes the same tail on a different head: a -> b "label" .cls { } [ ].

Syntax laws that bite

• Declarations end with ; and live only inside { }. A value runs to its ;, so it may span lines. (; optional right before }.)
• A statement ends at a newline or ; — two nodes on one line need the ;: |topic| "A"; |topic| "B". Bare strings are self-delimiting ("a" "b" is two text leaves). A { } or [ ] may span lines freely.
• Text is always double-quoted; escapes \" \\ \n \t; leading/trailing spaces are trimmed. A bare word is an identifier (keyword, colour name, id). Single quotes are not strings. String-valued properties (title, hint, href, src) need quotes even for one word.
• The comma law: commas separate repeated list items, spaces separate the components of one item. data: 9, 15, 24 (three values) · data: 10 20, 30 40 (two x-y points) · padding: 5 2 5 5 (one four-part value: N · v h · t r b l) · gap: 8 0 (row col — flow, grid, sequence alike) · translate: 10 -4.
• Math needs parens — operators appear only inside (…): padding: (8 * 2); width: (w / 2). A call's own parens count, so an operator inside a call's arguments needs no inner group: move(-tail - 1, -y), right(w / 2), pattern: grid(1, 3, 0, pitch). Calls are bare (width: scale(3)), signed numbers are bare (translate: -35 20). Inside a group: + - * / ^, comparisons, a ? b : c, pi/e, 1e-6, locals (r = 40; 2 * r), a top-level , makes a point, and the math library — sqrt exp ln log abs sin cos tan min max clamp floor round pow. Stylesheet bindings (w = 120; wave(a, f) = (u * 320, a * sin(2 * pi * f * u));) read bare anywhere a value goes — stroke-width: w, move(w, 0), pattern: grid(1, 3, 0, pitch).
• Parametric geometry: a points: value may be one expression in the ambient clock u (0 → 1), sampled samples: times — |line| { points: (u * 320, 24 * sin(2 * pi * 3 * u)); samples: 64 }, or points: wave(18, 2) from a point-valued binding. Charts bind x the same way (below).
• A class is worn, never glued into bars: |box| .hot — not |box.hot|. The label comes before classes: |box#a| "A" .hot. First class spaced off the head, further ones glued: .hot.loud.
• --name variables are visual only (colours, font-family). Sizes, gaps, padding, font-size, letter-spacing, line-spacing, text-transform bake at compile time — literals or bindings, never variables.
• No coordinate property. Layout places nodes; to place absolutely use pin: center; translate: x y (parent-local coordinates, y grows down) — or layout: stack (below) when the whole scene is hand-placed.
• No text-align — a text's lines align by its container's horizontal packing knob: justify in a row, align in a column or grid — so align in a card, which stacks. Split intents: wrap text in its own |block| { justify: start; }.
• id.child paths glue (no spaces): kitchen.bowl. a:left forces a link side. Paths resolve exactly in scope — never searched, never auto-created. An anonymous container is scope-transparent: its children belong to the enclosing scope and no path names it.
• Comments are // … only. Identifiers are [a-zA-Z_][a-zA-Z0-9_-]*, case-sensitive. Ids may not start with lini-.

Cascade

Five tiers, most specific wins, ties → later wins: type defaults/rules |box| { } → descendant rules |table| |box| { } → class rules .hot { } → id rule #hero { } → the instance's own { } block. Links walk the same ladder via |-| (#g |-| { } styles links written in #g); (-) { } is the dimension subtype and beats |-| { } for dimensions only. Values replace wholesale (no per-component merge). Text properties (font-*, color, spacing, transform) plus clearance/routing/format/thickness also inherit down the tree, nearest ancestor wins — set font-size once on the root and everything scales, captions and link labels included.

Box model & placement

• Center origin; source order = paint order (later on top; layer: N overrides).
• Auto-size: box = content + padding each side (default 20 on framed boxes, 0 on |block|). Explicit width/height are floors — content never clips. Empty auto box = 2×padding (40×40).
• max-width: N wraps text to fit (text-wrap: nowrap forbids); the wrapped size is the measured size.
• pin lifts a child out of flow onto a parent anchor: center, edges (top …), corners (top left …). A pinned child is an overlay — paints above, never grows the parent.
• translate: x y nudges any node after placement (layout-neutral); rotate: N turns about the bbox centre. Both work on text too.
• Flow containers: direction: row | column (default row — source order flows the way it reads; a closed shape's and a |topic|'s children are card content and stack instead, so an icon sits over its label), gap (default 36; 12 in card content; gap: row col), align (cross axis) / justify (main axis): start | center | end | stretch | evenly | origin — no-ops without slack (explicit size or fixed tracks). Inside a drawing/floorplan/stack scope a block that must lay out its own content states layout: flow itself (|room::block| { layout: flow; direction: column; align: center }).
• Grid: columns required — columns: 80, auto, repeat(3), repeat(5, 80); rows optional; children auto-flow, or cell: col row / span: cols rows (span: 2 = 2 1) on any non-text child (bare text can't carry them — wrap it in |block|). Empty "" holds a grid cell. Per-column alignment: align: start, center, end (one entry per track).
• gap-fill: colour paints the gutters (gap: 1; gap-fill: --stroke = hairline rules — how |table| works).

Node catalogue

Primitives: |block| (frameless base rect), |oval| (equal sides = circle: |oval| { width: 40 }), |hex|, |slant|, |cyl|, |diamond|, |poly| (points:), |line| (points:, marker*:), |path| (raw SVG path:), |image| (src: + width/height; local files embed; fit: auto | contain | cover | stretch), |icon| (a Phosphor icon), |sketch| (draw: pen — see Drawing). Text is not a node type — a bare "…" is a text leaf; wrap it in |block| when it needs an id, border, padding, or pin.

Templates (all overridable; extend with |name::base| { … }):

Shape extras: multiple: N (one offset duplicate behind — "several of these"; N is the offset, not a count), shadow: dx dy blur, stroke-style: solid|dashed|dotted (+ drafting center/phantom on shapes, wavy on links only) — one node, one stroke style: dashed interior geometry is its own child — opacity: 0.75. href: "url" makes anything clickable; hint: "…" adds a tooltip/accessible <title>. A standalone arrow is |line| { points: 0 0, 50 0; marker-end: arrow; }.

Links

a -> b                          // 1 link (labels boxes into existence)
a -> b -> c                     // chain: 2 links, every hop marked
a -> b & c                      // fan-out — shares one trunk at a's side
a & b -> c                      // fan-in
|group#g| [ |box#child| "C" ]
a:right -> g.child:left "label" // forced sides, path endpoint, label
client -> |cyl#db|              // capsule endpoint: declare + link in one statement

Operators are [marker][line][marker], glued. Lines: - solid, -- dashed, --- dotted, ~ wavy. End markers: > arrow, < crow, * dot, <> diamond (mirrored at the start: <-, <->, *-*…). ER cardinality (crow's-foot), end-side forms: -+ one · -< many · -o+ zero-or-one · -+< one-or-many · -o< zero-or-many · -++ exactly one (mirror at the start: >o-o<). The same set by name on marker: / marker-start: / marker-end: (overriding the operator, and the only way on a standalone |line|): arrow dot circle diamond one crow exactly-one zero-or-one one-or-many zero-or-many datum none.

• Style links like nodes: |-| { stroke: #888; stroke-width: 1.5; } for all, a worn class per link (a -> b .loud), the link's own { } to override. stroke* is the wire; color/font-* the labels.
• Labels: one inline (a -> b "hi"), several or styled ones in [ ]: a -> b { along: 0.3, 0.7; } [ "near a" "near b" ]. Labels slide to dodge; they never move the wire.
• Scene config, not link paint: clearance: N (min gap wire↔node; 16 in flow, 10 in a schematic, 18 for dimensions) and routing: orthogonal | natural | straight sit on a container's { } and cascade. orthogonal (default) = right-angle runs, rounded corners; natural = smooth direct curves (the mindmap look — free crossings); straight = one trimmed segment. Per-link routing: is an error.
• A self-loop a -> a exits right, hooks over the top. Bodies are sealed: a link inside [ ] connects that body's own children; cross-container links go at the lowest scope seeing both ends, via dot-paths. Where a link is written is its routing world: a link between two children of one group routes inside that group only if written in its [ ] — written at root it detours around the group's outside. Keep intra-group wires in the group.
• An unroutable link draws as a dashed slanted stray and is reported — fix by widening gap, shrinking clearance, or re-siding; nodes never move.

Colour & theming

Every colour is a light-dark() pair — dark mode is automatic; never hardcode hex where a variable fits. Role variables (as values, write the short form): --bg, --fill, --stroke, --stroke-dark (full drafting black — pen geometry, walls, dimension linework), --stroke-light (thin support tone — centrelines, extension lines), --accent, --muted, --danger, --warn. fill: --bg on the root paints the backdrop (default is none — transparent).

The palette is the beauty engine. Eleven hues — red rose orange amber lime green teal sky blue purple gray (aliases yellow→amber pink→rose indigo→purple cyan→teal) — each in five job-named tiers that survive the dark flip: --teal-wash (palest — card/section backgrounds) · --teal-soft (pastel fill, charts) · --teal (everyday pastel) · --teal-deep (strong — borders, strokes, wires) · --teal-ink (deepest — text). The coloured-node recipe is wash fill + ink (or deep) stroke + ink text: { fill: --teal-wash; stroke: --teal-ink; color: --teal-ink; }. red is reserved for danger; rose is the decorative pink. Literal colours: #f80, CSS names, rgb(), hsl(280, 55%, 50%), oklch(0.72, 0.16, 25) (the palette's own space).

Gradients (on fill/stroke/gap-fill): gradient(--rose, --sky) auto-135°, linear-gradient(135, --rose, --sky), radial-gradient(…). hatch(45) / hatch(45, 6, --gray-deep) is the section-line fill texture. Declare your own variables in the stylesheet: --brand: #ff6600; then fill: --brand.

Text: bundled Google Sans (default) and Google Sans Code (mono, via font-family: "Google Sans Code"). font-weight: normal | medium | semibold | bold (or 400–700), font-style: italic, text-decoration: underline | line-through, text-shadow: dx dy blur colour, text-transform: uppercase | lowercase | capitalize, letter-spacing / line-spacing (px). Body default 15/medium; captions and link labels derive from the inherited size, so one root font-size: scales everything.

Themes re-skin at render time — no file edits: --theme takes a builtin (light · dark · high-contrast · blueprint, white linework on cyanotype blue — the diazo print, for any diagram), a CSS file of --lini-* overrides, or a light/dark pair. lini theme NAME prints a builtin as CSS to start your own.

Layout engines

layout: on any container (the root included): flow (default) · grid · stack · tree · sequence · chart · pie · drawing · floorplan · schematic. Everything core — cascade, paint, palette, links syntax — works identically inside each.

Tables & entities

|table#basket| { columns: 80, 140, 80; align: start, center, end; } [
  "Fruit" "Quantity" "Notes"       // first row → header band
  "Apple" "12"       "fresh"
  "Mango" "3" { color: --red-ink }  "ripe"   // a styled cell
]

|entity#users| "Users" { columns: auto, auto, auto; } [
  "PK" "id"    "int"
  ""   "email" "varchar"
]
users -o< orders        // crow's-foot relationship, lands on the card edge

Style cells with |table| |cell| { … }, the header with |table| |header| { … }. A cell needing an id (to wire a field) is written as one: |cell#uid| "user_id" (a |block| there loses the cell inset).

Tree & mindmap

Structure is |topic| nesting inside a layout: tree scope — exactly one root topic; non-topic children are a topic's own content (an icon, a badge). direction: column (org chart, default) · row (outline) · bilateral (mindmap split; per-branch side: left|right overrides). Branch wires are generated; style a whole arm with #branchid |-| { }; size a tier with .lini-level-2 { font-size: 12; }.

|mindmap| "Root" [ |topic#ship| "Shipping" [ |topic| "Weekly train" ] … ] is the preset worth reaching for: bilateral + routing: natural + an automatic hue per first-level branch (wash fill, deep stroke and wires, ink text) + depth-ramped sizes + max-width: 160 wrap. Authored cross-links stay neutral: a.x:right --- b.y:right "relates" { along: 0.8; }.

Sequence

layout: sequence reads links as time: participants across the top (declared, or auto-created on first use), messages top-to-bottom in source order. -> call (opens an activation bar) · --> return (closes it) · ~> async · a -> a self-message. A participant's own paint colours its lifeline and bars.

{ layout: sequence; }
|box#user| "Customer" { fill: --rose-wash; stroke: --rose-deep; } [
  |icon| { symbol: 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"
|loop| "each item" [
  shop -> db "reserve stock"
  db --> shop "in stock"
]
|note| "rate-limited" { place: over shop db; }

Frames: |loop| / |opt| / |alt| (+ |else| separators) hold their messages in [ ] but open no scope — messages always wire the sequence's participants. gap: row col spaces rows/columns. place: modes: over a (one lifeline), over a b (span), left a / right a (beside). A named actor is a box wrapping an icon (above) — a bare |icon#user| "user" spends its label on the symbol name.

Charts & pie

A chart fixes a shared scale from all children, then draws. Default size 360×220 (width/height set the whole box); radial/pie default 280 square.

|chart| "Cycle time (s)" { categories: "15", "30", "50"; } [
  |bars| "1.8 kW" { data: 9, 15, 24; }
  |bars| "2.3 kW" { data: 7, 13, 20; }
]

• Series: |bars|, |line|, |area| (baseline: 40 floats the fill off axis zero), |dots| (+ per-node |bubble| { at: x y; value: N; }; |slice| { value: N; } in a pie). Label = legend entry (auto-shown at ≥ 2). Data — one of data: / fn:, never both: categorical data: 9, 15, 24 (must match categories: count) · points data: 0 225, 60 221 · dates data: "2026-01-01" 18, … · formula in x sampled over the domain (samples: count): fn: (min(100, x * 2)), a bare call fn: cure(18), or per-band segments fn: (0.1 + u^2), 5, (2 * u) — one per |band|, each in its local clock u (0 → 1). labels: "a", "b", … per-datum text needs explicit data:.
• Colour is automatic and good: series walk the palette (interleaved hues, red skipped) in the outlined look — soft fill + deep edge. Only override for meaning: fill: --sky-soft, stroke: --teal. Per-datum highlight on bars/ dots: fill: auto, auto, --red, auto.
• curve: linear (default) | smooth (monotone, never overshoots) | step; marker: dot|circle|diamond puts a mark at every datum; tooltip: none|hover|auto|always.
• Axes only when you have something to say: |axis#t| "Speed (mm/s)" { side: bottom; range: 0 133; unit: "%"; scale: log|time; step: 50; } (step: month / 2 week on a time axis; ticks: an explicit list). Bind a series with axis: t. range: 50 1 reverses; gridlines: none or a colour. format: decimal 1 | significant 3 | percent 0 | scientific 2 | engineering 1 | fraction 8 | year|month|day|hour|minute on a scope, axis, series, or dimension — inherits; presentation only, never measurement.
• Annotations in data space: |band| "Hold" { range: 1.5 4; axis: t; fill: --amber; } shades a region; a |mark| is a reference line (at: V), a labelled point (at: x y), or label-only (marker: none) — style its rule like a wire: |mark| "SLO 250 ms" { at: 250; axis: ms; stroke: --amber-deep; stroke-style: dashed; color: --amber-ink; }.
• direction: row flips bars horizontal; direction: radial makes radar (lines close into polygons); bars: grouped (default) | stacked | overlay combines bar series. |pie| { hole: 0.5 } is a donut.

Stack (one datum)

layout: stack arranges nothing: every child's origin lands on the container's datum and translate: is the only offset. A symmetric primitive's origin is its centre, so shapes stack concentric; a |sketch|'s is its pen origin, so several sketches keep the frame they were drawn in — which flow throws away. Reach for it for artwork (a logo), a hand-placed figure, or a diagram tuned past what an arranger will do.

{ layout: stack; unit: mm; density: 10; padding: 25; cap = 0.9; bowl = 2.5; }
|sketch#n| { draw: move(0, -3.4) arc(3.4, 3.4, 3.4) down(bowl) arc(cap, 180) up(bowl); mirror: y-axis; }
|sketch#dots| { draw: move(11, -9) down(1) arc(cap, -180) up(1) arc(cap, -180) close(); pattern: grid(1, 3, 0, 3); }

|stack| is the node form. Links go to the router, so arrows and labels behave as in a flow. gap/direction/align/justify are ignored (a root block refuses them). Nested boxes are unaffected: a |box| inside a stack still lays out its own content. Units: unit: px (the default) is 1 : 1; unit: mm plus a root density: (px per mm, default 4) draws in millimetres — density: 10 renders a 24 mm mark 240 px wide. layout: drawing is this engine plus drafting — mates, dimensions, generated chrome. Same placement, so |sketch|, mirror: and pattern: work identically in both; only a drawing draws a fused mirror's centreline.