Skip to content
Back to search

lini

SkillWorks with Claude CodeGitHub

Use when asked to create, edit, review, or debug a Lini diagram (a .lini file or its SVG) — architecture/box-and-arrow diagrams, flowcharts, mindmaps, org charts, ER schemas, tables, sequence diagrams, bar/line/area/pie/radar/scatter charts, engineering drawings, floor plans, circuit schematics, or pen-drawn artwork written in the Lini language.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/monfa-red--lini/badge.svg)](/listings/monfa-red--lini)

HTML

<a href="/listings/monfa-red--lini"><img src="/api/listings/monfa-red--lini/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

cargo install lini
lini diagram.lini -o diagram.svg   # compile to SVG
lini serve diagram.lini            # live-reloading preview
lini serve samples/                # browse and edit the bundled examples

Six lines — a type define, a container, and two links Lini routes for you:

{ |svc::box| { fill: --teal-wash; stroke: --teal-ink } }

|group| "Services" [ |svc#api| "API"; |svc#auth| "Auth" ]
|svc#db| "Postgres"

api  -> db "read"
auth -> db "write"

`{ }` is style, `[ ]` is children, and naming two nodes draws an orthogonal path between them, clear of everything in the way. The rest of the grammar is the [tour](https://lini.rs/docs/tour/language.html).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 722 lines
  1. ---
  2. name: lini
  3. description: Use when asked to create, edit, review, or debug a Lini diagram (a .lini file or its SVG) — architecture/box-and-arrow diagrams, flowcharts, mindmaps, org charts, ER schemas, tables, sequence diagrams, bar/line/area/pie/radar/scatter charts, engineering drawings, floor plans, circuit schematics, or pen-drawn artwork written in the Lini language.
  4. ---
  5. # Lini — writing beautiful diagrams
  6. Lini compiles plain text to clean, themeable SVG: composable nodes, a CSS-like
  7. cascade, compile-time layout. One core drives every diagram family. This file is
  8. self-sufficient for real work; `SPEC.md` (the full language), `ROUTING.md` (wire
  9. geometry), and `samples/` (the showroom — one file per feature cluster) go deeper.
  10. ## The loop
  11. Write → compile → **look at the render** → refine. Never ship a diagram you
  12. haven't seen.
  13. ```sh
  14. lini d.lini -o d.svg # compile; errors are file:line:col with fixes
  15. lini --check --strict d.lini # full compile, nothing written; warnings fail — the pre-finish gate
  16. lini fmt d.lini # canonical formatting in place (--check: exit 1 if it would change)
  17. lini --static d.lini -o s.svg && resvg s.svg d.png # rasterize, then READ d.png
  18. ```
  19. `--static` inlines CSS variables and outlines text — required before `resvg`
  20. (it can't resolve `var()`). Outlining covers the bundled Latin charset; a run
  21. with CJK, Arabic, arrows, or emoji stays `<text>` and warns (`O001`) — check the
  22. PNG for it. `--strict` / `--no-warn` bind every form (SVG, `--check`, `--json`
  23. diagnostics for tooling). Also: `--watch` (with `-o`), `--format html`,
  24. `--embed-font` (browser-only `@font-face`), `--theme NAME|FILE|light/dark`.
  25. Exit codes: 0 ok · 1 error (or `fmt --check` would reformat) · 2 I/O · 3 bad CLI.
  26. In this repo the binary is `target/release/lini` (`cargo build --release` if
  27. missing). `lini desugar d.lini` prints the lowered form when sugar confuses;
  28. `lini serve` opens a live playground.
  29. ## A complete file
  30. A file is **one optional `{ }` stylesheet, then drawn statements** in source
  31. order. The stylesheet configures and styles; it draws nothing, and must come
  32. first.
  33. ```
  34. { // the stylesheet — setup only
  35. layout: grid; columns: repeat(2); gap: 30; // scene config (root declarations)
  36. --brand: #ff6600; // a themeable colour variable
  37. w = 120; scale(n) = (100 * 1.2^n); // bindings — baked numbers / functions
  38. |box| { radius: 6; } // a rule: style every box
  39. |-| { stroke: --gray-deep; } // a rule: style every link
  40. .hot { stroke: --red-deep; } // a class definition
  41. |svc::box| { fill: --teal-wash; stroke: --teal-ink; } // a define: new type over a base
  42. |room::group| { gap: 40; } [ // a define with a BODY: intrinsic children + links,
  43. |box#in| "in"; |box#out| "out" // re-materialised per instance; ids local,
  44. in -> out "flows" // reachable from outside as `garden.out`
  45. ]
  46. }
  47. |svc#api| "API" // instances — the canvas
  48. |cyl#db| "Postgres" { fill: --rose-wash; }
  49. |room#garden|
  50. api -> db "queries" .hot // a link with a label and a worn class
  51. users -> api // undeclared id → auto-creates |box#users| "users"
  52. garden.out -> api // a dot-path into a body
  53. ```
  54. Every drawn statement is a node (`|…|`), a text leaf (`"…"`), or a link (bare
  55. name + operator). The full node anatomy — **only the bars are required, order
  56. fixed** — is `|type#id| "label" .class1.class2 { key: value; } [ children ]`;
  57. a link takes the same tail on a different head: `a -> b "label" .cls { } [ ]`.
  58. ## Syntax laws that bite
  59. - **Declarations end with `;`** and live only inside `{ }`. A value runs to its
  60. `;`, so it may span lines. (`;` optional right before `}`.)
  61. - **A statement ends at a newline or `;`** — two nodes on one line need the `;`:
  62. `|topic| "A"; |topic| "B"`. Bare strings are self-delimiting (`"a" "b"` is
  63. two text leaves). A `{ }` or `[ ]` may span lines freely.
  64. - **Text is always double-quoted**; escapes `\" \\ \n \t`; leading/trailing
  65. spaces are trimmed. A bare word is an identifier (keyword, colour name, id).
  66. Single quotes are not strings. String-valued properties (`title`, `hint`,
  67. `href`, `src`) need quotes even for one word.
  68. - **The comma law**: commas separate repeated list items, spaces separate the
  69. components of one item. `data: 9, 15, 24` (three values) · `data: 10 20, 30 40`
  70. (two x-y points) · `padding: 5 2 5 5` (one four-part value: `N` · `v h` ·
  71. `t r b l`) · `gap: 8 0` (row col — flow, grid, sequence alike) · `translate: 10 -4`.
  72. - **Math needs parens** — operators appear only inside `(…)`: `padding: (8 * 2);`
  73. `width: (w / 2)`. **A call's own parens count**, so an operator inside a call's
  74. arguments needs no inner group: `move(-tail - 1, -y)`, `right(w / 2)`,
  75. `pattern: grid(1, 3, 0, pitch)`. Calls are bare (`width: scale(3)`), signed
  76. numbers are bare (`translate: -35 20`). Inside a group: `+ - * / ^`,
  77. comparisons, `a ? b : c`, `pi`/`e`, `1e-6`, locals (`r = 40; 2 * r`), a
  78. top-level `,` makes a point, and the math library — `sqrt exp ln log abs sin
  79. cos tan min max clamp floor round pow`. Stylesheet bindings (`w = 120;`
  80. `wave(a, f) = (u * 320, a * sin(2 * pi * f * u));`) read bare anywhere a value
  81. goes — `stroke-width: w`, `move(w, 0)`, `pattern: grid(1, 3, 0, pitch)`.
  82. - **Parametric geometry**: a `points:` value may be one expression in the ambient
  83. clock `u` (0 → 1), sampled `samples:` times — `|line| { points: (u * 320, 24 *
  84. sin(2 * pi * 3 * u)); samples: 64 }`, or `points: wave(18, 2)` from a
  85. point-valued binding. Charts bind `x` the same way (below).
  86. - **A class is worn, never glued into bars**: `|box| .hot` — not `|box.hot|`.
  87. The label comes before classes: `|box#a| "A" .hot`. First class spaced off the
  88. head, further ones glued: `.hot.loud`.
  89. - **`--name` variables are visual only** (colours, `font-family`). Sizes, gaps,
  90. padding, `font-size`, `letter-spacing`, `line-spacing`, `text-transform` bake
  91. at compile time — literals or bindings, never variables.
  92. - **No coordinate property.** Layout places nodes; to place absolutely use
  93. `pin: center; translate: x y` (parent-local coordinates, y grows down) — or
  94. `layout: stack` (below) when the whole scene is hand-placed.
  95. - **No `text-align`** — a text's lines align by its container's *horizontal*
  96. packing knob: `justify` in a row, `align` in a column or grid — so `align` in
  97. a card, which stacks. Split intents: wrap text in its own
  98. `|block| { justify: start; }`.
  99. - **`id.child` paths glue** (no spaces): `kitchen.bowl`. `a:left` forces a link
  100. side. Paths resolve exactly in scope — never searched, never auto-created. An
  101. **anonymous** container is scope-transparent: its children belong to the
  102. enclosing scope and no path names it.
  103. - Comments are `// …` only. Identifiers are `[a-zA-Z_][a-zA-Z0-9_-]*`,
  104. case-sensitive. Ids may not start with `lini-`.
  105. ## Cascade
  106. Five tiers, most specific wins, ties → later wins:
  107. type defaults/rules `|box| { }` → descendant rules `|table| |box| { }` → class
  108. rules `.hot { }` → id rule `#hero { }` → the instance's own `{ }` block.
  109. Links walk the same ladder via `|-|` (`#g |-| { }` styles links written in `#g`);
  110. `(-) { }` is the dimension subtype and beats `|-| { }` for dimensions only.
  111. Values replace wholesale (no per-component merge). Text properties (`font-*`,
  112. `color`, spacing, transform) plus `clearance`/`routing`/`format`/`thickness`
  113. also **inherit** down the tree, nearest ancestor wins — set `font-size` once on
  114. the root and everything scales, captions and link labels included.
  115. ## Box model & placement
  116. - **Center origin**; source order = paint order (later on top; `layer: N` overrides).
  117. - **Auto-size**: box = content + `padding` each side (default 20 on framed
  118. boxes, 0 on `|block|`). Explicit `width`/`height` are **floors** — content
  119. never clips. Empty auto box = 2×padding (40×40).
  120. - **`max-width: N`** wraps text to fit (`text-wrap: nowrap` forbids); the
  121. wrapped size is the measured size.
  122. - **`pin`** lifts a child out of flow onto a parent anchor: `center`, edges
  123. (`top` …), corners (`top left` …). A pinned child is an overlay — paints above,
  124. never grows the parent.
  125. - **`translate: x y`** nudges any node after placement (layout-neutral);
  126. **`rotate: N`** turns about the bbox centre. Both work on text too.
  127. - Flow containers: `direction: row | column` (default row — source order flows
  128. the way it reads; a closed shape's and a `|topic|`'s children are **card
  129. content** and stack instead, so an icon sits over its label), `gap` (default
  130. 36; 12 in card content; `gap: row col`), `align` (cross axis) / `justify`
  131. (main axis): `start | center | end | stretch | evenly | origin` — no-ops
  132. without slack (explicit size or fixed tracks). Inside a drawing/floorplan/stack
  133. scope a block that must lay out its own content states `layout: flow` itself
  134. (`|room::block| { layout: flow; direction: column; align: center }`).
  135. - Grid: `columns` **required** — `columns: 80, auto, repeat(3), repeat(5, 80)`;
  136. `rows` optional; children auto-flow, or `cell: col row` / `span: cols rows`
  137. (`span: 2` = `2 1`) on any non-text child (bare text can't carry them — wrap it
  138. in `|block|`). Empty `""` holds a grid cell. Per-column alignment:
  139. `align: start, center, end` (one entry per track).
  140. - `gap-fill: colour` paints the gutters (`gap: 1; gap-fill: --stroke` =
  141. hairline rules — how `|table|` works).
  142. ## Node catalogue
  143. Primitives: `|block|` (frameless base rect), `|oval|` (equal sides = circle:
  144. `|oval| { width: 40 }`), `|hex|`, `|slant|`, `|cyl|`, `|diamond|`, `|poly|`
  145. (`points:`), `|line|` (`points:`, `marker*:`), `|path|` (raw SVG `path:`),
  146. `|image|` (`src:` + `width`/`height`; local files embed; `fit: auto | contain |
  147. cover | stretch`), `|icon|` (a Phosphor icon), `|sketch|` (`draw:` pen — see
  148. Drawing). Text is not a node type — a bare `"…"` is a text leaf; wrap it in
  149. `|block|` when it needs an id, border, padding, or pin.
  150. Templates (all overridable; extend with `|name::base| { … }`):
  151. | Type | What it is |
  152. |---|---|
  153. | `\|box\|` | the default: rounded framed card (radius 8, padding 20) |
  154. | `\|rect\|` | sharp-cornered box |
  155. | `\|queue\|` | message queue — a `\|cyl\|` on its side, label level; any cyl takes `facing: up \| right \| down \| left` (never `rotate:`, which turns the label) |
  156. | `\|group\|` | dashed light frame for a captioned region |
  157. | `\|caption\|` · `\|footnote\|` · `\|sheet-caption\|` | small muted title pinned above the top-left corner (a group/table **label becomes one**) · at the bottom centre · inside the top-left corner (a schematic scope's label lowers to it) |
  158. | `\|badge\|` | small accent pill pinned over the top-right corner |
  159. | `\|row\|` / `\|column\|` / `\|grid\|` / `\|stack\|` | frameless layout wrappers |
  160. | `\|icon\|` / `\|sign\|` | Phosphor icon: **`symbol: bell` or the label names the glyph — never both** (`\|icon\| "user"` *is* the user glyph, unnamed on the page; a captioned icon is a box wrapping one: `\|box#cdn\| "CDN" [ \|icon\| { symbol: cloud } ]`). `\|sign\|` is the 64px standalone preset (`fit: contain`). **Icons paint with `fill` (body) + `stroke` (line)** — `color:` does nothing. An icon's `[ ]` text rides *on* the symbol as a badge and grows the square: `\|icon\| { symbol: bell } [ "3" ]` |
  161. | `\|table\|` | ruled grid; first row auto-becomes the header band; cells via bare strings |
  162. | `\|entity\|` | ER card: label = centred title, rows = `"field" "type"` (3 columns for a key gutter) |
  163. | `\|note\|` | folded-corner callout card (works in every layout) |
  164. | `\|topic\|` / `\|mindmap\|` | tree structure node / the full mindmap preset |
  165. | `\|chart\|` / `\|pie\|` / `\|sequence\|` / `\|drawing\|` / `\|floorplan\|` / `\|schematic\|` | layout presets (below) |
  166. Shape extras: `multiple: N` (one offset duplicate behind — "several of these";
  167. `N` is the offset, not a count), `shadow: dx dy blur`,
  168. `stroke-style: solid|dashed|dotted` (+ drafting `center`/`phantom` on shapes,
  169. `wavy` on links only) — **one node, one stroke style**: dashed interior geometry
  170. is its own child — `opacity: 0.75`. `href: "url"` makes anything clickable;
  171. `hint: "…"` adds a tooltip/accessible `<title>`. A standalone arrow is
  172. `|line| { points: 0 0, 50 0; marker-end: arrow; }`.
  173. ## Links
  174. ```
  175. a -> b // 1 link (labels boxes into existence)
  176. a -> b -> c // chain: 2 links, every hop marked
  177. a -> b & c // fan-out — shares one trunk at a's side
  178. a & b -> c // fan-in
  179. |group#g| [ |box#child| "C" ]
  180. a:right -> g.child:left "label" // forced sides, path endpoint, label
  181. client -> |cyl#db| // capsule endpoint: declare + link in one statement
  182. ```
  183. Operators are `[marker][line][marker]`, glued. Lines: `-` solid, `--` dashed,
  184. `---` dotted, `~` wavy. End markers: `>` arrow, `<` crow, `*` dot, `<>` diamond
  185. (mirrored at the start: `<-`, `<->`, `*-*`…). ER cardinality (crow's-foot),
  186. end-side forms: `-+` one · `-<` many · `-o+` zero-or-one · `-+<` one-or-many ·
  187. `-o<` zero-or-many · `-++` exactly one (mirror at the start: `>o-o<`). The
  188. same set by name on `marker:` / `marker-start:` / `marker-end:` (overriding the
  189. operator, and the only way on a standalone `|line|`): `arrow dot circle diamond
  190. one crow exactly-one zero-or-one one-or-many zero-or-many datum none`.
  191. - Style links like nodes: `|-| { stroke: #888; stroke-width: 1.5; }` for all,
  192. a worn class per link (`a -> b .loud`), the link's own `{ }` to override.
  193. `stroke*` is the wire; `color`/`font-*` the labels.
  194. - Labels: one inline (`a -> b "hi"`), several or styled ones in `[ ]`:
  195. `a -> b { along: 0.3, 0.7; } [ "near a" "near b" ]`. Labels slide to dodge;
  196. they never move the wire.
  197. - **Scene config, not link paint**: `clearance: N` (min gap wire↔node; 16 in
  198. flow, 10 in a schematic, 18 for dimensions) and `routing: orthogonal | natural |
  199. straight` sit on a container's `{ }` and cascade. `orthogonal` (default) =
  200. right-angle runs, rounded corners; `natural` = smooth direct curves (the
  201. mindmap look — free crossings); `straight` = one trimmed segment. Per-link
  202. `routing:` is an error.
  203. - A self-loop `a -> a` exits right, hooks over the top. Bodies are sealed: a
  204. link inside `[ ]` connects that body's own children; cross-container links go
  205. at the lowest scope seeing both ends, via dot-paths. **Where a link is
  206. written is its routing world**: a link between two children of one group
  207. routes *inside* that group only if written in its `[ ]` — written at root it
  208. detours around the group's outside. Keep intra-group wires in the group.
  209. - An unroutable link draws as a dashed slanted **stray** and is reported —
  210. fix by widening `gap`, shrinking `clearance`, or re-siding; nodes never move.
  211. ## Colour & theming
  212. Every colour is a `light-dark()` pair — dark mode is automatic; **never
  213. hardcode hex where a variable fits**. Role variables (as values, write the
  214. short form): `--bg`, `--fill`, `--stroke`, `--stroke-dark` (full drafting
  215. black — pen geometry, walls, dimension linework), `--stroke-light` (thin
  216. support tone — centrelines, extension lines), `--accent`, `--muted`,
  217. `--danger`, `--warn`. `fill: --bg` on the root paints the backdrop (default is
  218. none — transparent).
  219. **The palette** is the beauty engine. Eleven hues — `red rose orange amber lime
  220. green teal sky blue purple gray` (aliases `yellow→amber pink→rose indigo→purple
  221. cyan→teal`) — each in five job-named tiers that survive the dark flip:
  222. `--teal-wash` (palest — card/section backgrounds) · `--teal-soft` (pastel
  223. fill, charts) · `--teal` (everyday pastel) · `--teal-deep` (strong — borders,
  224. strokes, wires) · `--teal-ink` (deepest — text). The coloured-node recipe is
  225. **wash fill + ink (or deep) stroke + ink text**: `{ fill: --teal-wash; stroke:
  226. --teal-ink; color: --teal-ink; }`. `red` is reserved for danger; `rose` is the
  227. decorative pink. Literal colours: `#f80`, CSS names, `rgb()`, `hsl(280, 55%,
  228. 50%)`, `oklch(0.72, 0.16, 25)` (the palette's own space).
  229. Gradients (on `fill`/`stroke`/`gap-fill`): `gradient(--rose, --sky)` auto-135°,
  230. `linear-gradient(135, --rose, --sky)`, `radial-gradient(…)`. `hatch(45)` /
  231. `hatch(45, 6, --gray-deep)` is the section-line fill texture. Declare your own
  232. variables in the stylesheet: `--brand: #ff6600;` then `fill: --brand`.
  233. Text: bundled **Google Sans** (default) and **Google Sans Code** (mono, via
  234. `font-family: "Google Sans Code"`). `font-weight: normal | medium | semibold |
  235. bold` (or 400–700), `font-style: italic`, `text-decoration: underline |
  236. line-through`, `text-shadow: dx dy blur colour`, `text-transform: uppercase |
  237. lowercase | capitalize`, `letter-spacing` / `line-spacing` (px). Body default
  238. 15/medium; captions and link labels derive from the inherited size, so one root
  239. `font-size:` scales everything.
  240. Themes re-skin at render time — no file edits: `--theme` takes a builtin
  241. (`light` · `dark` · `high-contrast` · `blueprint`, white linework on cyanotype
  242. blue — the diazo print, for any diagram), a CSS file of `--lini-*` overrides,
  243. or a `light/dark` pair. `lini theme NAME` prints a builtin as CSS to start your own.
  244. ## Layout engines
  245. `layout:` on any container (the root included): `flow` (default) · `grid` ·
  246. `stack` · `tree` · `sequence` · `chart` · `pie` · `drawing` · `floorplan` ·
  247. `schematic`. Everything core — cascade, paint, palette, links syntax — works
  248. identically inside each.
  249. ### Tables & entities
  250. ```
  251. |table#basket| { columns: 80, 140, 80; align: start, center, end; } [
  252. "Fruit" "Quantity" "Notes" // first row → header band
  253. "Apple" "12" "fresh"
  254. "Mango" "3" { color: --red-ink } "ripe" // a styled cell
  255. ]
  256. |entity#users| "Users" { columns: auto, auto, auto; } [
  257. "PK" "id" "int"
  258. "" "email" "varchar"
  259. ]
  260. users -o< orders // crow's-foot relationship, lands on the card edge
  261. ```
  262. Style cells with `|table| |cell| { … }`, the header with `|table| |header| { … }`.
  263. A cell needing an id (to wire a field) is written as one: `|cell#uid| "user_id"`
  264. (a `|block|` there loses the cell inset).
  265. ### Tree & mindmap
  266. Structure is `|topic|` nesting inside a `layout: tree` scope — exactly one root
  267. topic; non-topic children are a topic's own content (an icon, a badge).
  268. `direction: column` (org chart, default) · `row` (outline) · `bilateral`
  269. (mindmap split; per-branch `side: left|right` overrides). Branch wires are
  270. generated; style a whole arm with `#branchid |-| { }`; size a tier with
  271. `.lini-level-2 { font-size: 12; }`.
  272. `|mindmap| "Root" [ |topic#ship| "Shipping" [ |topic| "Weekly train" ] … ]` is
  273. the preset worth reaching for: bilateral + `routing: natural` + an automatic
  274. hue per first-level branch (wash fill, deep stroke and wires, ink text) +
  275. depth-ramped sizes + `max-width: 160` wrap. Authored cross-links stay neutral:
  276. `a.x:right --- b.y:right "relates" { along: 0.8; }`.
  277. ### Sequence
  278. `layout: sequence` reads links as time: participants across the top (declared,
  279. or auto-created on first use), messages top-to-bottom in source order. `->`
  280. call (opens an activation bar) · `-->` return (closes it) · `~>` async ·
  281. `a -> a` self-message. A participant's own paint colours its lifeline and bars.
  282. ```
  283. { layout: sequence; }
  284. |box#user| "Customer" { fill: --rose-wash; stroke: --rose-deep; } [
  285. |icon| { symbol: user; fill: none; stroke: --rose-deep; }
  286. ]
  287. |box#shop| "Storefront" { fill: --sky-wash; stroke: --sky-deep; }
  288. |cyl#db| "Orders" { fill: --orange-wash; stroke: --orange-deep; }
  289. user -> shop "place order"
  290. |loop| "each item" [
  291. shop -> db "reserve stock"
  292. db --> shop "in stock"
  293. ]
  294. |note| "rate-limited" { place: over shop db; }
  295. ```
  296. Frames: `|loop|` / `|opt|` / `|alt|` (+ `|else|` separators) hold their
  297. messages in `[ ]` but open no scope — messages always wire the sequence's
  298. participants. `gap: row col` spaces rows/columns. `place:` modes: `over a`
  299. (one lifeline), `over a b` (span), `left a` / `right a` (beside). A **named
  300. actor** is a box wrapping an icon (above) — a bare `|icon#user| "user"` spends
  301. its label on the symbol name.
  302. ### Charts & pie
  303. A chart fixes a shared scale from all children, then draws. Default size
  304. 360×220 (`width`/`height` set the whole box); radial/pie default 280 square.
  305. ```
  306. |chart| "Cycle time (s)" { categories: "15", "30", "50"; } [
  307. |bars| "1.8 kW" { data: 9, 15, 24; }
  308. |bars| "2.3 kW" { data: 7, 13, 20; }
  309. ]
  310. ```
  311. - Series: `|bars|`, `|line|`, `|area|` (`baseline: 40` floats the fill off
  312. axis zero), `|dots|` (+ per-node `|bubble| { at: x y; value: N; }`; `|slice|
  313. { value: N; }` in a pie). Label = legend entry (auto-shown at ≥ 2). Data —
  314. one of `data:` / `fn:`, never both: categorical `data: 9, 15, 24` (must match
  315. `categories:` count) · points `data: 0 225, 60 221` · dates `data:
  316. "2026-01-01" 18, …` · formula in `x` sampled over the domain (`samples:`
  317. count): `fn: (min(100, x * 2))`, a bare call `fn: cure(18)`, or per-band
  318. segments `fn: (0.1 + u^2), 5, (2 * u)` — one per `|band|`, each in its local
  319. clock `u` (0 → 1). `labels: "a", "b", …` per-datum text needs explicit `data:`.
  320. - **Colour is automatic and good**: series walk the palette (interleaved hues,
  321. red skipped) in the outlined look — soft fill + deep edge. Only override for
  322. meaning: `fill: --sky-soft`, `stroke: --teal`. Per-datum highlight on bars/
  323. dots: `fill: auto, auto, --red, auto`.
  324. - `curve: linear (default) | smooth (monotone, never overshoots) | step`;
  325. `marker: dot|circle|diamond` puts a mark at every datum; `tooltip:
  326. none|hover|auto|always`.
  327. - Axes only when you have something to say: `|axis#t| "Speed (mm/s)"
  328. { side: bottom; range: 0 133; unit: "%"; scale: log|time; step: 50; }`
  329. (`step: month` / `2 week` on a time axis; `ticks:` an explicit list). Bind a
  330. series with `axis: t`. `range: 50 1` reverses; `gridlines: none` or a colour.
  331. `format: decimal 1 | significant 3 | percent 0 | scientific 2 | engineering 1 |
  332. fraction 8 | year|month|day|hour|minute` on a scope, axis, series, or dimension —
  333. inherits; presentation only, never measurement.
  334. - Annotations in data space: `|band| "Hold" { range: 1.5 4; axis: t;
  335. fill: --amber; }` shades a region; a `|mark|` is a reference line (`at: V`),
  336. a labelled point (`at: x y`), or label-only (`marker: none`) — style its rule
  337. like a wire: `|mark| "SLO 250 ms" { at: 250; axis: ms; stroke: --amber-deep;
  338. stroke-style: dashed; color: --amber-ink; }`.
  339. - `direction: row` flips bars horizontal; `direction: radial` makes radar
  340. (lines close into polygons); `bars: grouped (default) | stacked | overlay`
  341. combines bar series. `|pie| { hole: 0.5 }` is a donut.
  342. ### Stack (one datum)
  343. `layout: stack` arranges nothing: every child's **origin** lands on the container's
  344. datum and `translate:` is the only offset. A symmetric primitive's origin is its
  345. centre, so shapes stack concentric; a `|sketch|`'s is its **pen origin**, so several
  346. sketches keep the frame they were drawn in — which flow throws away. Reach for it for
  347. artwork (a logo), a hand-placed figure, or a diagram tuned past what an arranger will do.
  348. ```
  349. { layout: stack; unit: mm; density: 10; padding: 25; cap = 0.9; bowl = 2.5; }
  350. |sketch#n| { draw: move(0, -3.4) arc(3.4, 3.4, 3.4) down(bowl) arc(cap, 180) up(bowl); mirror: y-axis; }
  351. |sketch#dots| { draw: move(11, -9) down(1) arc(cap, -180) up(1) arc(cap, -180) close(); pattern: grid(1, 3, 0, 3); }
  352. ```
  353. `|stack|` is the node form. Links go to the **router**, so arrows and labels behave as
  354. in a flow. `gap`/`direction`/`align`/`justify` are ignored (a root block refuses them).
  355. Nested boxes are unaffected: a `|box|` inside a stack still lays out its own content.
  356. **Units:** `unit: px` (the default) is 1 : 1; `unit: mm` plus a root `density:` (px
  357. per mm, default 4) draws in millimetres — `density: 10` renders a 24 mm mark 240 px
  358. wide. `layout: drawing` is this engine **plus** drafting — mates, dimensions,
  359. generated chrome. Same placement, so `|sketch|`, `mirror:` and `pattern:` work
  360. identically in both; only a drawing draws a fused mirror's centreline.
  361. ### Drawing (engineering)
  362. `layout: drawing` places every child's origin on a shared **datum** (no flow);
  363. links become dimensions/leaders; **measured values are computed from the
  364. geometry** — never type a number a dimension can read. No auto-create.
  365. ```
  366. { layout: drawing; }
  367. |rect#plate| { width: 120; height: 70; } [
  368. |hole#pin| { width: 10; translate: -35 20; pattern: grid(2, 1, 70, 0); }
  369. |hidden#bore| { draw: move(-20, -35) down(70); } // dashed interior geometry
  370. ]
  371. plate:left (-) plate:right { side: bottom; } // → 120
  372. plate:left (-) plate.pin { side: top; } // → 25
  373. plate.pin (o) // → 2× ⌀10
  374. plate.pin.2 <- "THRU" // leader to the 2nd pattern copy
  375. ```
  376. - **Anchors** are `id{.id}[.index][:point]`: `:center` (default), the four
  377. sides, the four corners vertical-word-first (`:top-right`), or an authored
  378. `:segment`/station. Pattern copies index `plate.pin.2`; `mirror:` copies are
  379. not addressable.
  380. - Ops: `(-)` linear (binary, chains share a row: `a (-) b (-) c`; a side or edge
  381. anchor sets the axis, two **point** anchors — a corner, a hole — read the
  382. *aligned* diagonal, so add `project: horizontal | vertical` to read one axis
  383. and stack it on a `side:`) · `(o)` round (unary: ⌀ for round features, R for named arcs) · `(<)`
  384. angle · leaders `<- "text"` (arrow) / `*- "text"` (dot on a face) / `>- "A"`
  385. (datum triangle) — or node-first to a placed annotation: `b1 -* housing:boss`
  386. (a `|balloon#b1| "1"`), `plate.pin <- bore` (a `|note#bore|`) · `a:left ||
  387. b:right { gap: 4 }` mates part faces (moves geometry, draws nothing; negative
  388. gap = inserted) and also **seats an annotation on a face** (`finish ||
  389. plate:top`, `gap:` along the normal, `translate:` the lateral slide).
  390. - **The pen** (`|sketch| { draw: … }`, and it works in any layout): calls run
  391. left-to-right — `move(x, y)` starts a subpath, `left/right/up/down(n)`,
  392. `line(dx, dy)`, `angle(deg, n)`, `curve(c1x, c1y, c2x, c2y, dx, dy)`,
  393. `circle(r)`, `fillet(r)` / `chamfer(c)` between two segments, `point()` (a
  394. station: records the current point, draws nothing — beside a fillet it is the
  395. sharp corner), `close()`. A second `move()` starts a subpath; fill is even-odd,
  396. so an inner one reads as a hole. `:name` glued to any call — `close():west`,
  397. `point():m1` included — names that segment/station for dimensioning
  398. (`body:neck (o)` → ⌀); built-in names (`:left`…) can't be authored; a duplicate
  399. errors. Every argument is an expression (bindings read bare).
  400. - **Coordinates bite**: the verbs are visual (`up` goes up), but `move`/`line`/
  401. `curve` take raw **y-down** numbers — `move(0, -14)` is 14 *above* the origin.
  402. - **Two arcs, and they are not interchangeable.** `arc(dx, dy, r)` is the *minor*
  403. arc to a relative point — `r > 0` sweeps clockwise, `r < 0` counter-clockwise,
  404. `|r|` ≥ half the chord. `arc(r, deg)` is a **tangent** arc: it continues the
  405. current heading and sweeps `deg` (positive = clockwise), updating the heading.
  406. **Every run, `line()`, `curve()`, `angle()` or arc leaves a heading; a bare
  407. `move()` leaves none** — so open a tangent chain with a run or the two-point
  408. form. Bearings are `up = 0`, clockwise (90 right, 180 down).
  409. - **`mirror:`** reflects the node's path *and its features* about an axis
  410. **through its origin**, then unions the copy — `y-axis` (left↔right), `x-axis`
  411. (top↔bottom), a bearing, or a list applied left to right, each reflecting the
  412. union so far (`y-axis, x-axis` = 4-fold). An **open** subpath is **fused**
  413. (draw half, get the whole — both ends must sit on the axis) and generates the
  414. axis `|centerline|` in a drawing; a **closed** one is **duplicated** (draw one
  415. ear, get both). The default `auto` reflects iff an ancestor does; `mirror:
  416. none` opts a node and its subtree out.
  417. - **`pattern:`** (any layout) — `grid(cols, rows, dx, dy)` where **the seed is
  418. copy one**, so `grid(1, 3, 0, 20)` gives three, not four; `radial(count, radius)`
  419. puts `count` copies *on* the circle about the node's position and draws the
  420. `|pitch-circle|`.
  421. - `revolve: x-axis` makes a turned part (centerline + shoulder lines auto);
  422. `|hole|` punches and centre-marks itself (`thread: 1.25` on it draws the ¾
  423. thread arc). Generated chrome (`|centerline|`, `|pitch-circle|`, `|breakline|`,
  424. `|shoulder|`, `|projection|`, `|threadline|`) is styled — or **removed** — by
  425. the cascade: `|sketch| |centerline| { stroke: none; fill: none }` takes its
  426. space back too. Each is also free to author by hand: `|centerline| { points:
  427. 0 -20, 0 20; }`.
  428. - Dims: `side:` picks the stacking edge, `tol: 0.1` / `tol: +0.2 -0.05` /
  429. `tol: h6` appends tolerance, labels follow (`pin (o) "H7"`) or replace
  430. (two-ended) the value; a dimension's `[ ]` carries annotation nodes
  431. (`plate:top (-) plate:bottom [ |datum| "C" ]`). **Scale is three settings**:
  432. `scale: 2` is the drafting ratio (a 2:1 view that still measures true),
  433. `unit:` the physical size of one drawing unit (`mm` default here, also
  434. `cm`/`m`/`in`/`px`), and root `density:` the pixels per mm (default 4) — the
  435. engine's px-per-unit is their product, never authored. Magnitude is `scale:`'s
  436. job: a 5 m beam on A4 is `scale: 0.02`. `density:` lives on the root; `unit:`
  437. and `scale:` on the drawing / stack scope (the root itself when it is one).
  438. - Sheets: the root stays flow; views are `|drawing|` children of a `|page|`:
  439. `|page| { sheet: a4; align: origin } [ |drawing#side| "Title" { scale: 2 } [ … ]
  440. side.a (-) side.b |title-block| { title: "…"; drawing-number: "…"; revision:
  441. "A"; sheet-number: "1/1"; date: "…"; author: "…"; } [ |image| { src: "logo.svg";
  442. cell: 3 3; width: 12; height: 12 } ] ]` (authored cells seat after the
  443. generated fields; dimensions sit in the view or on the page). Multi-view rows
  444. share axes with `align: origin`, and an unmarked `-` between anchors in
  445. **different views** (`side.screw:head - end.od:top`) is the projection
  446. construction line — the one legal cross-view link.
  447. - Deep machinery, a line each: `thread: neck 1.25` dresses an ISO thread on a
  448. revolved profile — a bare leader on that segment composes `M8×1.25`;
  449. `break: -40 40` cuts a long part's boring middle (the view compresses, dims
  450. still read the unbroken model). A section / detail is a marker plus a view:
  451. `|plane#a| "A" { at: 40 }` or `|magnifier#c| "C" { width: 12 }` on the
  452. source, a sibling `|drawing| { of: a }` as the view — its title (`A-A (1:1)`,
  453. `C (3:1)`) composes itself. GD&T: `|surface-finish| "Ra 1.6"`,
  454. `|feature-control| "position" { tol: 0.05; datums: A B; zone: diameter;
  455. material: maximum; modifiers: projected 10 }` (+ `|control|` rows for a
  456. composite frame; the ISO 1101 characteristic names validate), `|datum|` — seat
  457. on a face with `||` or carry in a dimension's `[ ]`; datum letters come from
  458. `>-` leaders (`body:seat >- "A"`).
  459. ### Floorplan (architectural)
  460. `layout: floorplan` is the drawing engine in an architect's vocabulary —
  461. same datum, `scale:`/`unit:`, anchors and dimensions. Build it in four passes:
  462. **walls → openings → fixtures → dimensions**. Sizes you type are drawing units;
  463. every *built-in* size is true physical mm converted through `unit:`.
  464. ```
  465. { layout: floorplan; unit: m; scale: 0.02 } // 1:50 — 80 px per metre
  466. |wall#outer| { // draw: is the CENTRELINE
  467. draw: move(0, 0) right(7.2):north down(4.8):east
  468. left(7.2):south close():west;
  469. } [ // openings ride the wall's [ ]
  470. |window| { on: north; at: 2.7; width: 1.6 }
  471. |door#entry| "D1" { on: south; at: 1.05; width: 0.95; swing: right }
  472. // 'south' runs leftward: 'at' counts from its EAST end, and the pen's left
  473. // is the outside — 'right' is what opens the door into the flat
  474. ]
  475. |partition#bathwall| { // ends ON the shell, never across an opening
  476. draw: move(4.9, 0) down(2.3):face right(2.3):side
  477. } [
  478. |door| { on: side; at: 0.15; width: 0.8 } // opens into the bathroom
  479. ]
  480. |rect#counter| { width: 0.6; height: 1.4; translate: 6.8 3.2;
  481. fill: --bg; stroke: --stroke-dark; stroke-width: 1 }
  482. |bed| { rotate: 90; translate: 1.15 1.05 } // head to the west wall
  483. |sofa| { symbol: two; rotate: 90; translate: 0.6 3.4 }
  484. |dining| { symbol: round; translate: 3.3 3.3 }
  485. |appliance| "F" { symbol: fridge; translate: 6.8 2.8 }
  486. |bath| { symbol: shower; translate: 6.6 0.6 }
  487. |bath| { symbol: toilet; rotate: 90; translate: 5.35 0.5 } // 0° backs WEST
  488. "STUDIO 27 m²" { translate: 2.2 2.2 } // room names are plain sheet text
  489. // Clear spans, face to face. 'face' runs south, so its 'out' face is the
  490. // living side's and its 'in' face the bathroom's — read them the other way
  491. // round and each dimension eats the partition.
  492. outer:west-in (-) bathwall:face-out { side: top } // → 4.75 — the living space
  493. bathwall:face-in (-) outer:east-in { side: top } // → 2.15 — the bathroom
  494. outer:west-in (-) outer:east-in { side: top } // → 7 — the shell, clear
  495. outer:north-in (-) outer:south-in { side: right } // → 4.6
  496. ```
  497. - **Walls.** `|wall|` is a `|sketch|` whose `draw:` traces the centreline;
  498. `thickness:` (200 mm default, inherits nearest-wins; authored per wall in
  499. **drawing units** — `thickness: 0.4` under `unit: m`) offsets it into the
  500. mitred, solid-filled **poché** outline that takes the paint. `|partition|`
  501. is the 100 mm interior define. `fill: --bg; stroke: --stroke-dark` is the
  502. hollow double-line look, `fill: hatch(45)` the section convention. Walls bend
  503. with `arc()`; `curve()` errors. Draw meeting walls as **separate nodes** —
  504. paint order merges them seamlessly.
  505. - **Openings.** A `|door|` / `|window|` must sit in its wall's `[ ]`, stationed
  506. `on:` a **straight named segment**, `at:` the near jamb's distance from that
  507. segment's start (mind the draw direction — a `left(...)` run measures from its
  508. east end). They clip the wall and generate their chrome: `hinge: start|end` ×
  509. `swing: left|right` (left of the pen's travel), `symbol: single | double |
  510. sliding` (a slider takes no `hinge:`/`swing:`). `translate:` on one is an error.
  511. - **Fixtures.** Place them against something and leave every door its swing: a
  512. fixture floating mid-room, a leaf sweeping a tub, or a body crossing a
  513. partition is what makes a plan read as noise. `rotate:` turns a piece to its
  514. wall — a `toilet` and a `sink` back **west** unturned, a `sofa` backs
  515. **north**, a `corner` sofa seats a **north-west** corner; add 90° per
  516. quarter-turn clockwise. The families: `|bed|` (queen·king·double·single) · `|sofa|`
  517. (three·two·one·corner·stool — `one` is the armchair, `stool` the ⌀350 bar
  518. seat) · `|dining|` (six·four·round — sized by its **tabletop**, ⌀1000 for
  519. `round`; the pull-back chairs extend the bbox) · `|bath|`
  520. (tub·shower·toilet·sink·double-sink — the last is one unit, two basins) ·
  521. `|appliance|` (stove·fridge·washer·dishwasher) ·
  522. `|stairs|` (`steps: N` ≥ 2 required; no `symbol:`). `width`/`height` are floors
  523. that **stretch** the body. Each fills `--bg`, so furniture masks the floor
  524. under it. Label seats: a fixture's hangs **below** the body — leave air
  525. there; an `|appliance|`'s centres **inside** it (`"F"` / `"DW"` / `"W/D"`);
  526. an opening's sits beside the gap; each turns upright.
  527. - **Everything else** is plain geometry: counters, islands, desks and coffee
  528. tables are `|rect|`s; a balcony deck, a north arrow or a scale bar is a
  529. `|sketch|`; room names and areas are sheet text placed with `translate:` (a
  530. two-line name over its area is a `|block| { layout: flow; direction: column }`).
  531. A casework `|rect|` takes the core `radius:` for a softened counter — mind
  532. that it is **sheet-space pixels**, not drawing units (at 1:50 and the default
  533. density, `radius: 4` is 50 mm).
  534. - **Dimensions** anchor on the wall's own named runs, which answer three ways:
  535. every named run derives its two **face anchors** — `-in` (the enclosed side
  536. on a closed run, the left of the pen's travel on an open one) and `-out` —
  537. and the bare `:segment` is the **centreline**, where a structural drawing
  538. measures. **Dimension inside faces, always**: a room reads its **clear**
  539. span and the overall the shell's clear interior — what a listing plan
  540. publishes. Never a centreline, and never a span that runs *through* a wall:
  541. take the face on the room's own side, so the room clears plus the partitions
  542. sum to the overall (`2.65 + 0.1 + 4.05 = 6.8`). Which face that is follows
  543. the run's draw direction, so check it — a partition drawn southward has its
  544. `-out` face to the west. A name of your own ending `-in`/`-out` on a wall
  545. errors. A named **edge**'s extension line springs
  546. from the end nearest the dimension line, so it leaves a corner and runs away
  547. from the plan. Mind the axis — an edge dimensions **across** itself, so a
  548. horizontal span names the two vertical runs. An id'd opening anchors at its
  549. **centre**, which makes a location chain (`outer:west-in (-) outer.entry (-)
  550. outer:east-in`) — a setting-out drawing's dimension, not a room's, so reach
  551. for it only when that is what the sheet is.
  552. - **The print look is a theme, never authoring**: render with `--theme
  553. blueprint` for white-on-cyanotype; a plan's default stays black-on-white.
  554. ### Schematic
  555. `layout: schematic` seats parts and lets the router draw square, junction-dotted
  556. wires onto pins. 3+-pin parts (and anything with `cell:`) are anchors on
  557. tracks; 1–2-pin parts and labels are satellites seated at the pin their wire
  558. touches. The sheet is on a grid — `gap` is the part pitch (column and row,
  559. default 100), and it is the one lever when a long value overhangs the column
  560. beside it, since no part's ink ever moves another part. **A schematic's
  561. `columns:` is the wrap count** (one integer, not a track list) and its `cell:
  562. col row` is ordinal — empty tracks collapse. `clearance` is 10 (past the
  563. `pin-pitch` 20 it errors). No auto-create — unknown bare ids error.
  564. ```
  565. { layout: schematic; |vcc::label| { symbol: power } [ "5V" ] }
  566. |component#u1| "AMS1117-3.3" [
  567. |pin#vin| { side: left; number: 3; }
  568. |space| { span: 2; } // empty rail slots — the datasheet's pin-group gap
  569. |pin#en| "EN/~SHDN" { side: left; number: 4; } // label = displayed name (id shows when absent)
  570. |pin#gnd| { side: bottom; number: 1; }
  571. |pin#vout| { side: right; number: 2; }
  572. ]
  573. |J#j1| "3V3 OUT" { pins: 4; rotate: 180; }
  574. |C#c1| "22u"
  575. |label#tach| "TACH"
  576. u1.vin - |vcc| // the power-flag capsule, defined above
  577. u1.vout - c1 - |gnd| // a chain PASSES THROUGH a 2-pin part: series circuit
  578. u1.vout - j1.p3 "3V3" // net name = the wire's label, set beside the trace
  579. j1.p1 -> "NSTDBY" // one-ended label wire; the marker sets the tag's shape
  580. u1.en - "EN" // a plain name is a RUN of trace, not a stop
  581. j1.p2 - tach; tach - j1.p4 // two wires to one declared label merge at its point
  582. ```
  583. - **Parts.** Discretes with generated pins: `|R| |C| |L| |D| |LED| |Q| |Y| |F|
  584. |FB| |SW| |BT| |V| |I| |M| |BZ| |TP|` (pins `p1 p2`, or `a k`, `b c e` / `g d
  585. s` by `symbol:` variant — `zener`, `npn`, `nfet`, `polarized`…); `|opamp|`
  586. (pins `out inp inn`, power hidden); `|J|` (`pins: N` — one left-facing
  587. column); `|component|` + `|pin|` for anything else; `|gnd|`, `|nc|`,
  588. `|junction|` built in. The id is the reference designator (`#R5` reads R5);
  589. anonymous parts auto-number (display only — give an id to wire it); `prefix:
  590. "IC"` on a define renames the family. `|region::group| { layout: schematic }`
  591. makes a captioned sub-sheet — tile several on a `|page|` grid.
  592. - **Pose.** `rotate:` is 90°-step: a satellite auto-poses to face its wire, and
  593. a forced turn also sets which way its chain grows (`|R| { rotate: 270 }` off
  594. a side pin stands the chain **up**); `mirror: x-axis | y-axis` flips a part
  595. about its own axis before the turn — on a `|J|`, `rotate: 180` moves pin 1 to
  596. the bottom, `mirror: y-axis` faces it right with pin 1 still on top; a
  597. transistor's collector swaps sides. Text stays upright, bar a net name, which
  598. reads along a vertical trace.
  599. - **Wires.** Writing a polarised pin mid-chain sets orientation (`q1.s - d1.k -
  600. |gnd|`). A 2-pin part between two placed pins is a **bridge** (`u2.en - r5 -
  601. u2.vin`). Naming a discrete's pin reserves it first, so `u6.fb - r16.p1`
  602. beside `u6.vout - r15 - r16.p1 - |gnd|` taps *between* the resistors. A name
  603. on a pin another statement wires rides that wire as its net label. `:side`
  604. on any terminal is an error.
  605. - **Labels.** `shape: plain (default, no outline) | left | right | both |
  606. round`; `symbol: gnd | earth | chassis | power | nc | antenna` (text beside
  607. it; symbol + text = power flag, define it once as above). A plain run's
  608. `width: N` lengthens the trace it names, `side:` picks its flank. The classic
  609. look (green wires, yellow bodies, beige sheet) is automatic.
  610. ## Making it beautiful
  611. The defaults are designed — a plain file already reads well. Beauty is mostly
  612. restraint plus a few deliberate moves:
  613. 1. **Colour by meaning.** One hue per subsystem / branch / state, in the
  614. wash + ink recipe. Two or three hues, not seven. Define the pairing once as a
  615. define or class and instantiate — never repeat paint per node.
  616. 2. **Name regions with `|group|` + its caption label** (`|group#edge| "Edge"
  617. { gap: 20; } [ … ]`). Groups organize; boxes state.
  618. 3. **Refined over heavy**: keep strokes thin (1.5–2), body text
  619. `normal`/`medium`; save bold and strong colour for titles, one hero node, a
  620. `|badge|`. One gradient per scene at most (`fill: gradient(--sky, --purple);
  621. stroke: none; color: white` on the hero).
  622. 4. **Let the engines work.** Don't hand-place what flow/grid/tree can lay out;
  623. reach for `pin`+`translate` only for free-form canvases (ER graphs) and
  624. overlays, `stack` for artwork. Force `:side` sparingly — reorder declarations
  625. first. Charts: accept the palette walk unless colour has meaning.
  626. 5. **Meaning in line style**: solid = sync/primary, `-->` dashed = return/
  627. cache/secondary, `~>` wavy = async/event. Encode it as classes
  628. (`.async { stroke: --amber-deep; }`) so the legend lives in one place.
  629. 6. **Air**: root `padding: 24–30`; group `gap` 20–28; don't shrink the default
  630. 36 scene gap without reason. `max-width` on prose-y labels (~160–200).
  631. 7. `hint:` on dense nodes, `href:` where a diagram lands in a doc, `|icon|`s for
  632. recognition. Set root `fill: --bg` only when a backdrop plate is wanted.
  633. ## When the compiler complains
  634. Errors carry did-you-mean suggestions — read them, they're usually exact. The
  635. ones whose fix is not in the message:
  636. | Symptom | Fix |
  637. |---|---|
  638. | `text content takes no '[ ]'` / `'pin' needs a box` / `'cell' places a grid child` | wrap the string in `\|block\|` |
  639. | `'routing' is a scope's strategy` | set `routing:` on the container, not the link |
  640. | link endpoint not found | paths never auto-create; declare it or fix the path (the error lists candidates) |
  641. | `impossible (a -> b): no legal route: …` | a **stray** — drawn as a slanted dashed line, a warning unless `--strict`. Widen `gap`, drop a forced `:side`, move the link into the group whose children it joins, or lower `clearance` (a schematic already sits at 10) |
  642. | `no bundled glyph for '你' …` | `--static` kept that run as `<text>`; fine in a browser, boxes in resvg |
  643. | a tangent `arc()` right after `move()` | no heading yet — open with a run or `arc(dx, dy, r)` |
  644. Warnings matter too (`--check --strict` before finishing): near-miss ids (`cta`
  645. vs `cat`), split label blocks, never-worn classes, strays.
README.md · README · 162 lines
  1. <p align="center">
  2. <a href="https://lini.rs"><img src="https://raw.githubusercontent.com/monfa-red/lini/main/assets/logo/lini.svg" alt="Lini" width="256"></a>
  3. </p>
  4. <p align="center"><strong>From mindmap to blueprint.</strong></p>
  5. <p align="center">One small language for every kind of figure — pretty by default, precise when it has to be.</p>
  6. <p align="center">
  7. <a href="https://crates.io/crates/lini"><img src="https://img.shields.io/crates/v/lini.svg" alt="crates.io"></a>
  8. <a href="https://docs.rs/lini"><img src="https://img.shields.io/docsrs/lini" alt="docs.rs"></a>
  9. <a href="https://github.com/monfa-red/lini/actions/workflows/ci.yml"><img src="https://github.com/monfa-red/lini/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  10. <a href="https://github.com/monfa-red/lini/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license: MIT"></a>
  11. </p>
  12. <h3 align="center"><a href="https://lini.rs">lini.rs</a> — the tour, the reference, the gallery, and the compiler in your browser</h3>
  13. <p align="center">
  14. <a href="https://lini.rs"><img src="https://raw.githubusercontent.com/monfa-red/lini/main/assets/hero.svg" alt="A colourful service map rendered by Lini" width="440"></a>
  15. </p>
  16. <p align="center"><em>Thirty-odd lines of Lini — <a href="https://github.com/monfa-red/lini/blob/main/samples/hero.lini"><code>samples/hero.lini</code></a>.</em></p>
  17. ---
  18. ## What it is
  19. A compiler: plain text in, clean themeable SVG out. You say where things go, and the parts you'd rather not do by hand — routing a wire through the gaps, measuring a dimension, picking a palette — are done for you.
  20. - **One grammar, every family.** Flowcharts, mindmaps, org charts, tables, ER schemas, sequences, charts, engineering drawings, floor plans, and circuit schematics are all layouts over the same nodes and links. Not ten tools with ten syntaxes — one language, so theming, baking, and diffing work identically in each.
  21. - **Themeable after export.** Every colour is a live CSS variable and a `light-dark()` pair, so one SVG follows the viewer's OS with no script and no re-render, and one line of host CSS recolours every diagram on a page.
  22. - **Fast and deterministic.** A typical figure compiles in about 2 ms, byte-identical every run, so SVGs diff cleanly in CI.
  23. - **No runtime.** A single native binary. No Node, no headless browser, nothing to stand up beside it.
  24. - **Agents can write it.** [`SKILL.md`](https://github.com/monfa-red/lini/blob/main/SKILL.md) is the whole language as a working brief, and the property schema is generated from the compiler's own ledger.
  25. ## Gallery
  26. <table>
  27. <tr>
  28. <td width="50%" align="center" valign="top">
  29. <sub><b>Charts</b></sub><br>
  30. <img width="100%" src="https://raw.githubusercontent.com/monfa-red/lini/main/assets/charts.svg" alt="Six charts: stacked bars, grouped bars, a step-and-line plot, a banded area, a radar, and a donut">
  31. </td>
  32. <td width="50%" align="center" valign="top">
  33. <sub><b>ER schemas</b></sub><br>
  34. <img width="100%" src="https://raw.githubusercontent.com/monfa-red/lini/main/assets/entity_hero.svg" alt="An e-commerce ER schema: six entity cards wired with crow's-foot cardinality">
  35. </td>
  36. </tr>
  37. <tr>
  38. <td width="50%" align="center" valign="top">
  39. <sub><b>Sequence diagrams</b></sub><br>
  40. <img width="100%" src="https://raw.githubusercontent.com/monfa-red/lini/main/assets/sequence.svg" alt="A sequence diagram of a checkout flow with activation bars, a loop frame, a self-message, and an async message">
  41. </td>
  42. <td width="50%" align="center" valign="top">
  43. <sub><b>Icons &amp; signs</b></sub><br>
  44. <img width="100%" src="https://raw.githubusercontent.com/monfa-red/lini/main/assets/icons.svg" alt="Built-in Phosphor icons in several treatments, and labelled signs wired into a flow">
  45. </td>
  46. </tr>
  47. <tr>
  48. <td width="50%" align="center" valign="top">
  49. <sub><b>Circuit schematics</b></sub><br>
  50. <img width="100%" src="https://raw.githubusercontent.com/monfa-red/lini/main/assets/schematic_hero.svg" alt="A circuit schematic on an ISO A4 sheet: six captioned regions, an STM32 and an RS-485 transceiver with numbered pins, discretes, net labels, connectors, and a title block">
  51. </td>
  52. <td width="50%" align="center" valign="top">
  53. <sub><b>Engineering drawings</b></sub><br>
  54. <img width="100%" src="https://raw.githubusercontent.com/monfa-red/lini/main/assets/drawing_sheet.svg" alt="An engineering drawing of a DIN 912 socket cap screw on an ISO sheet: two views sharing an axis, a thread callout, hidden lines, dimensions, and a title block">
  55. </td>
  56. </tr>
  57. <tr>
  58. <td width="50%" align="center" valign="top">
  59. <sub><b>Floor plans</b></sub><br>
  60. <img width="100%" src="https://raw.githubusercontent.com/monfa-red/lini/main/assets/floorplan.svg" alt="A one-bedroom condo floor plan: poché walls, doors with swing arcs, windows, true-size furniture, room labels, and clear-span dimensions">
  61. </td>
  62. <td width="50%" align="center" valign="top">
  63. <sub><b>Mindmaps &amp; trees</b></sub><br>
  64. <img width="100%" src="https://raw.githubusercontent.com/monfa-red/lini/main/assets/mindmap.svg" alt="A mindmap: a centred root with six colour-tinted branches on smooth curves">
  65. </td>
  66. </tr>
  67. </table>
  68. More, with their source, at [lini.rs/gallery](https://lini.rs/gallery/).
  69. ## Colour
  70. <p align="center">
  71. <img src="https://raw.githubusercontent.com/monfa-red/lini/main/assets/palette.png" alt="Lini's eleven hues in five tiers — wash, soft, base, deep, ink — in light mode" width="340">
  72. <img src="https://raw.githubusercontent.com/monfa-red/lini/main/assets/palette-dark.png" alt="The same palette in dark mode: the tiers flip, but ink stays the high-contrast tone" width="340">
  73. </p>
  74. <p align="center"><em>One file, both modes — <a href="https://github.com/monfa-red/lini/blob/main/samples/palette.lini"><code>samples/palette.lini</code></a>.</em></p>
  75. Eleven named hues — `red rose orange amber lime green teal sky blue purple gray` — each in five **job-named** tiers: `wash` for backgrounds, `soft`, the bare name, `deep` for strokes, `ink` for text. The names hold across the flip — `--teal-ink` is the high-contrast tone in *both* modes, where a `light`/`dark` name would invert — which is what lets one export serve both. OKLCH underneath, so every ramp is perceptually even, and `gradient(--rose, --sky)` blends any two at a flattering angle.
  76. ## Install
  77. ```bash
  78. cargo install lini
  79. ```
  80. ```bash
  81. lini diagram.lini -o diagram.svg # compile to SVG
  82. lini serve diagram.lini # live-reloading preview
  83. lini serve samples/ # browse and edit the bundled examples
  84. ```
  85. Six lines — a type define, a container, and two links Lini routes for you:
  86. ```
  87. { |svc::box| { fill: --teal-wash; stroke: --teal-ink } }
  88. |group| "Services" [ |svc#api| "API"; |svc#auth| "Auth" ]
  89. |svc#db| "Postgres"
  90. api -> db "read"
  91. auth -> db "write"
  92. ```
  93. `{ }` is style, `[ ]` is children, and naming two nodes draws an orthogonal path between them, clear of everything in the way. The rest of the grammar is the [tour](https://lini.rs/docs/tour/language.html).
  94. ## Use it in your project
  95. - **[mdbook-lini](https://github.com/monfa-red/mdbook-lini)** — ` ```lini ` fences in an mdBook, compiled to inline SVG at build time. On [crates.io](https://crates.io/crates/mdbook-lini).
  96. - **[rehype-lini](https://github.com/monfa-red/rehype-lini)** — the same fences anywhere [rehype](https://github.com/rehypejs/rehype) runs: Docusaurus, Next and MDX, or a bare `unified()` pipeline. A toggle reveals the source that drew each figure. On [npm](https://www.npmjs.com/package/rehype-lini): `npm install rehype-lini`.
  97. - **[astro-lini](https://github.com/monfa-red/astro-lini)** — the Astro integration: one line in `astro.config.mjs` and every fence in the site draws. On [npm](https://www.npmjs.com/package/astro-lini): `npm install astro-lini`.
  98. - **[remark-lini](https://github.com/monfa-red/remark-lini)** — the engine both of those run on, and the remark plugin for a pipeline that needs the figures drawn before a highlighter sees them. On [npm](https://www.npmjs.com/package/remark-lini-lang) as `remark-lini-lang`, since npm refuses the short name as one edit from `remark-lint`.
  99. - **[lini-wasm](https://www.npmjs.com/package/lini-wasm)** — the compiler itself, for JavaScript. One package, two builds, so it runs in Node, Bun, Deno, a bundler or a browser. This is what the integrations above ride on, and what to reach for to build one of your own.
  100. - **Editors** — search *Lini* in the extensions pane: a TextMate bundle on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=monfa-red.lini) and a tree-sitter extension in [Zed's registry](https://zed.dev/extensions?query=lini). Source for both under [`editors/`](https://github.com/monfa-red/lini/tree/main/editors). Their word lists are generated from the compiler's own tables, so a new property highlights the day it lands.
  101. - **As a library** — `lini` is a crate as well as a binary: [docs.rs/lini](https://docs.rs/lini).
  102. ### From the community
  103. Built and maintained by their own authors, on their own release schedules.
  104. - **[obsidian-lini-view](https://github.com/FoxMaint/obsidian-lini-view)** — the Obsidian plugin: a ` ```lini ` fence draws in the note itself, live in the editor, on `lini-wasm`.
  105. ## For agents
  106. - **[`SKILL.md`](https://github.com/monfa-red/lini/blob/main/SKILL.md)** — the language as a working brief: the write → compile → *look at the render* loop, every family, and the mistakes worth not making. Also served at [lini.rs/SKILL.md](https://lini.rs/SKILL.md).
  107. - **[`schema/lini.schema.json`](https://github.com/monfa-red/lini/blob/main/schema/lini.schema.json)** — every primitive, template, role, and property with its owner, value shape, resolved default, inheritance channel, and a compiled example. Generated from the same ledger the compiler reads, and CI fails on drift. [`schema/reference.md`](https://github.com/monfa-red/lini/blob/main/schema/reference.md) is the compact human mirror.
  108. - **`lini --json`** — diagnostics as JSON: stable codes, spans, and machine-applicable fixes.
  109. ## Go deeper
  110. - [The tour](https://lini.rs/docs/tour/language.html) — fourteen pages, start to finish.
  111. - [The reference](https://lini.rs/docs/reference/00-at-a-glance.html) — every property, split out of the spec.
  112. - [The gallery](https://lini.rs/gallery/) — finished figures, with the source that drew them.
  113. - [The playground](https://lini.rs/play/) — the compiler, compiled to wasm, in your browser.
  114. In this repo: [`SPEC.md`](https://github.com/monfa-red/lini/blob/main/SPEC.md) is the language contract, frozen for 1.x — syntax, property names, defaults, diagnostic codes, and the theming surface stay compatible. [`ROUTING.md`](https://github.com/monfa-red/lini/blob/main/ROUTING.md) is the routing contract. [`samples/`](https://github.com/monfa-red/lini/tree/main/samples) holds one file per feature area, and [`RELEASING.md`](https://github.com/monfa-red/lini/blob/main/RELEASING.md) says how the pieces ship together.
  115. ## Development
  116. ```bash
  117. cargo test # unit, snapshot, and routing-law suites
  118. cargo run -- serve samples/
  119. ```
  120. A linear pipeline, each stage independently testable: lex → parse → desugar → resolve → layout → route → render. `lini desugar` prints any file with its sugar lowered to primitives, so the engine's real input is always inspectable. Conventions are in [`AGENTS.md`](https://github.com/monfa-red/lini/blob/main/AGENTS.md).
  121. ## License
  122. MIT — see [LICENSE](https://github.com/monfa-red/lini/blob/main/LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.