@brunosouzas/design-system 0.5.0 → 0.5.2

package/README.md

@@ -136,13 +136,14 @@ The components take every colour and size from the tokens, and what is visible a
 
 ### 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, 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.
+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; `heads: "start"` or `"both"` puts heads at `from`, `dashed` overrides the kind's dash), `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).
 
 - `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.
+- `countBadge` takes `textSize` (6 to 48, default 11): without `height`, the height, width and baseline grow with it.
 - 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.
 - `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.
@@ -159,14 +160,15 @@ const badge = lineBadge({ x: 250, y: 40, text: "SH", fill: "#7B3FE4", surface: "
 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.
+- Backticks mark code: `` "adopts a `correlationId`" `` draws `correlationId` in the monospace stack, as a `tspan`. An odd number of backticks is drawn as is. The cover `pill` follows the same rule (`` "`main`" ``).
+- `milestonePin` takes `size`, the head's radius (6 to 48, default 18); the head, its outline and the label scale with it.
 - 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). The cover command does this for you with `"format": "diagram"` (below).
 - `stateStart({ cx, cy, r, surface })` draws the filled start dot of a state machine (7.7 units, 11 at 800), in the surface's text colour, with no outline and no shadow.
 
 ### The cast and the emotes
 
-`mascot({ who, x, y, face, action, scale, look, headTilt, prop })` draws one character standing with the centre of its ground line at `(x, y)`. Each one carries its identity in three layers, so no video has to introduce it: a body shape, a mark always visible, and a prop when its hands are free.
+`mascot({ who, x, y, face, action, scale, look, headTilt, prop, surface })` draws one character standing with the centre of its ground line at `(x, y)`. Each one carries its identity in three layers, so no video has to introduce it: a body shape, a mark always visible, and a prop when its hands are free.
 
 | `who` | Body | Mark | Prop | Colour |
 |---|---|---|---|---|
@@ -182,7 +184,7 @@ Ten pieces draw what the blog's body diagrams need beyond the map pieces: `diagr
 - `action`: `none` (the default: an expression has no hands or feet), `rest`, `wave`, `hold`, `reach`, `up`, `shrug`, `type`. Arms and legs start at the body's sides; hands are mittens.
 - `look` (-1 to 1) moves the gaze, `headTilt` (-30 to 30) turns the agent's head on its neck, `prop: false` hides the prop. Every part is a group named by `data-part` (`body`, `face`, `eyes`, `brows`, `mouth`, `arm-left`, `arm-right`, `legs`, `prop`, `mark`, …), so a scene can animate it.
 
-`emote({ kind, x, y, scale, burst })` draws a reaction beside a head, never over the face. Each kind keeps one meaning in every video, like the colours:
+`emote({ kind, x, y, scale, burst, surface })` draws a reaction beside a head, never over the face. Each kind keeps one meaning in every video, like the colours:
 
 | `kind` | Shape | Meaning |
 |---|---|---|
@@ -197,7 +199,7 @@ Ten pieces draw what the blog's body diagrams need beyond the map pieces: `diagr
 
 In a scene, an emote pops in on the frame the face changes (`emotePop` in `src/brand/cast-motion.ts`, with `leave`, `blinking`, `breathe`, `squashAfter` and `hop`), one at a time, and the body acts through `pose`. A mascot's colour is its identity and never changes with state. The approved motion test is the Studio composition `cast-motion-test` (folder `cast`): `npx remotion render src/index.ts cast-motion-test`. It is a proof of the cast, not an article scene, so `npm run stills` and `npm run render` do not list it.
 
-The cast draws the same on any background; a dark-surface variant is planned (AB#187).
+On a dark page pass `surface: "dark"` (AB#187, 0.5.2): the hard shadows take `surface.dark.shadow`, the ground takes `surface.dark.grid`, and a light rim (`surface.dark.rim`) lines the whole outline, limbs and props included; faces are unchanged. Without `surface`, the cast draws as in 0.5.0.
 
 ### A cover
 

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

@@ -1,4 +1,5 @@
 import { type SvgNode } from "./node.ts";
+import { type SurfaceName } from "./ink.ts";
 export declare const MASCOTS: readonly ["dev", "agent", "architect", "devops", "data", "request", "message"];
 export declare const MASCOT_FACES: readonly ["normal", "blink", "happy", "wink", "surprised", "worried", "thinking", "focused"];
 export declare const MASCOT_ACTIONS: readonly ["none", "rest", "wave", "hold", "reach", "up", "shrug", "type"];
@@ -18,6 +19,7 @@ export type MascotParams = {
     look?: number;
     headTilt?: number;
     prop?: boolean;
+    surface?: SurfaceName;
 };
 export type EmoteParams = {
     kind: EmoteKind;
@@ -25,6 +27,7 @@ export type EmoteParams = {
     y: number;
     scale?: number;
     burst?: boolean;
+    surface?: SurfaceName;
 };
 /** One character standing with the centre of its ground line at (x, y). */
 export declare const mascot: import("./piece.ts").Piece<MascotParams>;

package/dist/src/pieces/cast.js

@@ -10,7 +10,9 @@
 // (~/.hermes/spikes/design-system/cast-and-emotes/cast.mts). The frozen fixture
 // test/fixtures/cast-0.5.0.json pins every call's output, so a refactor here
 // must keep every hash.
+import { tokens } from "../../tokens/generated/tokens.js";
 import { drawn, el, g } from "./node.js";
+import { surfaceParam } from "./ink.js";
 import { colour, pos } from "./params.js";
 import { definePiece } from "./piece.js";
 const c = (path) => colour(path);
@@ -20,10 +22,59 @@ export const MASCOT_ACTIONS = ["none", "rest", "wave", "hold", "reach", "up", "s
 export const EMOTE_KINDS = ["idea", "doubt", "problem", "worked", "refused", "pressure", "liked", "waiting"];
 const ink = () => c("color.ink");
 const O = () => ({ stroke: ink(), "stroke-width": 4, "stroke-linejoin": "round" });
-const shade = (d, dx = 8) => el("path", { d, fill: ink(), transform: `translate(${dx} ${dx})` });
+// Every hard shadow is made by `hard`, so the dark drawing finds it by identity, not by its look.
+const SHADOWS = new WeakSet();
+const hard = (n) => (SHADOWS.add(n), n);
+const shade = (d, dx = 8) => hard(el("path", { d, fill: ink(), transform: `translate(${dx} ${dx})` }));
 const solid = (d, fill, dx = 8) => [shade(d, dx), el("path", { d, fill, ...O() })];
 const shine = (d, col) => el("path", { d, fill: "none", stroke: col, "stroke-width": 9, "stroke-linecap": "round" });
 const rr = (x, y, w, h, r) => `M${x + r},${y} H${x + w - r} Q${x + w},${y} ${x + w},${y + r} V${y + h - r} Q${x + w},${y + h} ${x + w - r},${y + h} H${x + r} Q${x},${y + h} ${x},${y + h - r} V${y + r} Q${x},${y} ${x + r},${y} Z`;
+// ---------------------------------------------------------------- dark surface (card 187)
+// On the dark surface (ADR 0003 amendment) the light drawing is rewritten, so the
+// light output stays the frozen 0.5.0 tree: each hard shadow (made by `hard`) takes the surface's
+// shadow colour, the ground takes the surface's grid colour, and a light rim
+// (the drawing in the rim colour, every stroke widened by 2 × 2 × rimWidth) sits
+// behind the whole outline, arms and legs included. The face is unchanged.
+const walk = (n, f) => {
+    const m = f(n);
+    if (!m)
+        return null;
+    const kids = m.children.map((k) => (typeof k === "string" ? k : walk(k, f))).filter((k) => k !== null);
+    return { ...m, children: kids };
+};
+const part = (n) => String(n.attrs["data-part"] ?? "");
+const onDark = (n) => {
+    const d = tokens.surface.dark;
+    return walk(n, (x) => {
+        if (SHADOWS.has(x))
+            return { ...x, attrs: { ...x.attrs, fill: d.shadow } };
+        if (part(x) === "ground")
+            return { ...x, children: x.children.map((k) => (typeof k === "string" ? k : { ...k, attrs: { ...k.attrs, fill: d.grid } })) };
+        return x;
+    });
+};
+const rimOf = (n) => {
+    const d = tokens.surface.dark;
+    return walk(n, (x) => {
+        if (SHADOWS.has(x) || ["ground", "face"].includes(part(x)) || x.attrs.opacity !== undefined)
+            return null;
+        if (x.tag === "g")
+            return x;
+        const sw = x.attrs.stroke !== undefined && x.attrs.stroke !== "none" ? Number(x.attrs["stroke-width"] ?? 4) : 0;
+        const attrs = { ...x.attrs, stroke: d.rim, "stroke-width": sw + 4 * d.rimWidth, "stroke-linejoin": "round" };
+        if (x.attrs.fill !== undefined && x.attrs.fill !== "none")
+            attrs.fill = d.rim;
+        return { ...x, attrs };
+    });
+};
+/** The light drawing redrawn for the dark surface: ground, rim, then the drawing. */
+const darken = (root) => {
+    // The rim is taken from the light tree, where shadows are still known by identity.
+    const isGround = (k) => typeof k === "object" && part(k) === "ground";
+    const rim = rimOf({ ...root, attrs: {}, children: root.children.filter((k) => !isGround(k)) });
+    const dark = onDark(root);
+    return { ...dark, children: [...dark.children.filter(isGround), ...(rim ? [g({ "data-part": "rim" }, ...rim.children)] : []), ...dark.children.filter((k) => !isGround(k))] };
+};
 // ---------------------------------------------------------------- face (macs.ts)
 export const face = (cx, cy, f, col, mouthFill) => {
     const k = 1, dx = 24 * k;
@@ -206,7 +257,7 @@ const drawMascot = (p) => {
         parts = [...parts, g({ "data-part": "head", transform: `rotate(${tilt} ${top[0]} ${top[1]})` }, ...solid(rr(top[0] - 96, 0, 192, 132, 22), c("color.white")), el("path", { d: rr(top[0] - 80, 14, 160, 104, 12), fill: c("illustration.codePanel"), stroke: ink(), "stroke-width": 4 }), faceWrapped)];
     }
     const root = g({ "data-mascot": p.who, transform: `translate(${p.x} ${p.y}) scale(${k}) translate(${-ax} ${-ay})`, stroke: "none" }, g({ "data-part": "ground" }, el("ellipse", { cx: ax, cy: ay, rx: ch.ground, ry: 9, fill: c("cast.ground") })), ...(front ? [] : arms), legs, ...parts, ch.faceInHead ? null : faceWrapped, showProp ? g({ "data-part": "prop" }, ...ch.prop()) : null, ...(front ? arms : []));
-    return drawn([root]);
+    return drawn([p.surface === "dark" ? darken(root) : root]);
 };
 // ---------------------------------------------------------------- emotes (emotes.ts)
 const rays = (cx, cy, r1, r2, n, from = -150, to = -30) => Array.from({ length: n }, (_, i) => {
@@ -215,7 +266,7 @@ const rays = (cx, cy, r1, r2, n, from = -150, to = -30) => Array.from({ length:
     return el("path", { d: `M${r(cx + r1 * Math.cos(a))},${r(cy + r1 * Math.sin(a))} L${r(cx + r2 * Math.cos(a))},${r(cy + r2 * Math.sin(a))}`, stroke: ink(), "stroke-width": 6, "stroke-linecap": "round" });
 });
 const EO = () => ({ stroke: ink(), "stroke-width": 5, "stroke-linejoin": "round", "stroke-linecap": "round" });
-const disc = (cx, cy, r, fill) => [el("circle", { cx: cx + 6, cy: cy + 6, r, fill: ink() }), el("circle", { cx, cy, r, fill, ...EO() })];
+const disc = (cx, cy, r, fill) => [hard(el("circle", { cx: cx + 6, cy: cy + 6, r, fill: ink() })), el("circle", { cx, cy, r, fill, ...EO() })];
 const zed = (x, y, s) => {
     // A Z of height s with its top-left at (x, y - s): ink casing, caller fill.
     const w = s * 0.72, d = `M${x},${y - s} H${x + w} L${x},${y} H${x + w}`;
@@ -230,7 +281,7 @@ const drawEmote = (p) => {
             if (burst)
                 parts.push(el("circle", { cx, cy: cy - 6, r: 62, fill: c("color.transitional"), opacity: 0.35 }), ...rays(cx, cy - 6, 50, 72, 7, -180, 0));
             const bulb = `M${cx - 30},${cy - 10} A34,34 0 1 1 ${cx + 30},${cy - 10} Q${cx + 22},${cy + 6} ${cx + 18},${cy + 22} H${cx - 18} Q${cx - 22},${cy + 6} ${cx - 30},${cy - 10} Z`;
-            parts.push(el("path", { d: bulb, fill: ink(), transform: "translate(6 6)" }), el("path", { d: bulb, fill: c("color.transitional"), ...EO() }), el("path", { d: `M${cx - 16},${cy - 22} Q${cx - 12},${cy - 32} ${cx - 2},${cy - 34}`, fill: "none", stroke: c("color.white"), "stroke-width": 6, "stroke-linecap": "round" }), el("path", { d: `M${cx - 8},${cy + 22} V${cy} L${cx},${cy + 8} L${cx + 8},${cy} V${cy + 22}`, fill: "none", stroke: ink(), "stroke-width": 4, "stroke-linejoin": "round" }), el("rect", { x: cx - 18, y: cy + 22, width: 36, height: 12, rx: 3, fill: c("cast.metal"), ...EO(), "stroke-width": 4 }), el("rect", { x: cx - 14, y: cy + 34, width: 28, height: 10, rx: 5, fill: c("cast.metal"), ...EO(), "stroke-width": 4 }));
+            parts.push(hard(el("path", { d: bulb, fill: ink(), transform: "translate(6 6)" })), el("path", { d: bulb, fill: c("color.transitional"), ...EO() }), el("path", { d: `M${cx - 16},${cy - 22} Q${cx - 12},${cy - 32} ${cx - 2},${cy - 34}`, fill: "none", stroke: c("color.white"), "stroke-width": 6, "stroke-linecap": "round" }), el("path", { d: `M${cx - 8},${cy + 22} V${cy} L${cx},${cy + 8} L${cx + 8},${cy} V${cy + 22}`, fill: "none", stroke: ink(), "stroke-width": 4, "stroke-linejoin": "round" }), el("rect", { x: cx - 18, y: cy + 22, width: 36, height: 12, rx: 3, fill: c("cast.metal"), ...EO(), "stroke-width": 4 }), el("rect", { x: cx - 14, y: cy + 34, width: 28, height: 10, rx: 5, fill: c("cast.metal"), ...EO(), "stroke-width": 4 }));
             break;
         }
         case "doubt":
@@ -239,7 +290,7 @@ const drawEmote = (p) => {
         case "problem":
             if (burst)
                 parts.push(...rays(cx, cy, 48, 70, 5));
-            parts.push(el("path", { d: `M${cx},${cy - 44} L${cx + 46},${cy + 34} H${cx - 46} Z`, fill: ink(), transform: "translate(6 6)" }), el("path", { d: `M${cx},${cy - 44} L${cx + 46},${cy + 34} H${cx - 46} Z`, fill: c("color.failure"), ...EO() }), el("path", { d: `M${cx},${cy - 18} V${cy + 8}`, stroke: ink(), "stroke-width": 9, "stroke-linecap": "round" }), el("circle", { cx, cy: cy + 22, r: 5.5, fill: ink() }));
+            parts.push(hard(el("path", { d: `M${cx},${cy - 44} L${cx + 46},${cy + 34} H${cx - 46} Z`, fill: ink(), transform: "translate(6 6)" })), el("path", { d: `M${cx},${cy - 44} L${cx + 46},${cy + 34} H${cx - 46} Z`, fill: c("color.failure"), ...EO() }), el("path", { d: `M${cx},${cy - 18} V${cy + 8}`, stroke: ink(), "stroke-width": 9, "stroke-linecap": "round" }), el("circle", { cx, cy: cy + 22, r: 5.5, fill: ink() }));
             break;
         case "pressure":
             for (const [dx, dy, k] of [[0, 0, 1], [30, 22, 0.6]])
@@ -261,7 +312,8 @@ const drawEmote = (p) => {
             break;
     }
     const attrs = s === 1 ? { "data-emote": kind, stroke: "none" } : { "data-emote": kind, stroke: "none", transform: `translate(${cx} ${cy}) scale(${s}) translate(${-cx} ${-cy})` };
-    return drawn([g(attrs, ...parts)]);
+    const root = g(attrs, ...parts);
+    return drawn([p.surface === "dark" ? darken(root) : root]);
 };
 const unit = { kind: "number", min: 0, exclusiveMin: true, max: 10 };
 /** One character standing with the centre of its ground line at (x, y). */
@@ -275,6 +327,7 @@ export const mascot = definePiece("mascot", {
     look: { kind: "number", min: -1, max: 1 },
     headTilt: { kind: "number", min: -30, max: 30 },
     prop: { kind: "boolean" },
+    surface: surfaceParam,
 }, drawMascot, ({ who, headTilt }) => (headTilt !== undefined && headTilt !== 0 && who !== "agent" ? [{ path: "headTilt", message: "applies only to the agent" }] : []));
 /** One reaction symbol with a fixed meaning, centred on (x, y), beside a head. */
-export const emote = definePiece("emote", { kind: { kind: "enum", required: true, values: EMOTE_KINDS }, x: pos(), y: pos(), scale: unit, burst: { kind: "boolean" } }, drawEmote);
+export const emote = definePiece("emote", { kind: { kind: "enum", required: true, values: EMOTE_KINDS }, x: pos(), y: pos(), scale: unit, burst: { kind: "boolean" }, surface: surfaceParam }, drawEmote);

package/dist/src/pieces/diagram.js

@@ -7,7 +7,7 @@
 // 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 { inkOf, inkSchema, limits, roomFor, spans, 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";
@@ -20,14 +20,6 @@ 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). */

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

@@ -45,4 +45,9 @@ export declare const atLeast: (name: string, value: number, least: number, what:
 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[];
+/** Backticks mark code (body-diagram-pieces design §4; the pill since card 190): 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. */
+export declare const spans: (value: string) => (SvgNode | string)[];
+/** A pill's text length for its default width: backticks of code runs do not count; otherwise `length` as in 0.5.0. */
+export declare const codeLength: (value: string) => number;
 export declare const words: (x: number, y: number, value: string, attrs: Attrs) => SvgNode;

package/dist/src/pieces/ink.js

@@ -34,5 +34,15 @@ export const sticker = (shape, face, inkParams) => {
         shape(0, 0, { fill: face, stroke: ink, "stroke-width": r2(outline), "stroke-linejoin": "round" }),
     ];
 };
+/** Backticks mark code (body-diagram-pieces design §4; the pill since card 190): 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. */
+export 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]));
+};
+/** A pill's text length for its default width: backticks of code runs do not count; otherwise `length` as in 0.5.0. */
+export const codeLength = (value) => (value.split("`").length % 2 === 1 && value.includes("`") ? value.replace(/`/g, "") : value).length;
 // 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

@@ -12,7 +12,7 @@ export type PillParams = {
     fill?: string;
     width?: number;
 };
-/** Pill label centred on (x, y), usually overlapping the top edge of what it names. */
+/** Pill label centred on (x, y), usually overlapping the top edge of what it names. Backticks mark code (card 190). */
 export declare const pill: import("./piece.ts").Piece<PillParams>;
 export declare const RING_COUNT = 14;
 /** Most rings one call draws: enough for a banner's farthest corner from any centre a cover spec accepts (548). */
@@ -140,8 +140,10 @@ export type MilestonePinParams = {
     text: string;
     fill?: string;
     stem?: number;
+    size?: number;
 };
-/** A pin standing on (x, y): a stem and a round head with a short label. */
+/** A pin standing on (x, y): a stem and a round head with a short label. `size` is the head's radius (18) and
+ * scales the head, its outline and the label together (card 190). */
 export declare const milestonePin: import("./piece.ts").Piece<MilestonePinParams>;
 export type PriceTagParams = {
     x: number;

package/dist/src/pieces/library.js

@@ -16,6 +16,7 @@ import { DIAGRAM_PIECES, stateStart } from "./diagram.js";
 import { uiIcon } from "./ui-icons.js";
 import { linkIcon } from "./link-icons.js";
 import { emote, mascot } from "./cast.js";
+import { codeLength, spans } from "./ink.js";
 export { emote, mascot };
 export * from "./metro.js";
 export * from "./diagram.js";
@@ -23,11 +24,11 @@ export * from "./ui-icons.js";
 export * from "./link-icons.js";
 const ink = tokens.color.ink;
 const mono = tokens.font.mono;
-/** Pill label centred on (x, y), usually overlapping the top edge of what it names. */
+/** Pill label centred on (x, y), usually overlapping the top edge of what it names. Backticks mark code (card 190). */
 export const pill = definePiece("pill", { x: pos(), y: pos(), text: label(), fill: col(), width: size() }, ({ x, y, text, fill = "color.white", width }) => {
     const h = tokens.cover.pillHeight;
-    const w = width ?? Math.max(68, Math.round(text.length * 10.5 + 34));
-    return drawn([el("rect", { x: x - w / 2, y: y - h / 2, width: w, height: h, rx: h / 2, fill: colour(fill, "fill") })], [el("text", { x, y: y + 7 }, text)]);
+    const w = width ?? Math.max(68, Math.round(codeLength(text) * 10.5 + 34));
+    return drawn([el("rect", { x: x - w / 2, y: y - h / 2, width: w, height: h, rx: h / 2, fill: colour(fill, "fill") })], [el("text", { x, y: y + 7 }, ...spans(text))]);
 });
 // ---------- background ----------
 export const RING_COUNT = 14;
@@ -194,8 +195,15 @@ export const road = definePiece("road", { d: { kind: "string", required: true, n
     el("path", { d, fill: "none", stroke: tokens.illustration.road, "stroke-width": 40, "stroke-linecap": "round" }),
     el("path", { d, fill: "none", stroke: tokens.color.white, "stroke-width": tokens.outline.block, "stroke-dasharray": "14 12" }),
 ]));
-/** A pin standing on (x, y): a stem and a round head with a short label. */
-export const milestonePin = definePiece("milestonePin", { x: pos(), y: pos(), text: label(), fill: col(), stem: size() }, ({ x, y, text, fill = "color.healthy", stem = 44 }) => drawn([el("line", { x1: x, y1: y, x2: x, y2: y - stem }), el("circle", { cx: x, cy: y - stem - 14, r: 18, fill: colour(fill, "fill"), "stroke-width": tokens.outline.small })], [el("text", { x, y: y - stem - 7, "font-size": 18, "font-weight": tokens.font.weightHeavy }, text)]));
+const PIN_SIZE = 18;
+/** A pin standing on (x, y): a stem and a round head with a short label. `size` is the head's radius (18) and
+ * scales the head, its outline and the label together (card 190). */
+export const milestonePin = definePiece("milestonePin", { x: pos(), y: pos(), text: label(), fill: col(), stem: size(), size: { kind: "number", min: 6, max: 48 } }, ({ x, y, text, fill = "color.healthy", stem = 44, size: r }) => {
+    // Without `size`, the 0.5.0 expressions exactly (no rounding), so every 0.5.0 call keeps its bytes.
+    const k = (r ?? PIN_SIZE) / PIN_SIZE;
+    const at = r === undefined ? (v) => v : r2;
+    return drawn([el("line", { x1: x, y1: y, x2: x, y2: y - stem }), el("circle", { cx: x, cy: at(y - stem - 14 * k), r: r ?? PIN_SIZE, fill: colour(fill, "fill"), "stroke-width": at(tokens.outline.small * k) })], [el("text", { x, y: at(y - stem - 7 * k), "font-size": r ?? PIN_SIZE, "font-weight": tokens.font.weightHeavy }, text)]);
+});
 /** Price or version tag pointing left from its tip (x, y), with a hole and an optional string. */
 export const priceTag = definePiece("priceTag", { x: pos(), y: pos(), text: label(), width: size(), fill: col(), stringFrom: { kind: "point" } }, ({ x, y, text, width: w = 128, fill = "color.white", stringFrom }) => {
     const h = 48;

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

@@ -34,6 +34,7 @@ export type CountBadgeParams = Ink & {
     text: string;
     width?: number;
     height?: number;
+    textSize?: number;
 };
 /** A count (rules of a skill): a circle when as wide as high, a pill otherwise, in the surface's panel colour. */
 export declare const countBadge: import("./piece.ts").Piece<CountBadgeParams>;
@@ -56,12 +57,15 @@ 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 ArrowHeads = "end" | "start" | "both";
 export type MessageArrowParams = {
     from: Point;
     to: Point;
     curve?: "bezier" | "straight";
     controls?: [Point, Point];
     head?: boolean;
+    heads?: ArrowHeads;
+    dashed?: boolean;
     label?: string;
     width?: number;
     kind?: ArrowKind;

package/dist/src/pieces/metro.js

@@ -70,20 +70,30 @@ export const pipe = definePiece("pipe", { d: PIPE_PATH, fill: dataColour(), widt
         el("path", { ...line, stroke: paint(fill), "stroke-width": width }),
     ]);
 });
-const countWidth = ({ width, text, height = M.countHeight }) => {
+// `textSize` scales the default height, the per-character width and the baseline with it (card 190);
+// without it, k is 1 and every expression is the 0.5.0 one.
+const countScale = ({ textSize }) => (textSize ?? M.countTextSize) / M.countTextSize;
+const countHeight = (params) => params.height ?? (params.textSize === undefined ? M.countHeight : r2(M.countHeight * countScale(params)));
+const countWidth = (params) => {
+    const { width, text } = params;
+    const height = countHeight(params);
+    const k = countScale(params);
     const characters = Array.from(text).length;
-    return width ?? (characters === 1 ? height : Math.max(height, 6.4 * characters + 8));
+    return width ?? (characters === 1 ? height : Math.max(height, k === 1 ? 6.4 * characters + 8 : r2(k * (6.4 * characters + 8))));
 };
 /** A count (rules of a skill): a circle when as wide as high, a pill otherwise, in the surface's panel colour. */
-export const countBadge = definePiece("countBadge", { cx: pos(), cy: pos(), text: label(), width: size(), height: size(), ...inkSchema }, (params) => {
-    const { cx, cy, text, height = M.countHeight } = params;
+export const countBadge = definePiece("countBadge", { cx: pos(), cy: pos(), text: label(), width: size(), height: size(), textSize: { kind: "number", min: 6, max: 48 }, ...inkSchema }, (params) => {
+    const { cx, cy, text, textSize = M.countTextSize } = params;
+    const height = countHeight(params);
     const width = countWidth(params);
     const { s } = inkOf(params);
     const shape = width === height ? (dx, dy, attrs) => el("circle", { cx: r2(cx + dx), cy: r2(cy + dy), r: r2(height / 2), ...attrs }) : pill(cx - width / 2, cy - height / 2, width, height);
-    return drawn(sticker(shape, s.panel, params), [words(cx, cy + 4, text, { fill: s.text, "font-size": M.countTextSize, "font-weight": bold, "text-anchor": "middle" })]);
+    return drawn(sticker(shape, s.panel, params), [words(cx, cy + 4 * countScale(params), text, { fill: s.text, "font-size": textSize, "font-weight": bold, "text-anchor": "middle" })]);
 }, (params) => {
-    const height = params.height ?? M.countHeight;
-    return limits(atLeast("width", countWidth(params), height, "the height"), roomFor("height", height, params));
+    const height = countHeight(params);
+    // A height derived from textSize is reported at textSize, the parameter the caller passed (card 190).
+    const name = params.height === undefined && params.textSize !== undefined ? "textSize" : "height";
+    return limits(atLeast("width", countWidth(params), height, "the height"), roomFor(name, height, params));
 });
 const nodeSchema = {
     x: pos(),
@@ -147,11 +157,13 @@ export const messageArrow = definePiece("messageArrow", {
     curve: { kind: "enum", values: ["bezier", "straight"] },
     controls: { kind: "array", minItems: 2, maxItems: 2, of: point() },
     head: { kind: "boolean" },
+    heads: { kind: "enum", values: ["end", "start", "both"] },
+    dashed: { 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", controls, head = true, label: text, width = M.edgeWidth, kind = "message", surface = "light" }) => {
+}, ({ from, to, curve = "bezier", controls, head = true, heads = "end", dashed, 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;
@@ -166,21 +178,35 @@ export const messageArrow = definePiece("messageArrow", {
     };
     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 atEnd = head && heads !== "start";
+    const atStart = head && heads !== "end";
+    const end = atEnd ? [to[0] - direction[0] * length, to[1] - direction[1] * length] : to;
+    // A head at `from` points back at it, from the first of c1, c2, to that differs from `from` (card 190).
+    const away = (q) => {
+        const l = Math.hypot(from[0] - q[0], from[1] - q[1]);
+        return [(from[0] - q[0]) / l, (from[1] - q[1]) / l];
+    };
+    const lead = controls && [controls[0], controls[1], to].find((q) => q[0] !== from[0] || q[1] !== from[1]);
+    const back = lead !== undefined ? away(lead) : bent ? [-Math.sign(dx), 0] : [-direction[0], -direction[1]];
+    const start = atStart ? [from[0] - back[0] * length, from[1] - back[1] * length] : from;
     const mx = (from[0] + to[0]) / 2;
     const at = (p) => `${r2(p[0])},${r2(p[1])}`;
     const d = controls
-        ? `M${at(from)} C${at(controls[0])} ${at(controls[1])} ${at(end)}`
+        ? `M${at(start)} 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)}` };
+            ? `M${at(start)} C${r2(mx)},${r2(from[1])} ${r2(mx)},${r2(to[1])} ${at(end)}`
+            : `M${at(start)} L${at(end)}`;
+    const dash = !(dashed ?? 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]]];
+    const arrowhead = (tip, base, along) => {
+        const normal = [-along[1] * 2 * width, along[0] * 2 * width];
+        const points = [tip, [base[0] + normal[0], base[1] + normal[1]], [base[0] - normal[0], base[1] - normal[1]]];
         body.push(el("polygon", { points: points.map(at).join(" "), fill: paint_, stroke: paint_, "stroke-width": 1, "stroke-linejoin": "round" }));
-    }
+    };
+    if (atEnd)
+        arrowhead(to, end, direction);
+    if (atStart)
+        arrowhead(from, start, back);
     const words_ = [];
     if (text !== undefined) {
         const middle = [mx, (from[1] + to[1]) / 2];
@@ -189,9 +215,10 @@ 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, controls, curve }) => {
+}, ({ from, to, head = true, heads, 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)}` }, controls !== undefined && curve !== undefined && { path: "controls", message: "cannot be combined with curve" });
+    const need = (heads === "both" ? 20 : 10) * width;
+    return limits(head === false && heads !== undefined && { path: "heads", message: "cannot be combined with head: false" }, distance === 0 && { path: "to", message: "must differ from from" }, distance > 0 && head && distance < need && { path: "to", message: `is too close to from for the ${heads === "both" ? "heads" : "head"}: needs at least ${r2(need)}, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosouzas/design-system",
-  "version": "0.5.0",
+  "version": "0.5.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": {