@brunosouzas/design-system 0.3.0 → 0.3.2

package/README.md

@@ -25,7 +25,7 @@ The visual identity of [brunosouzas.com](https://brunosouzas.com): design tokens
 
 ## Status
 
-Early. The first change of the [roadmap](docs/roadmap.md) is implemented: the token source and its CSS, TypeScript and JSON exports, the motion components, and the circuit-breaker state machine as the first catalogue scene (16:9 and 4:5, Portuguese and English), with commands to render its stills and videos. The first variety scene, `publish-subscribe`, is implemented with independent message copies, Publish acceptance, two ACKs and a local invoice NACK. Its owner stills/video approval is pending; implementation is not visual approval. The illustration pieces (roadmap item 3), the metro and diagram pieces (item 6) and stackledger's map markers, zones and icons (AB#167, 0.3.0) are implemented: the static drawing library that covers, banners, diagrams and scenes share, with a command that builds a blog cover from a JSON spec. The published covers are not ported to it yet (item 5).
+Early. The first change of the [roadmap](docs/roadmap.md) is implemented: the token source and its CSS, TypeScript and JSON exports, the motion components, and the circuit-breaker state machine as the first catalogue scene (16:9 and 4:5, Portuguese and English), with commands to render its stills and videos. The first variety scene, `publish-subscribe`, is implemented with independent message copies, Publish acceptance, two ACKs and a local invoice NACK. Its owner stills/video approval is pending; implementation is not visual approval. The illustration pieces (roadmap item 3), the metro and diagram pieces (item 6) stackledger's map markers, zones and icons (AB#167, 0.3.0) and the body diagram pieces (AB#141, 0.3.2) are implemented: the static drawing library that covers, banners, diagrams and scenes share, with a command that builds a blog cover from a JSON spec. The published covers are not ported to it yet (item 5).
 
 ## What it is
 
@@ -131,11 +131,11 @@ The components take every colour and size from the tokens, and what is visible a
 - `toSvg(node)` writes a tree as SVG text; `toReact(node)` turns the same tree into React elements. Both describe the same elements, attributes and text, which the tests check.
 - `pose(node, { x, y, tilt, squash, hop, scale, shake, opacity })` animates any piece around its base point; a scene recomputes the numbers every frame.
 - Every colour parameter is a token path (`"color.healthy"`, `"illustration.accent"`), never a hex value, except the three data fills of the map pieces below. Each piece checks its parameters before drawing and names the first wrong one. Positions and points take any finite number, because a map has no edge; sizes stay within 10000. A drawing that would hold a non-finite number throws `<piece>: the drawing overflows`.
-- The 41 pieces, with their anchors, parameters and defaults, are listed in [design §4](openspec/changes/archive/2026-10-23-illustration-pieces/design.md) (the 26 cover pieces), in [design §3](openspec/changes/archive/2026-10-23-metro-and-diagram-pieces/design.md) of `metro-and-diagram-pieces` (the nine map and diagram pieces) and in [design §3, §5 and §6](openspec/changes/archive/2026-10-23-stackledger-map-and-link-pieces/design.md) of `stackledger-map-and-link-pieces` (the six markers, zones and icons); the rules are in [`openspec/specs/illustration-pieces/`](openspec/specs/illustration-pieces/spec.md). `npm run pieces:sheet -- --out <file.svg>` draws them all.
+- The 51 pieces, with their anchors, parameters and defaults, are listed in [design §4](openspec/changes/archive/2026-10-23-illustration-pieces/design.md) (the 26 cover pieces), in [design §3](openspec/changes/archive/2026-10-23-metro-and-diagram-pieces/design.md) of `metro-and-diagram-pieces` (the nine map and diagram pieces) and in [design §3, §5 and §6](openspec/changes/archive/2026-10-23-stackledger-map-and-link-pieces/design.md) of `stackledger-map-and-link-pieces` (the six markers, zones and icons) and in [design §3 to §5](openspec/changes/archive/2026-10-23-body-diagram-pieces/design.md) of `body-diagram-pieces` (the ten body diagram pieces); the rules are in [`openspec/specs/illustration-pieces/`](openspec/specs/illustration-pieces/spec.md). `npm run pieces:sheet -- --out <file.svg>` draws them all.
 
 ### Maps and diagrams
 
-Thirteen pieces draw a metro map and its page diagrams, for [stackledger](https://github.com/brunosouzas/stackledger) and any other map in this style: `lineBadge`, `stationMarker` (stop, interchange as a capsule, deprecated), `pipe`, `countBadge`, `nodeBlock`, `pillNode`, `hexNode` (normal, focus, placeholder), `messageArrow` (curved or straight, with a head and an optional label) `ledgerMark` (stackledger's mark; `surface: "dark"` lines it with a light rim), `renewalRing` (orange bands round a station), `suggestedHalo` (a dashed muted circle), `licenceMark` (a 10-unit disc, green when held, white to buy) and `zone` (the outline the caller gives, widened by a round 32-unit stroke at the surface's zone opacity, with an optional title). They paint what the caller lays out: positions, hulls, text measurement and truncation stay with the map engine.
+Thirteen pieces draw a metro map and its page diagrams, for [stackledger](https://github.com/brunosouzas/stackledger) and any other map in this style: `lineBadge`, `stationMarker` (stop, interchange as a capsule, deprecated), `pipe`, `countBadge`, `nodeBlock`, `pillNode`, `hexNode` (normal, focus, placeholder), `messageArrow` (curved, straight or through two `controls` points, with a head and an optional label; `kind` `reply`, `failure` or `failFast` dashes it and paints it as ADR 0003 says), `ledgerMark` (stackledger's mark; `surface: "dark"` lines it with a light rim), `renewalRing` (orange bands round a station), `suggestedHalo` (a dashed muted circle), `licenceMark` (a 10-unit disc, green when held, white to buy) and `zone` (the outline the caller gives, widened by a round 32-unit stroke at the surface's zone opacity, with an optional title). They paint what the caller lays out: positions, hulls, text measurement and truncation stay with the map engine.
 
 - A `placeholder` node may have a `subtitle` (drawn like a normal node's, all muted), and `lineBadge` may have no `text` (the pill alone, 30 wide by default).
 - The licence's disc is small, so it has its own room rule: `size` at least three outlines (9 at ink scale 1).
@@ -143,7 +143,8 @@ Thirteen pieces draw a metro map and its page diagrams, for [stackledger](https:
 - `surface: "light" | "dark"` picks the background they sit on (`surface.*` tokens); every map and diagram piece takes it except `pipe`; `ledgerMark` takes only `surface`. On dark the hard shadow takes `surface.dark.shadow` and the outline gets a light rim ([ADR 0003](docs/adr/0003-visual-language-and-colour-meaning.md), amendment of AB#157).
 - `inkScale` (0.25 to 8) thickens the outline, rim and shadow without changing the geometry, on `lineBadge`, `stationMarker`, `countBadge` and the three nodes; the map uses 1, the page diagrams 1.6. A shape's height (a marker's diameter) must be at least four outlines; a placeholder node, which draws no ink, is exempt.
 - A line's colour comes from the map's data, so `pipe.fill`, `lineBadge.fill` and `zone.fill` also accept `#RRGGBB`. Every other colour is a token path, and a cover spec rejects any hex.
-- The `map.*` tokens hold the measures (outline 3, shadow 3.5, line 12, casing 6, badge 20, node 46, ring 3, halo 1.5, licence 10, zone padding 32…), `surface.*.zoneOpacity` the zone's opacity (0.12, dark 0.22), and `site.*` the page palette, fonts and type scale of brunosouzas.com in light and dark.
+- `map.bendRadius` (32) is the radius of a bundle's centre line at a 45° or 90° bend; no piece reads it, the map engine draws the arcs (`pipe.d` takes `A`).
+- The `map.*` tokens hold the measures (outline 3, shadow 3.5, line 12, casing 6, badge 20, node 46, ring 3, halo 1.5, licence 10, zone padding 32, bend radius 32…), `surface.*.zoneOpacity` the zone's opacity (0.12, dark 0.22), and `site.*` the page palette, fonts and type scale of brunosouzas.com in light and dark.
 
 ```ts
 import { lineBadge, pipe, stationMarker, toSvg } from "@brunosouzas/design-system";
@@ -152,6 +153,15 @@ const stop = stationMarker({ cx: 120, cy: 40, surface: "dark" });
 const badge = lineBadge({ x: 250, y: 40, text: "SH", fill: "#7B3FE4", surface: "dark" });
 ```
 
+### Body diagrams
+
+Ten pieces draw what the blog's body diagrams need beyond the map pieces: `diagramBox` (a box or pill with a fill and centred lines), `decisionNode` (diamond), `storeNode` (cylinder), `queueNode` (box with two rails), `exchangeNode` (hexagon), `taggedContainer` (a frame with its name on a tab), `lifeline` (dashed, or sparse dots once nothing calls it), `phaseBand` (a pill across a sequence in its state's colour), `altFrame` (alt/else frame with a tag and condition per part) and `edgeLabel` (words next to an arrow, optionally on a backdrop). They take `surface` and, the stickers, `inkScale`, like the map pieces, and paint what the caller lays out.
+
+- The shapes take one to three centred lines (`text`), an optional `subtitle` and `textSize`. Without `fill` the face is the surface's panel; with a fill, every word is ink.
+- Backticks mark code: `` "adopts a `correlationId`" `` draws `correlationId` in the monospace stack, as a `tspan`. An odd number of backticks is drawn as is.
+- Widths the piece estimates (`tagWidth`, `conditionWidth`, a label's `width`) can be passed by a caller that measures its text.
+- A body diagram is 800 wide. Lay it out in 560 units and show it 800 wide: the pieces then come out at the sizes of the published diagrams (text about 18, outline about 4); only the hard shadow is shallower (5 instead of 8).
+
 ### A cover
 
 A cover is a JSON spec kept with its article, outside this repository: drafts are private, and only the pieces are public. `npm run cover -- <spec.json> --out <file.svg>` validates it, reports every problem with its JSON path, and writes an 800x420 SVG; the same spec always gives the same bytes. With `"format": "banner"` the same command writes a site banner instead (see below).
@@ -191,7 +201,7 @@ Add it to `src/pieces/library.ts` (or `src/pieces/metro.ts` for a map or diagram
 
 ### UI and link icons
 
-- `uiIcon({ name, x, y, size, colour })` draws one of seven glyphs of the sites' chrome in a 24-unit box and one token colour: `sun`, `moon`, `zoomIn`, `zoomOut`, `reset`, `calendar`, `download` (data in `UI_ICONS`).
+- `uiIcon({ name, x, y, size, colour })` draws one of seven glyphs of the sites' chrome in a 24-unit box and one token colour: `sun`, `moon`, `zoomIn`, `zoomOut`, `reset`, `calendar`, `download` (data in `UI_ICONS`). `colour: "currentColor"` makes the icon follow its element's text colour (a button that inverts on hover, say); it only works when the SVG is inline in the page, since an `<img>` does not inherit the page's colour, and a cover spec refuses it.
 - `linkIcon({ icon, x, y, size, surface })` draws a link sticker as brunosouzas.com draws its social icons (46-unit box, light or dark frame): `github`, `linkedin`, `email`, `website` (data in `LINK_ICONS`). The GitHub mark is from [Font Awesome](https://fontawesome.com/), licensed [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
 - Neither holds a link, a style, a script or a URL, so a consumer can write one with `toSvg` inside its own `<svg xmlns=…>` and ship it as a static file.
 

package/dist/src/pieces/cover.js

@@ -10,7 +10,7 @@
 import { tokens } from "../../tokens/generated/tokens.js";
 import { PIECE_NAMES, PIECES, rings } from "./library.js";
 import { el, g } from "./node.js";
-import { COLOUR_TOKENS, checkParams, isColourLiteral, MAX_SIZE, PATH_DATA } from "./params.js";
+import { COLOUR_TOKENS, CURRENT_COLOUR, checkParams, isColourLiteral, MAX_SIZE, PATH_DATA } from "./params.js";
 export const SAFE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const TOP_LEVEL = ["id", "title", "description", "format", "background", "rings", "pieces", "custom"];
 /** Cover (800x420, the default) or banner (1200x420, rounded corners): spec cover-cli, "Banner output". */
@@ -191,6 +191,12 @@ export const validateCoverSpec = (spec) => {
                 return void out.push({ path: `${at}.piece`, message: "rings belong to the cover's rings field" });
             const definition = PIECES[piece];
             const own = checkParams(definition.schema, params, at);
+            // A cover is a standalone image: currentColor (accepted by uiIcon for inline page icons) is refused.
+            for (const [name, spec] of Object.entries(definition.schema)) {
+                if (spec.kind === "color" && spec.currentColor && params[name] === CURRENT_COLOUR) {
+                    own.push({ path: `${at}.${name}`, message: "currentColor is for icons inline in a page; a cover uses a token path" });
+                }
+            }
             out.push(...own);
             // Limits between parameters are reported with the schema's problems, except on a parameter
             // already reported; a relation that cannot read a broken parameter reports nothing.

package/dist/src/pieces/diagram.d.ts

@@ -0,0 +1,128 @@
+import { type Ink, type SurfaceName } from "./ink.ts";
+export type ShapeParams = Ink & {
+    x: number;
+    y: number;
+    width: number;
+    height?: number;
+    text: string[];
+    subtitle?: string;
+    fill?: string;
+    textSize?: number;
+};
+export type DiagramBoxParams = ShapeParams & {
+    radius?: number;
+    shape?: "box" | "pill";
+};
+/** A box or a pill with a fill and centred lines: a body diagram's step, system or note. */
+export declare const diagramBox: import("./piece.ts").Piece<DiagramBoxParams>;
+/** A decision: a diamond in its bounds. */
+export declare const decisionNode: import("./piece.ts").Piece<Ink & {
+    x: number;
+    y: number;
+    width: number;
+    height?: number;
+    text: string[];
+    subtitle?: string;
+    fill?: string;
+    textSize?: number;
+} & {
+    height: number;
+}>;
+export type StoreNodeParams = ShapeParams & {
+    height: number;
+    ry?: number;
+};
+/** A store: a cylinder in its bounds, with the front of its lid. */
+export declare const storeNode: import("./piece.ts").Piece<StoreNodeParams>;
+/** A queue: a box with a rail 10 in from each side. */
+export declare const queueNode: import("./piece.ts").Piece<ShapeParams>;
+/** An exchange: a hexagon with its points 0.26 × height in, as the motion shape (src/brand/flow-shapes.ts). */
+export declare const exchangeNode: import("./piece.ts").Piece<ShapeParams>;
+export type TaggedContainerParams = Ink & {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    tag: string;
+    tagWidth?: number;
+    tagFill?: string;
+    fill?: string;
+};
+/** A container (a platform, a broker) with its name on a tab centred on the top edge. */
+export declare const taggedContainer: import("./piece.ts").Piece<TaggedContainerParams>;
+export type LifelineParams = {
+    x: number;
+    y1: number;
+    y2: number;
+    state?: "active" | "inactive";
+    width?: number;
+    surface?: SurfaceName;
+};
+/** A participant's lifeline: dashed while active, sparse dots once nothing calls it. */
+export declare const lifeline: import("./piece.ts").Piece<LifelineParams>;
+export type PhaseBandParams = Ink & {
+    x: number;
+    y: number;
+    width: number;
+    height?: number;
+    text: string;
+    fill: string;
+    textSize?: number;
+};
+/** A phase of a sequence: a pill across the diagram in its state's colour. */
+export declare const phaseBand: import("./piece.ts").Piece<PhaseBandParams>;
+type Head = {
+    tag: string;
+    condition?: string;
+    tagWidth?: number;
+    conditionWidth?: number;
+};
+export type AltFrameParams = Head & {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    sections?: (Head & {
+        y: number;
+    })[];
+    surface?: SurfaceName;
+};
+/** An alt/else frame: the frame, a dashed divider per section, and a tag (with its condition) per part. */
+export declare const altFrame: import("./piece.ts").Piece<AltFrameParams>;
+export type EdgeLabelParams = {
+    x: number;
+    y: number;
+    lines: string[];
+    anchor?: "start" | "middle" | "end";
+    backdrop?: boolean;
+    width?: number;
+    textSize?: number;
+    surface?: SurfaceName;
+};
+/** Words next to an arrow: lines down from the baseline (x, y), optionally on a backdrop that hides what is behind. */
+export declare const edgeLabel: import("./piece.ts").Piece<EdgeLabelParams>;
+/** The body diagram pieces, in catalogue order (design §3). */
+export declare const DIAGRAM_PIECES: {
+    readonly diagramBox: import("./piece.ts").Piece<DiagramBoxParams>;
+    readonly decisionNode: import("./piece.ts").Piece<Ink & {
+        x: number;
+        y: number;
+        width: number;
+        height?: number;
+        text: string[];
+        subtitle?: string;
+        fill?: string;
+        textSize?: number;
+    } & {
+        height: number;
+    }>;
+    readonly storeNode: import("./piece.ts").Piece<StoreNodeParams>;
+    readonly queueNode: import("./piece.ts").Piece<ShapeParams>;
+    readonly exchangeNode: import("./piece.ts").Piece<ShapeParams>;
+    readonly taggedContainer: import("./piece.ts").Piece<TaggedContainerParams>;
+    readonly lifeline: import("./piece.ts").Piece<LifelineParams>;
+    readonly phaseBand: import("./piece.ts").Piece<PhaseBandParams>;
+    readonly altFrame: import("./piece.ts").Piece<AltFrameParams>;
+    readonly edgeLabel: import("./piece.ts").Piece<EdgeLabelParams>;
+};
+export {};

package/dist/src/pieces/diagram.js

@@ -0,0 +1,198 @@
+// Body diagram pieces (spec illustration-pieces, change body-diagram-pieces,
+// design §3 and §4): the shapes, lines and labels of the blog's body diagrams
+// that the metro and diagram pieces lack. Like those, they paint what the caller
+// lays out; positions, text measurement and truncation stay with the caller.
+//
+// What can go wrong: every parameter is checked by its schema first; the limits
+// between parameters are checked in the order of design §3 and the first one is
+// thrown as a RangeError naming the parameter.
+import { tokens } from "../../tokens/generated/tokens.js";
+import { inkOf, inkSchema, limits, roomFor, sticker, surfaceParam } from "./ink.js";
+import { drawn, el, r2 } from "./node.js";
+import { col, colour, label, MAX_SIZE, pos, size } from "./params.js";
+import { definePiece } from "./piece.js";
+const ink = tokens.color.ink;
+const font = tokens.font.sans;
+const bold = tokens.font.weightBold;
+const M = tokens.map;
+const lines = (max) => ({ kind: "array", required: true, minItems: 1, maxItems: max, of: label() });
+const textSize = { kind: "number", min: 6, max: 48 };
+// ---------- words ----------
+/** Characters of a word for a width estimate: backticks do not count. */
+const characters = (value) => Array.from(value.replace(/`/g, "")).length;
+/** Backticks mark code (design §4): with an even number of them, each part between backticks becomes a tspan in
+ * the monospace stack; empty parts are dropped. With an odd number, the string is drawn as is. */
+const spans = (value) => {
+    const parts = value.split("`");
+    if (parts.length % 2 === 0)
+        return [value];
+    return parts.flatMap((part, i) => (part === "" ? [] : i % 2 === 1 ? [el("tspan", { "font-family": tokens.font.mono }, part)] : [part]));
+};
+// Every text sets its own anchor, size and weight, so a surrounding group (a cover's label style) does not leak in.
+const words = (x, y, value, attrs) => el("text", { x: r2(x), y: r2(y), "font-family": font, ...attrs }, ...spans(value));
+/** No fill: the surface's panel with its text; a fill: that token with ink words (ADR 0003). */
+const coloursOf = (fill, params) => {
+    const { s } = inkOf(params);
+    return fill === undefined ? { face: s.panel, text: s.text, sub: s.muted } : { face: colour(fill, "fill"), text: ink, sub: ink };
+};
+/** Centred lines (bold) and an optional subtitle (11, regular), centred on (cx, cy). */
+const centred = (cx, cy, text, subtitle, c, size_ = M.labelSize) => {
+    const step = size_ * 1.25;
+    const block = (text.length - 1) * step + (subtitle === undefined ? 0 : 15);
+    const first = cy + (4.5 * size_) / 13 - block / 2;
+    return [
+        ...text.map((line, i) => words(cx, first + i * step, line, { fill: c.text, "font-size": size_, "font-weight": bold, "text-anchor": "middle" })),
+        ...(subtitle === undefined ? [] : [words(cx, first + (text.length - 1) * step + 15, subtitle, { fill: c.sub, "font-size": 11, "font-weight": 400, "text-anchor": "middle" })]),
+    ];
+};
+/** Room on the smaller of width and height, naming the smaller one. */
+const roomOn = (width, height, params) => width < height ? roomFor("width", width, params) : roomFor("height", height, params);
+const polygon = (points) => (dx, dy, attrs) => el("polygon", { points: points.map(([px, py]) => `${r2(px + dx)},${r2(py + dy)}`).join(" "), ...attrs });
+const rect = (x, y, w, h, rx) => (dx, dy, attrs) => el("rect", { x: r2(x + dx), y: r2(y + dy), width: r2(w), height: r2(h), rx: r2(rx), ...attrs });
+const shapeSchema = (heightRequired) => ({
+    x: pos(),
+    y: pos(),
+    width: size(true),
+    height: size(heightRequired),
+    text: lines(3),
+    subtitle: label(false),
+    fill: col(),
+    textSize,
+    ...inkSchema,
+});
+/** A box or a pill with a fill and centred lines: a body diagram's step, system or note. */
+export const diagramBox = definePiece("diagramBox", { ...shapeSchema(false), radius: { kind: "number", min: 0, max: MAX_SIZE }, shape: { kind: "enum", values: ["box", "pill"] } }, (params) => {
+    const { x, y, width, height = M.nodeHeight, text, subtitle, fill, shape = "box" } = params;
+    const radius = shape === "pill" ? height / 2 : (params.radius ?? Math.min(M.nodeRadius, height / 2));
+    const c = coloursOf(fill, params);
+    return drawn(sticker(rect(x, y, width, height, radius), c.face, params), centred(x + width / 2, y + height / 2, text, subtitle, c, params.textSize));
+}, (params) => {
+    const height = params.height ?? M.nodeHeight;
+    return limits(roomOn(params.width, height, params), params.shape === "pill" && params.radius !== undefined && { path: "radius", message: "cannot be combined with shape pill" }, params.radius !== undefined && params.radius > height / 2 && { path: "radius", message: `must be at most half the height (${r2(height / 2)}), found ${r2(params.radius)}` });
+});
+/** A decision: a diamond in its bounds. */
+export const decisionNode = definePiece("decisionNode", shapeSchema(true), (params) => {
+    const { x, y, width: w, height: h, text, subtitle, fill } = params;
+    const c = coloursOf(fill, params);
+    const shape = polygon([[x + w / 2, y], [x + w, y + h / 2], [x + w / 2, y + h], [x, y + h / 2]]);
+    return drawn(sticker(shape, c.face, params), centred(x + w / 2, y + h / 2, text, subtitle, c, params.textSize));
+}, (params) => limits(roomOn(params.width, params.height, params)));
+/** A store: a cylinder in its bounds, with the front of its lid. */
+export const storeNode = definePiece("storeNode", { ...shapeSchema(true), ry: size() }, (params) => {
+    const { x, y, width: w, height: h, text, subtitle, fill, ry = 8 } = params;
+    const c = coloursOf(fill, params);
+    const { outline } = inkOf(params);
+    const rx = r2(w / 2);
+    const body = (dx, dy, attrs) => el("path", { d: `M${r2(x + dx)},${r2(y + ry + dy)} A${rx},${ry} 0 0 1 ${r2(x + w + dx)},${r2(y + ry + dy)} V${r2(y + h - ry + dy)} A${rx},${ry} 0 0 1 ${r2(x + dx)},${r2(y + h - ry + dy)} Z`, ...attrs });
+    const lid = el("path", { d: `M${r2(x)},${r2(y + ry)} A${rx},${ry} 0 0 0 ${r2(x + w)},${r2(y + ry)}`, fill: "none", stroke: ink, "stroke-width": r2(0.75 * outline) });
+    return drawn([...sticker(body, c.face, params), lid], centred(x + w / 2, y + (h + ry) / 2, text, subtitle, c, params.textSize));
+}, (params) => {
+    const ry = params.ry ?? 8;
+    return limits(roomOn(params.width, params.height, params), ry > params.height / 4 && { path: "ry", message: `must be at most a quarter of the height (${r2(params.height / 4)}), found ${r2(ry)}` });
+});
+const RAIL = 10;
+/** A queue: a box with a rail 10 in from each side. */
+export const queueNode = definePiece("queueNode", shapeSchema(false), (params) => {
+    const { x, y, width: w, height: h = M.nodeHeight, text, subtitle, fill } = params;
+    const c = coloursOf(fill, params);
+    const { outline } = inkOf(params);
+    const rails = el("path", { d: `M${r2(x + RAIL)},${r2(y)} V${r2(y + h)} M${r2(x + w - RAIL)},${r2(y)} V${r2(y + h)}`, fill: "none", stroke: ink, "stroke-width": r2(0.75 * outline) });
+    return drawn([...sticker(rect(x, y, w, h, tokens.radius.small), c.face, params), rails], centred(x + w / 2, y + h / 2, text, subtitle, c, params.textSize));
+}, (params) => {
+    const height = params.height ?? M.nodeHeight;
+    const least = Math.max(height, 2 * RAIL + 4 * inkOf(params).outline);
+    return limits(roomFor("height", height, params), params.width < least && { path: "width", message: `must be at least the height and leave room for the rails (${r2(least)}), found ${r2(params.width)}` });
+});
+/** An exchange: a hexagon with its points 0.26 × height in, as the motion shape (src/brand/flow-shapes.ts). */
+export const exchangeNode = definePiece("exchangeNode", shapeSchema(false), (params) => {
+    const { x, y, width: w, height: h = M.nodeHeight, text, subtitle, fill } = params;
+    const c = coloursOf(fill, params);
+    const k = 0.26 * h;
+    const shape = polygon([[x + k, y], [x + w - k, y], [x + w, y + h / 2], [x + w - k, y + h], [x + k, y + h], [x, y + h / 2]]);
+    return drawn(sticker(shape, c.face, params), centred(x + w / 2, y + h / 2, text, subtitle, c, params.textSize));
+}, (params) => {
+    const height = params.height ?? M.nodeHeight;
+    return limits(roomFor("height", height, params), params.width < height && { path: "width", message: `must be at least the height (${r2(height)}), found ${r2(params.width)}` });
+});
+// ---------- container ----------
+const TAB = 24;
+const tabWidth = (params) => params.tagWidth ?? 7.2 * characters(params.tag) + 24;
+/** A container (a platform, a broker) with its name on a tab centred on the top edge. */
+export const taggedContainer = definePiece("taggedContainer", { x: pos(), y: pos(), width: size(true), height: size(true), tag: label(), tagWidth: size(), tagFill: col(), fill: col(), ...inkSchema }, (params) => {
+    const { x, y, width, height, tag, tagFill = "color.transitional", fill } = params;
+    const tw = tabWidth(params);
+    const c = coloursOf(fill, params);
+    return drawn([...sticker(rect(x, y, width, height, M.nodeRadius), c.face, params), ...sticker(rect(x + 14, y - TAB / 2, tw, TAB, TAB / 2), colour(tagFill, "tagFill"), params)], [words(x + 14 + tw / 2, y + 4.5, tag, { fill: ink, "font-size": M.badgeTextSize, "font-weight": bold, "text-anchor": "middle" })]);
+}, (params) => {
+    const tw = tabWidth(params);
+    const need = 4 * inkOf(params).outline;
+    return limits(roomOn(params.width, params.height, params), tw < TAB && { path: "tagWidth", message: `must be at least the tab's height (${TAB}), found ${r2(tw)}` }, TAB < need && { path: "inkScale", message: `leaves no room for the tab's outline: the tab is ${TAB} high and needs ${r2(need)}` }, params.width < tw + 28 && { path: "width", message: `leaves no room for the tag: needs at least ${r2(tw + 28)}` });
+});
+/** A participant's lifeline: dashed while active, sparse dots once nothing calls it. */
+export const lifeline = definePiece("lifeline", { x: pos(), y1: pos(), y2: pos(), state: { kind: "enum", values: ["active", "inactive"] }, width: { kind: "number", min: 0, exclusiveMin: true, max: 12 }, surface: surfaceParam }, ({ x, y1, y2, state = "active", width = 1.75, surface = "light" }) => {
+    const active = state === "active";
+    // Width as given, like pipe's: a valid hairline must not round to zero.
+    return drawn([
+        el("line", { x1: r2(x), y1: r2(y1), x2: r2(x), y2: r2(y2), stroke: tokens.surface[surface].muted, "stroke-width": width, "stroke-dasharray": active ? "5 5" : "1 6", "stroke-linecap": active ? "butt" : "round" }),
+    ]);
+}, ({ y1, y2 }) => limits(y1 === y2 && { path: "y2", message: "must differ from y1" }));
+/** A phase of a sequence: a pill across the diagram in its state's colour. */
+export const phaseBand = definePiece("phaseBand", { x: pos(), y: pos(), width: size(true), height: size(), text: label(), fill: { kind: "color", required: true }, textSize, ...inkSchema }, (params) => {
+    const { x, y, width, height = 26, text, fill, textSize: size_ = M.labelSize } = params;
+    return drawn(sticker(rect(x, y, width, height, height / 2), colour(fill, "fill"), params), [
+        words(x + width / 2, y + height / 2 + (4.5 * size_) / 13, text, { fill: ink, "font-size": size_, "font-weight": bold, "text-anchor": "middle" }),
+    ]);
+}, (params) => {
+    const height = params.height ?? 26;
+    return limits(roomFor("height", height, params), params.width < height && { path: "width", message: `must be at least the height (${r2(height)}), found ${r2(params.width)}` });
+});
+/** An alt/else frame: the frame, a dashed divider per section, and a tag (with its condition) per part. */
+export const altFrame = definePiece("altFrame", {
+    x: pos(),
+    y: pos(),
+    width: size(true),
+    height: size(true),
+    tag: label(),
+    condition: label(false),
+    tagWidth: size(),
+    conditionWidth: size(),
+    sections: {
+        kind: "array",
+        maxItems: 10,
+        of: { kind: "object", fields: { y: pos(), tag: label(), condition: label(false), tagWidth: size(), conditionWidth: size() } },
+    },
+    surface: surfaceParam,
+}, ({ x, y, width, height, sections = [], surface = "light", ...first }) => {
+    const s = tokens.surface[surface];
+    const head = (top, { tag, condition, tagWidth, conditionWidth }) => {
+        const tw = tagWidth ?? 6.4 * characters(tag) + 14;
+        const body = [el("rect", { x: r2(x + 7), y: r2(top + 6), width: r2(tw), height: 17, rx: 4, fill: s.text, stroke: "none" })];
+        const text = [words(x + 7 + tw / 2, top + 18.5, tag, { fill: s.panel, "font-size": 10, "font-weight": tokens.font.weightHeavy, "text-anchor": "middle" })];
+        if (condition !== undefined) {
+            body.push(el("rect", { x: r2(x + 7 + tw + 2), y: r2(top + 7.5), width: r2(conditionWidth ?? 6.2 * characters(condition) + 8), height: 14, rx: 3, fill: s.background, stroke: "none" }));
+            text.push(words(x + 7 + tw + 6, top + 18.5, condition, { fill: s.text, "font-size": 11, "font-weight": bold, "text-anchor": "start" }));
+        }
+        return { body, text };
+    };
+    const heads = [head(y, first), ...sections.map((section) => head(section.y, section))];
+    return drawn([
+        el("rect", { x: r2(x), y: r2(y), width: r2(width), height: r2(height), rx: 7, fill: "none", stroke: s.text, "stroke-width": 1.75 }),
+        ...sections.map((section) => el("line", { x1: r2(x), y1: r2(section.y), x2: r2(x + width), y2: r2(section.y), stroke: s.text, "stroke-width": 1.4, "stroke-dasharray": "4 4" })),
+        ...heads.flatMap((part) => part.body),
+    ], heads.flatMap((part) => part.text));
+}, ({ y, height, sections = [] }) => limits(...sections.map((section, i) => (section.y <= y || section.y >= y + height) && { path: `sections[${i}].y`, message: "must lie inside the frame" })));
+/** Words next to an arrow: lines down from the baseline (x, y), optionally on a backdrop that hides what is behind. */
+export const edgeLabel = definePiece("edgeLabel", { x: pos(), y: pos(), lines: lines(4), anchor: { kind: "enum", values: ["start", "middle", "end"] }, backdrop: { kind: "boolean" }, width: size(), textSize, surface: surfaceParam }, ({ x, y, lines: rows, anchor = "middle", backdrop = false, width, textSize: size_ = 11, surface = "light" }) => {
+    const s = tokens.surface[surface];
+    const k = size_ / 11;
+    const body = backdrop
+        ? rows.map((row, i) => {
+            const w = width ?? (6.2 * characters(row) + 8) * k;
+            const left = anchor === "start" ? x - 4 * k : anchor === "end" ? x - w + 4 * k : x - w / 2;
+            return el("rect", { x: r2(left), y: r2(y + (i * 13 - 10) * k), width: r2(w), height: r2(14 * k), rx: 3, fill: s.background, stroke: "none" });
+        })
+        : [];
+    return drawn(body, rows.map((row, i) => words(x, y + i * 13 * k, row, { fill: s.text, "font-size": size_, "font-weight": bold, "text-anchor": anchor })));
+});
+/** The body diagram pieces, in catalogue order (design §3). */
+export const DIAGRAM_PIECES = { diagramBox, decisionNode, storeNode, queueNode, exchangeNode, taggedContainer, lifeline, phaseBand, altFrame, edgeLabel };

package/dist/src/pieces/ink.d.ts

@@ -0,0 +1,48 @@
+import { type Attrs, type SvgNode } from "./node.ts";
+import type { ParamSpec, Problem, Schema } from "./params.ts";
+export type Point = [number, number];
+export declare const SURFACES: readonly ["light", "dark"];
+export type SurfaceName = (typeof SURFACES)[number];
+export type Ink = {
+    surface?: SurfaceName;
+    inkScale?: number;
+};
+export declare const surfaceParam: ParamSpec;
+export declare const inkScaleParam: ParamSpec;
+export declare const inkSchema: Schema;
+/** Collects the limits between parameters (piece.ts, `relations`). */
+export declare const limits: (...checks: (Problem | false)[]) => Problem[];
+/** The surface's colours and the ink measures at a scale. */
+export declare const inkOf: ({ surface, inkScale }: Ink) => {
+    s: {
+        readonly background: "#14215A";
+        readonly grid: "#1C2D74";
+        readonly muted: "#8F9BD0";
+        readonly panel: "#1C2D74";
+        readonly rim: "#EEF2FF";
+        readonly rimWidth: 1;
+        readonly shadow: "#4C5CB8";
+        readonly text: "#EEF2FF";
+        readonly zoneOpacity: 0.22;
+    } | {
+        readonly background: "#EEF2FF";
+        readonly grid: "#E0E7FB";
+        readonly muted: "#5B6694";
+        readonly panel: "#FFFFFF";
+        readonly rim: "#EEF2FF";
+        readonly rimWidth: 0;
+        readonly shadow: "#0A1033";
+        readonly text: "#0A1033";
+        readonly zoneOpacity: 0.12;
+    };
+    outline: number;
+    rim: number;
+    offset: number;
+};
+/** Outlined shapes need room for their ink: smallest dimension ≥ 4 × outline. */
+export declare const roomFor: (name: string, smallest: number, inkParams: Ink) => Problem | false;
+export declare const atLeast: (name: string, value: number, least: number, what: string) => Problem | false;
+export type Shape = (dx: number, dy: number, attrs: Attrs) => SvgNode;
+/** The ink sticker (metro-and-diagram-pieces design §3): shadow copy, rim on dark, then the face. */
+export declare const sticker: (shape: Shape, face: string, inkParams: Ink) => SvgNode[];
+export declare const words: (x: number, y: number, value: string, attrs: Attrs) => SvgNode;

package/dist/src/pieces/ink.js

@@ -0,0 +1,38 @@
+// Ink helpers shared by the metro, diagram and body diagram pieces (moved from
+// metro.ts unchanged; change body-diagram-pieces, design §8). Internal: the
+// package does not export this module.
+import { tokens } from "../../tokens/generated/tokens.js";
+import { el, r2 } from "./node.js";
+export const SURFACES = ["light", "dark"];
+const ink = tokens.color.ink;
+const font = tokens.font.sans;
+const M = tokens.map;
+export const surfaceParam = { kind: "enum", values: SURFACES };
+export const inkScaleParam = { kind: "number", min: 0.25, max: 8 };
+export const inkSchema = { surface: surfaceParam, inkScale: inkScaleParam };
+/** Collects the limits between parameters (piece.ts, `relations`). */
+export const limits = (...checks) => checks.filter((check) => check !== false);
+/** The surface's colours and the ink measures at a scale. */
+export const inkOf = ({ surface = "light", inkScale = 1 }) => {
+    const s = tokens.surface[surface];
+    return { s, outline: M.outline * inkScale, rim: s.rimWidth * inkScale, offset: M.shadow * inkScale };
+};
+/** Outlined shapes need room for their ink: smallest dimension ≥ 4 × outline. */
+export const roomFor = (name, smallest, inkParams) => {
+    const need = 4 * inkOf(inkParams).outline;
+    return smallest < need && { path: name, message: `leaves no room for the outline: needs at least ${r2(need)} at this ink scale` };
+};
+export const atLeast = (name, value, least, what) => value < least && { path: name, message: `must be at least ${what} (${r2(least)}), found ${r2(value)}` };
+/** The ink sticker (metro-and-diagram-pieces design §3): shadow copy, rim on dark, then the face. */
+export const sticker = (shape, face, inkParams) => {
+    const { s, outline, rim, offset } = inkOf(inkParams);
+    const wide = r2(outline + 2 * rim);
+    return [
+        // Joins are set here, so a sticker draws the same inside any group.
+        shape(offset, offset, { fill: s.shadow, stroke: s.shadow, "stroke-width": wide, "stroke-linejoin": "round" }),
+        ...(s.rimWidth > 0 ? [shape(0, 0, { fill: s.rim, stroke: s.rim, "stroke-width": wide, "stroke-linejoin": "round" })] : []),
+        shape(0, 0, { fill: face, stroke: ink, "stroke-width": r2(outline), "stroke-linejoin": "round" }),
+    ];
+};
+// Every text sets its own anchor, size and weight, so a surrounding group (a cover's label style) does not leak in.
+export const words = (x, y, value, attrs) => el("text", { x: r2(x), y: r2(y), "font-family": font, ...attrs }, value);

package/dist/src/pieces/library.d.ts

@@ -1,4 +1,5 @@
 export * from "./metro.ts";
+export * from "./diagram.ts";
 export * from "./ui-icons.ts";
 export * from "./link-icons.ts";
 type Point = [number, number];
@@ -275,6 +276,27 @@ export declare const PIECES: {
     readonly suggestedHalo: import("./piece.ts").Piece<import("./metro.ts").SuggestedHaloParams>;
     readonly licenceMark: import("./piece.ts").Piece<import("./metro.ts").LicenceMarkParams>;
     readonly zone: import("./piece.ts").Piece<import("./metro.ts").ZoneParams>;
+    readonly diagramBox: import("./piece.ts").Piece<import("./diagram.ts").DiagramBoxParams>;
+    readonly decisionNode: import("./piece.ts").Piece<import("./ink.ts").Ink & {
+        x: number;
+        y: number;
+        width: number;
+        height?: number;
+        text: string[];
+        subtitle?: string;
+        fill?: string;
+        textSize?: number;
+    } & {
+        height: number;
+    }>;
+    readonly storeNode: import("./piece.ts").Piece<import("./diagram.ts").StoreNodeParams>;
+    readonly queueNode: import("./piece.ts").Piece<import("./diagram.ts").ShapeParams>;
+    readonly exchangeNode: import("./piece.ts").Piece<import("./diagram.ts").ShapeParams>;
+    readonly taggedContainer: import("./piece.ts").Piece<import("./diagram.ts").TaggedContainerParams>;
+    readonly lifeline: import("./piece.ts").Piece<import("./diagram.ts").LifelineParams>;
+    readonly phaseBand: import("./piece.ts").Piece<import("./diagram.ts").PhaseBandParams>;
+    readonly altFrame: import("./piece.ts").Piece<import("./diagram.ts").AltFrameParams>;
+    readonly edgeLabel: import("./piece.ts").Piece<import("./diagram.ts").EdgeLabelParams>;
     readonly pill: import("./piece.ts").Piece<PillParams>;
     readonly rings: import("./piece.ts").Piece<RingsParams>;
     readonly sheet: import("./piece.ts").Piece<SheetParams>;

package/dist/src/pieces/library.js

@@ -12,9 +12,11 @@ import { drawn, el, g, r2, shadowed } from "./node.js";
 import { col, colour, count, label, MAX_SIZE, PATH_DATA, pos, size } from "./params.js";
 import { definePiece } from "./piece.js";
 import { METRO_PIECES } from "./metro.js";
+import { DIAGRAM_PIECES } from "./diagram.js";
 import { uiIcon } from "./ui-icons.js";
 import { linkIcon } from "./link-icons.js";
 export * from "./metro.js";
+export * from "./diagram.js";
 export * from "./ui-icons.js";
 export * from "./link-icons.js";
 const ink = tokens.color.ink;
@@ -381,5 +383,6 @@ export const PIECES = {
     ...METRO_PIECES,
     uiIcon,
     linkIcon,
+    ...DIAGRAM_PIECES,
 };
 export const PIECE_NAMES = Object.keys(PIECES);

package/dist/src/pieces/metro.d.ts

@@ -1,10 +1,5 @@
-type Point = [number, number];
-export declare const SURFACES: readonly ["light", "dark"];
-export type SurfaceName = (typeof SURFACES)[number];
-export type Ink = {
-    surface?: SurfaceName;
-    inkScale?: number;
-};
+import { type Ink, type Point, type SurfaceName } from "./ink.ts";
+export { SURFACES, type Ink, type SurfaceName } from "./ink.ts";
 export type LineBadgeParams = Ink & {
     x: number;
     y: number;
@@ -60,16 +55,20 @@ export declare const nodeBlock: import("./piece.ts").Piece<NodeBlockParams>;
 export declare const pillNode: import("./piece.ts").Piece<NodeParams>;
 /** A diagram hexagon (an agent). */
 export declare const hexNode: import("./piece.ts").Piece<NodeParams>;
+export type ArrowKind = "message" | "reply" | "failure" | "failFast";
 export type MessageArrowParams = {
     from: Point;
     to: Point;
     curve?: "bezier" | "straight";
+    controls?: [Point, Point];
     head?: boolean;
     label?: string;
     width?: number;
+    kind?: ArrowKind;
     surface?: SurfaceName;
 };
-/** An edge with a head at `to`: curved (leaves and enters horizontally) or straight, with an optional label. */
+/** An edge with a head at `to`: curved (leaves and enters horizontally), straight, or through the caller's two
+ * control points, with an optional label. `kind` paints a reply, a failure or a fail-fast path (card 141). */
 export declare const messageArrow: import("./piece.ts").Piece<MessageArrowParams>;
 export type LedgerMarkParams = {
     x: number;
@@ -129,4 +128,3 @@ export declare const METRO_PIECES: {
     readonly licenceMark: import("./piece.ts").Piece<LicenceMarkParams>;
     readonly zone: import("./piece.ts").Piece<ZoneParams>;
 };
-export {};

package/dist/src/pieces/metro.js

@@ -9,46 +9,18 @@
 // cross-parameter limits (room for the outline, width against height, arrow
 // length) are checked here and thrown as a RangeError naming the parameter.
 import { tokens } from "../../tokens/generated/tokens.js";
+import { atLeast, inkOf, inkSchema, limits, roomFor, sticker, surfaceParam, words } from "./ink.js";
 import { drawn, el, g, r2 } from "./node.js";
 import { col, colour, label, MAX_SIZE, PATH_DATA, paint, pos, size } from "./params.js";
 import { definePiece } from "./piece.js";
-export const SURFACES = ["light", "dark"];
+export { SURFACES } from "./ink.js";
 const ink = tokens.color.ink;
 const white = tokens.color.white;
 const font = tokens.font.sans;
 const bold = tokens.font.weightBold;
 const M = tokens.map;
-const surfaceParam = { kind: "enum", values: SURFACES };
-const inkScaleParam = { kind: "number", min: 0.25, max: 8 };
 const dataColour = (required = true) => ({ kind: "dataColor", required });
 const point = (required = true) => ({ kind: "point", required });
-const inkSchema = { surface: surfaceParam, inkScale: inkScaleParam };
-/** Collects the limits between parameters (piece.ts, `relations`). */
-const limits = (...checks) => checks.filter((check) => check !== false);
-/** The surface's colours and the ink measures at a scale. */
-const inkOf = ({ surface = "light", inkScale = 1 }) => {
-    const s = tokens.surface[surface];
-    return { s, outline: M.outline * inkScale, rim: s.rimWidth * inkScale, offset: M.shadow * inkScale };
-};
-/** Outlined shapes need room for their ink: smallest dimension ≥ 4 × outline. */
-const roomFor = (name, smallest, inkParams) => {
-    const need = 4 * inkOf(inkParams).outline;
-    return smallest < need && { path: name, message: `leaves no room for the outline: needs at least ${r2(need)} at this ink scale` };
-};
-const atLeast = (name, value, least, what) => value < least && { path: name, message: `must be at least ${what} (${r2(least)}), found ${r2(value)}` };
-/** The ink sticker (design §3): shadow copy, rim on dark, then the face. */
-const sticker = (shape, face, inkParams) => {
-    const { s, outline, rim, offset } = inkOf(inkParams);
-    const wide = r2(outline + 2 * rim);
-    return [
-        // Joins are set here, so a sticker draws the same inside any group.
-        shape(offset, offset, { fill: s.shadow, stroke: s.shadow, "stroke-width": wide, "stroke-linejoin": "round" }),
-        ...(s.rimWidth > 0 ? [shape(0, 0, { fill: s.rim, stroke: s.rim, "stroke-width": wide, "stroke-linejoin": "round" })] : []),
-        shape(0, 0, { fill: face, stroke: ink, "stroke-width": r2(outline), "stroke-linejoin": "round" }),
-    ];
-};
-// Every text sets its own anchor, size and weight, so a surrounding group (a cover's label style) does not leak in.
-const words = (x, y, value, attrs) => el("text", { x: r2(x), y: r2(y), "font-family": font, ...attrs }, value);
 const pill = (x, y, w, h) => (dx, dy, attrs) => el("rect", { x: r2(x + dx), y: r2(y + dy), width: r2(w), height: r2(h), rx: r2(h / 2), ...attrs });
 // Without a text, the default width is the one-character width (card 167).
 const badgeWidth = ({ width, text }) => width ?? Math.max(30, 7.6 * (text === undefined ? 1 : Array.from(text).length) + 18);
@@ -167,32 +139,47 @@ export const nodeBlock = definePiece("nodeBlock", { ...nodeSchema, radius: { kin
 export const pillNode = definePiece("pillNode", nodeSchema, (p) => drawNode("pill", p), nodeLimits("pill"));
 /** A diagram hexagon (an agent). */
 export const hexNode = definePiece("hexNode", nodeSchema, (p) => drawNode("hex", p), nodeLimits("hex"));
-/** An edge with a head at `to`: curved (leaves and enters horizontally) or straight, with an optional label. */
+/** An edge with a head at `to`: curved (leaves and enters horizontally), straight, or through the caller's two
+ * control points, with an optional label. `kind` paints a reply, a failure or a fail-fast path (card 141). */
 export const messageArrow = definePiece("messageArrow", {
     from: point(),
     to: point(),
     curve: { kind: "enum", values: ["bezier", "straight"] },
+    controls: { kind: "array", minItems: 2, maxItems: 2, of: point() },
     head: { kind: "boolean" },
     label: label(false),
     width: { kind: "number", min: 1, max: 12 },
+    kind: { kind: "enum", values: ["message", "reply", "failure", "failFast"] },
     surface: surfaceParam,
-}, ({ from, to, curve = "bezier", head = true, label: text, width = M.edgeWidth, surface = "light" }) => {
+}, ({ from, to, curve = "bezier", controls, head = true, label: text, width = M.edgeWidth, kind = "message", surface = "light" }) => {
     const s = tokens.surface[surface];
+    const paint_ = kind === "failure" ? tokens.color.failure : kind === "failFast" ? tokens.color.failFast : s.text;
     const length = 5 * width;
     const distance = Math.hypot(to[0] - from[0], to[1] - from[1]);
     const dx = to[0] - from[0];
     // A curve whose ends are almost above each other has no horizontal entry: draw it straight.
-    const bent = curve === "bezier" && Math.abs(dx) > 2 * length;
-    const direction = bent ? [Math.sign(dx), 0] : [dx / distance, (to[1] - from[1]) / distance];
+    const bent = controls === undefined && curve === "bezier" && Math.abs(dx) > 2 * length;
+    // With controls, the head points from the last of c2, c1, from that differs from `to` (design §5).
+    const towards = (q) => {
+        const l = Math.hypot(to[0] - q[0], to[1] - q[1]);
+        return [(to[0] - q[0]) / l, (to[1] - q[1]) / l];
+    };
+    const tail = controls && [controls[1], controls[0], from].find((q) => q[0] !== to[0] || q[1] !== to[1]);
+    const direction = tail !== undefined ? towards(tail) : bent ? [Math.sign(dx), 0] : [dx / distance, (to[1] - from[1]) / distance];
     const end = head ? [to[0] - direction[0] * length, to[1] - direction[1] * length] : to;
     const mx = (from[0] + to[0]) / 2;
     const at = (p) => `${r2(p[0])},${r2(p[1])}`;
-    const d = bent ? `M${at(from)} C${r2(mx)},${r2(from[1])} ${r2(mx)},${r2(to[1])} ${at(end)}` : `M${at(from)} L${at(end)}`;
-    const body = [el("path", { d, fill: "none", stroke: s.text, "stroke-width": r2(width), "stroke-linecap": "round" })];
+    const d = controls
+        ? `M${at(from)} C${at(controls[0])} ${at(controls[1])} ${at(end)}`
+        : bent
+            ? `M${at(from)} C${r2(mx)},${r2(from[1])} ${r2(mx)},${r2(to[1])} ${at(end)}`
+            : `M${at(from)} L${at(end)}`;
+    const dash = kind === "message" ? {} : { "stroke-dasharray": `${r2(2.4 * width)} ${r2(3.2 * width)}` };
+    const body = [el("path", { d, fill: "none", stroke: paint_, "stroke-width": r2(width), "stroke-linecap": "round", ...dash })];
     if (head) {
         const normal = [-direction[1] * 2 * width, direction[0] * 2 * width];
         const points = [to, [end[0] + normal[0], end[1] + normal[1]], [end[0] - normal[0], end[1] - normal[1]]];
-        body.push(el("polygon", { points: points.map(at).join(" "), fill: s.text, stroke: s.text, "stroke-width": 1, "stroke-linejoin": "round" }));
+        body.push(el("polygon", { points: points.map(at).join(" "), fill: paint_, stroke: paint_, "stroke-width": 1, "stroke-linejoin": "round" }));
     }
     const words_ = [];
     if (text !== undefined) {
@@ -202,9 +189,9 @@ export const messageArrow = definePiece("messageArrow", {
         words_.push(words(middle[0], middle[1] + 4, text, { fill: s.text, "font-size": 11, "font-weight": 400, "text-anchor": "middle" }));
     }
     return drawn(body, words_);
-}, ({ from, to, head = true, width = M.edgeWidth }) => {
+}, ({ from, to, head = true, width = M.edgeWidth, controls, curve }) => {
     const distance = Math.hypot(to[0] - from[0], to[1] - from[1]);
-    return limits(distance === 0 && { path: "to", message: "must differ from from" }, distance > 0 && head && distance < 10 * width && { path: "to", message: `is too close to from for the head: needs at least ${r2(10 * width)}, found ${r2(distance)}` });
+    return limits(distance === 0 && { path: "to", message: "must differ from from" }, distance > 0 && head && distance < 10 * width && { path: "to", message: `is too close to from for the head: needs at least ${r2(10 * width)}, found ${r2(distance)}` }, controls !== undefined && curve !== undefined && { path: "controls", message: "cannot be combined with curve" });
 });
 /** stackledger's mark (favicon, header): an ink square with a bent line and two stations, 32 units scaled to `size`.
  * On a surface with a rim (dark), a light rim of 2 × rimWidth lines the square inside its 32 box (card 167). */

package/dist/src/pieces/node.d.ts

@@ -1,4 +1,4 @@
-export declare const SVG_TAGS: readonly ["svg", "g", "title", "desc", "defs", "clipPath", "rect", "circle", "ellipse", "line", "polyline", "polygon", "path", "text"];
+export declare const SVG_TAGS: readonly ["svg", "g", "title", "desc", "defs", "clipPath", "rect", "circle", "ellipse", "line", "polyline", "polygon", "path", "text", "tspan"];
 export type SvgTag = (typeof SVG_TAGS)[number];
 export type AttrValue = string | number;
 export type Attrs = Readonly<Record<string, AttrValue>>;

package/dist/src/pieces/node.js

@@ -23,6 +23,7 @@ export const SVG_TAGS = [
     "polygon",
     "path",
     "text",
+    "tspan",
 ];
 export const el = (tag, attrs = {}, ...children) => ({
     tag,

package/dist/src/pieces/params.d.ts

@@ -5,9 +5,12 @@ export type ParamSpec = {
     exclusiveMin?: boolean;
     max?: number;
     integer?: boolean;
-} | {
+}
+/** A token path; with `currentColor`, also that exact keyword (uiIcon.colour only, card 170). */
+ | {
     kind: "color";
     required?: boolean;
+    currentColor?: boolean;
 }
 /** A token path, or a colour from the consumer's data (#RRGGBB): pipe and lineBadge fills only. */
  | {
@@ -72,6 +75,10 @@ export declare const size: (required?: boolean, min?: number) => ParamSpec;
 /** A position: any finite number, because a map position has no maximum. */
 export declare const pos: () => ParamSpec;
 export declare const col: () => ParamSpec;
+/** The paint keyword that follows the text colour of an inline SVG's element. */
+export declare const CURRENT_COLOUR = "currentColor";
+/** A token path or `currentColor`: for icons written inline in a page. */
+export declare const colOrCurrent: () => ParamSpec;
 /** SVG path data: commands, digits, signs, dots, commas and spaces only. */
 export declare const PATH_DATA: RegExp;
 export declare const label: (required?: boolean) => ParamSpec;

package/dist/src/pieces/params.js

@@ -55,6 +55,8 @@ const checkValue = (spec, value, path, out) => {
             return;
         }
         case "color":
+            if (spec.currentColor && value === CURRENT_COLOUR)
+                return;
             if (typeof value !== "string")
                 return report(`expected a colour token path, found ${describe(value)}`);
             if (isColourLiteral(value))
@@ -87,7 +89,8 @@ const checkValue = (spec, value, path, out) => {
             return;
         case "point":
             // Any finite number: a map position has no maximum (spec illustration-pieces, "Positions of any size").
-            if (!Array.isArray(value) || value.length !== 2 || !value.every((n) => typeof n === "number" && Number.isFinite(n))) {
+            // Both indices read directly: every() skips the holes of a sparse array.
+            if (!Array.isArray(value) || value.length !== 2 || ![value[0], value[1]].every((n) => typeof n === "number" && Number.isFinite(n))) {
                 return report(`expected a point [x, y] of finite numbers, found ${describe(value)}`);
             }
             return;
@@ -98,7 +101,9 @@ const checkValue = (spec, value, path, out) => {
                 return report(`expected at least ${spec.minItems} item(s)`);
             if (value.length > (spec.maxItems ?? MAX_ITEMS))
                 return report(`expected at most ${spec.maxItems ?? MAX_ITEMS} item(s)`);
-            value.forEach((item, index) => checkValue(spec.of, item, `${path}[${index}]`, out));
+            // An index loop, not forEach: a hole in a sparse array is checked as a missing item, not skipped.
+            for (let index = 0; index < value.length; index++)
+                checkValue(spec.of, value[index], `${path}[${index}]`, out);
             return;
         case "object":
             if (!isPlainObject(value))
@@ -144,6 +149,10 @@ export const size = (required = false, min) => min === undefined ? { kind: "numb
 /** A position: any finite number, because a map position has no maximum. */
 export const pos = () => ({ kind: "number", required: true });
 export const col = () => ({ kind: "color" });
+/** The paint keyword that follows the text colour of an inline SVG's element. */
+export const CURRENT_COLOUR = "currentColor";
+/** A token path or `currentColor`: for icons written inline in a page. */
+export const colOrCurrent = () => ({ kind: "color", currentColor: true });
 /** SVG path data: commands, digits, signs, dots, commas and spaces only. */
 export const PATH_DATA = /^[MmLlHhVvCcSsQqTtAaZz0-9eE.,+\-\s]+$/;
 export const label = (required = true) => ({ kind: "string", nonEmpty: true, required });

package/dist/src/pieces/render.js

@@ -10,7 +10,8 @@ export const toSvg = (node, depth = 0) => {
     if (node.children.length === 0)
         return `${open}/>`;
     // Text content, alone or mixed with elements, is written inline: added whitespace would change it.
-    if (node.children.some((child) => typeof child === "string")) {
+    // A text node is always written inline, so one holding only a tspan keeps its words intact (body-diagram-pieces §4).
+    if (node.tag === "text" || node.children.some((child) => typeof child === "string")) {
         return `${open}>${node.children.map((child) => toSvg(child)).join("")}</${node.tag}>`;
     }
     if (node.children.every((child) => typeof child === "string")) {

package/dist/src/pieces/ui-icons.d.ts

@@ -16,5 +16,6 @@ export type UiIconParams = {
     size?: number;
     colour?: string;
 };
-/** One UI icon at (x, y), `size` wide (24 by default), in one token colour (`color.ink` by default). */
+/** One UI icon at (x, y), `size` wide (24 by default), in one token colour (`color.ink` by default)
+ * or `currentColor`, so an icon inline in a page follows its element's text colour. */
 export declare const uiIcon: import("./piece.ts").Piece<UiIconParams>;

package/dist/src/pieces/ui-icons.js

@@ -1,5 +1,5 @@
 import { el, g, drawn, r2 } from "./node.js";
-import { col, pos, size } from "./params.js";
+import { CURRENT_COLOUR, colOrCurrent, pos, size } from "./params.js";
 import { definePiece } from "./piece.js";
 import { colour } from "./params.js";
 /** Every UI icon draws in a 24x24 box. */
@@ -26,9 +26,10 @@ export const UI_ICONS = [
     { name: "download", title: "Download", description: "An arrow down into a tray.", nodes: [stroked("M12 3.5v11M7.5 10l4.5 4.5 4.5-4.5M4.5 16.5v3h15v-3")] },
 ];
 export const UI_ICON_NAMES = UI_ICONS.map((icon) => icon.name);
-/** One UI icon at (x, y), `size` wide (24 by default), in one token colour (`color.ink` by default). */
-export const uiIcon = definePiece("uiIcon", { name: { kind: "enum", required: true, values: UI_ICON_NAMES }, x: pos(), y: pos(), size: size(), colour: col() }, ({ name, x, y, size: side = UI_ICON_SIZE, colour: path = "color.ink" }) => {
+/** One UI icon at (x, y), `size` wide (24 by default), in one token colour (`color.ink` by default)
+ * or `currentColor`, so an icon inline in a page follows its element's text colour. */
+export const uiIcon = definePiece("uiIcon", { name: { kind: "enum", required: true, values: UI_ICON_NAMES }, x: pos(), y: pos(), size: size(), colour: colOrCurrent() }, ({ name, x, y, size: side = UI_ICON_SIZE, colour: path = "color.ink" }) => {
     const icon = UI_ICONS.find((candidate) => candidate.name === name);
-    const paint = colour(path, "colour");
+    const paint = path === CURRENT_COLOUR ? CURRENT_COLOUR : colour(path, "colour");
     return drawn([g({ transform: `translate(${r2(x)} ${r2(y)}) scale(${side / UI_ICON_SIZE})`, fill: paint, stroke: paint }, ...icon.nodes)]);
 });

package/dist/tokens/generated/tokens.d.ts

@@ -132,6 +132,7 @@ export declare const tokens: {
     readonly map: {
         readonly badgeHeight: 20;
         readonly badgeTextSize: 12;
+        readonly bendRadius: 32;
         readonly casing: 6;
         readonly countHeight: 16;
         readonly countTextSize: 11;

package/dist/tokens/generated/tokens.js

@@ -133,6 +133,7 @@ export const tokens = {
     "map": {
         "badgeHeight": 20,
         "badgeTextSize": 12,
+        "bendRadius": 32,
         "casing": 6,
         "countHeight": 16,
         "countTextSize": 11,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosouzas/design-system",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Design tokens and illustration pieces of brunosouzas.com: tokens as CSS, JSON and TypeScript, pieces that draw SVG (and React), and a cover command.",
   "license": "Apache-2.0",
   "repository": {

package/tokens/generated/tokens.css

@@ -78,6 +78,7 @@
   --ds-illustration-transitional-shade: #E8B830;
   --ds-map-badge-height: 20px;
   --ds-map-badge-text-size: 12px;
+  --ds-map-bend-radius: 32px;
   --ds-map-casing: 6px;
   --ds-map-count-height: 16px;
   --ds-map-count-text-size: 11px;

package/tokens/generated/tokens.json

@@ -132,6 +132,7 @@
   "map": {
     "badgeHeight": 20,
     "badgeTextSize": 12,
+    "bendRadius": 32,
     "casing": 6,
     "countHeight": 16,
     "countTextSize": 11,

package/tokens/generated/tokens.ts

@@ -134,6 +134,7 @@ export const tokens = {
   "map": {
     "badgeHeight": 20,
     "badgeTextSize": 12,
+    "bendRadius": 32,
     "casing": 6,
     "countHeight": 16,
     "countTextSize": 11,