@brunosouzas/design-system 0.1.1 → 0.3.0

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) and the metro and diagram pieces (item 6) 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) 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).
 
 ## What it is
 
@@ -90,7 +90,7 @@ npm run stills -- publish-subscribe               # 24 phase/final PNGs (six per
 npm run stills -- publish-subscribe --dry-run     # print 24 commands, no effects
 npm run render -- publish-subscribe --dry-run     # print eight commands; real video waits for owner stills approval
 npm run build                                     # compile the package into dist/ (the package test needs it)
-npm run cover -- cover.json --out card.svg        # build a blog cover from its spec
+npm run cover -- cover.json --out card.svg        # build a blog cover (or a banner) from its spec
 npm run pieces:sheet -- --out out/pieces.svg      # every piece once, labelled, for review
 npm run studio                                    # Remotion Studio, for frame-by-frame review
 ```
@@ -130,17 +130,20 @@ 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 two line 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 35 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) and in [design §3](openspec/changes/archive/2026-10-23-metro-and-diagram-pieces/design.md) of `metro-and-diagram-pieces` (the nine below); the rules are in [`openspec/specs/illustration-pieces/`](openspec/specs/illustration-pieces/spec.md). `npm run pieces:sheet -- --out <file.svg>` draws them all.
+- 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.
 
 ### Maps and diagrams
 
-Nine 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) and `ledgerMark` (stackledger's mark). They paint what the caller lays out: positions, 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 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.
 
-- `surface: "light" | "dark"` picks the background they sit on (`surface.*` tokens); every map and diagram piece takes it except `pipe` and `ledgerMark`. 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).
+- 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.
-- A line's colour comes from the map's data, so `pipe.fill` and `lineBadge.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…), and `site.*` the page palette, fonts and type scale of brunosouzas.com in light and dark.
+- 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.
 
 ```ts
 import { lineBadge, pipe, stationMarker, toSvg } from "@brunosouzas/design-system";
@@ -151,7 +154,7 @@ const badge = lineBadge({ x: 250, y: 40, text: "SH", fill: "#7B3FE4", surface: "
 
 ### 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.
+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).
 
 ```json
 {
@@ -173,10 +176,30 @@ A cover is a JSON spec kept with its article, outside this repository: drafts ar
 - `custom` (optional) is the cover's one free-form object, a JSON node tree limited to drawing tags and a fixed list of attributes, with no external references. An object that repeats becomes a piece instead.
 - The three published covers that proved the pieces are the test fixtures in `test/fixtures/covers/`.
 
+### Banners
+
+A spec with `"format": "banner"` (the default is `"cover"`) builds a home banner for a site: `banner.width` x `banner.height` (1200x420) with corners rounded at `banner.radius` (20), the measures of brunosouzas.com's published banner. Same pieces, validation and command. Two things differ from a cover:
+
+- the rings go on until they reach the frame's farthest corner (22 rings for a centre at 600, 225 with radius 60), where a cover draws 14;
+- pieces and labels are clipped to the rounded frame too, so nothing pokes past a corner.
+
+The banner is one image that scales down as a whole. Words in it become small on a phone (a 19px label is about 6px at 375px wide), so keep them few or none. `test/fixtures/covers/home-banner.json` is the brunosouzas.com home banner redrawn from the pieces.
+
 ### A new piece
 
 Add it to `src/pieces/library.ts` (or `src/pieces/metro.ts` for a map or diagram piece) with `definePiece(name, schema, draw)`, take its colours and sizes from the tokens (a new colour goes to `tokens/source.json` first), register it in `PIECES`, and give it a sample in `scripts/pieces-sheet.ts`. The catalogue test then checks that it draws with only its required parameters and uses token colours only.
 
+### 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`).
+- `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.
+
+```ts
+import { el, linkIcon, toSvg } from "@brunosouzas/design-system";
+const github = toSvg(el("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 46 46", width: 28, height: 28 }, ...linkIcon({ icon: "github", x: 0, y: 0, surface: "dark" }).body));
+```
+
 ### EIP icons
 
 `src/pieces/eip-icons.ts` holds the 26 Enterprise Integration Patterns icons as data. They are redrawn from the icons by Gregor Hohpe and Bobby Woolf ([enterpriseintegrationpatterns.com](https://www.enterpriseintegrationpatterns.com/)), licensed [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); each icon keeps that credit in its description.

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

@@ -2,6 +2,9 @@ import { type PieceName } from "./library.ts";
 import { type SvgNode } from "./node.ts";
 import { type Problem } from "./params.ts";
 export declare const SAFE_ID: RegExp;
+/** Cover (800x420, the default) or banner (1200x420, rounded corners): spec cover-cli, "Banner output". */
+export declare const FORMATS: readonly ["cover", "banner"];
+export type CoverFormat = (typeof FORMATS)[number];
 export type CoverPiece = {
     piece: PieceName;
 } & Record<string, unknown>;
@@ -14,6 +17,7 @@ export type CoverSpec = {
     id: string;
     title: string;
     description: string;
+    format?: CoverFormat;
     background: string;
     rings: {
         cx: number;
@@ -28,5 +32,7 @@ export declare const backgroundNames: () => string[];
 export declare const comparePaths: (a: string, b: string) => number;
 /** Every problem of a parsed spec, sorted by path; empty when the spec is valid. */
 export declare const validateCoverSpec: (spec: unknown) => Problem[];
-/** The cover's node tree. The spec must be valid (validateCoverSpec returned no problem). */
+/** Rings a banner draws: out to the frame's farthest corner (spec cover-cli, "Banner rings reach the corners"). */
+export declare const bannerRingCount: (cx: number, cy: number, radius?: number) => number;
+/** The cover's (or banner's) node tree. The spec must be valid (validateCoverSpec returned no problem). */
 export declare const coverTree: (spec: CoverSpec) => SvgNode;

package/dist/src/pieces/cover.js

@@ -12,7 +12,9 @@ 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";
 export const SAFE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const TOP_LEVEL = ["id", "title", "description", "background", "rings", "pieces", "custom"];
+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". */
+export const FORMATS = ["cover", "banner"];
 const CUSTOM_TAGS = ["g", "rect", "circle", "ellipse", "line", "polyline", "polygon", "path", "text"];
 // Attributes a free-form object may use (design §6): geometry, paint, text and transform.
 const CUSTOM_ATTRS = new Set([
@@ -154,7 +156,7 @@ export const validateCoverSpec = (spec) => {
     if (!isPlainObject(spec.rings))
         out.push({ path: "rings", message: "missing or not an object (expected cx, cy and an optional radius)" });
     else {
-        const ringProblems = checkParams(rings.schema, spec.rings, "rings").filter((problem) => problem.path !== "rings.color");
+        const ringProblems = checkParams(rings.schema, spec.rings, "rings").filter((problem) => problem.path !== "rings.color" && problem.path !== "rings.count");
         out.push(...ringProblems);
         // The piece takes any finite centre; a cover spec keeps 0.1.0's ±10000, which bounds a banner's ring count.
         for (const axis of ["cx", "cy"]) {
@@ -169,6 +171,11 @@ export const validateCoverSpec = (spec) => {
     }
     if (isPlainObject(spec.rings) && Object.hasOwn(spec.rings, "color"))
         out.push({ path: "rings.color", message: "unknown parameter: the ring colour comes from the background" });
+    if (isPlainObject(spec.rings) && Object.hasOwn(spec.rings, "count"))
+        out.push({ path: "rings.count", message: "unknown parameter: the ring count comes from the format" });
+    if (spec.format !== undefined && (typeof spec.format !== "string" || !FORMATS.includes(spec.format))) {
+        out.push({ path: "format", message: `expected one of ${FORMATS.join(", ")}` });
+    }
     if (!Array.isArray(spec.pieces))
         out.push({ path: "pieces", message: "missing or not an array" });
     else
@@ -254,12 +261,25 @@ const resolveCustom = (node) => {
         attrs.stroke = "none";
     return el(node.tag, attrs, ...(node.children ?? []).map((child) => (typeof child === "string" ? child : resolveCustom(child))));
 };
-/** The cover's node tree. The spec must be valid (validateCoverSpec returned no problem). */
+/** Rings a banner draws: out to the frame's farthest corner (spec cover-cli, "Banner rings reach the corners"). */
+export const bannerRingCount = (cx, cy, radius = tokens.cover.ringRadius) => {
+    const { width, height } = tokens.banner;
+    const far = Math.max(...[[0, 0], [width, 0], [0, height], [width, height]].map(([x, y]) => Math.hypot(x - cx, y - cy)));
+    return Math.max(1, Math.ceil((far - radius) / tokens.cover.ringStep) + 1);
+};
+/** The cover's (or banner's) node tree. The spec must be valid (validateCoverSpec returned no problem). */
 export const coverTree = (spec) => {
-    const { width, height } = tokens.cover;
+    const banner = spec.format === "banner";
+    const { width, height } = banner ? tokens.banner : tokens.cover;
+    // A banner's corners are rounded; a cover keeps today's square frame, attribute for attribute.
+    const corner = banner ? { rx: tokens.banner.radius } : {};
     const pair = tokens.coverBackground[spec.background];
     const drawnPieces = spec.pieces.map(({ piece, ...params }) => PIECES[piece](params));
     const ringPath = `coverBackground.${spec.background}.ring`;
+    const ringCount = banner ? { count: bannerRingCount(spec.rings.cx, spec.rings.cy, spec.rings.radius) } : {};
+    const frame = `url(#${spec.id}-frame)`;
+    const outlined = g({ stroke: tokens.color.ink, "stroke-width": tokens.outline.block, "stroke-linejoin": "round" }, ...drawnPieces.flatMap((d) => d.body), spec.custom ? resolveCustom(spec.custom) : null);
+    const labels = g({ "font-size": tokens.cover.labelSize, "font-weight": tokens.cover.labelWeight, fill: tokens.color.ink, "text-anchor": "middle" }, ...drawnPieces.flatMap((d) => d.text));
     return el("svg", {
         xmlns: "http://www.w3.org/2000/svg",
         width,
@@ -268,5 +288,7 @@ export const coverTree = (spec) => {
         role: "img",
         "aria-labelledby": `${spec.id}-title ${spec.id}-desc`,
         "font-family": tokens.font.sans,
-    }, el("title", { id: `${spec.id}-title` }, spec.title), el("desc", { id: `${spec.id}-desc` }, spec.description), el("defs", {}, el("clipPath", { id: `${spec.id}-frame` }, el("rect", { width, height }))), el("rect", { width, height, fill: pair.fill }), g({ "clip-path": `url(#${spec.id}-frame)` }, ...rings({ ...spec.rings, color: ringPath }).body), g({ stroke: tokens.color.ink, "stroke-width": tokens.outline.block, "stroke-linejoin": "round" }, ...drawnPieces.flatMap((d) => d.body), spec.custom ? resolveCustom(spec.custom) : null), g({ "font-size": tokens.cover.labelSize, "font-weight": tokens.cover.labelWeight, fill: tokens.color.ink, "text-anchor": "middle" }, ...drawnPieces.flatMap((d) => d.text)));
+    }, el("title", { id: `${spec.id}-title` }, spec.title), el("desc", { id: `${spec.id}-desc` }, spec.description), el("defs", {}, el("clipPath", { id: `${spec.id}-frame` }, el("rect", { width, height, ...corner }))), el("rect", { width, height, ...corner, fill: pair.fill }), g({ "clip-path": frame }, ...rings({ ...spec.rings, color: ringPath, ...ringCount }).body), 
+    // On a banner, pieces and labels are clipped too, so nothing pokes past a rounded corner.
+    ...(banner ? [g({ "clip-path": frame }, outlined, labels)] : [outlined, labels]));
 };

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

@@ -5,5 +5,5 @@ export { COLOUR_TOKENS, DATA_COLOUR, MAX_ITEMS, paint, MAX_SIZE, checkParams, co
 export { definePiece, type Piece } from "./piece.ts";
 export * from "./library.ts";
 export { EIP_ICONS, EIP_ICON_NAMES, EIP_ICON_HEIGHT, EIP_ICON_WIDTH, type EipIcon } from "./eip-icons.ts";
-export { SAFE_ID, backgroundNames, comparePaths, coverTree, validateCoverSpec, type CoverPiece, type CoverSpec, type CustomNode } from "./cover.ts";
+export { FORMATS, SAFE_ID, backgroundNames, bannerRingCount, comparePaths, coverTree, validateCoverSpec, type CoverFormat, type CoverPiece, type CoverSpec, type CustomNode } from "./cover.ts";
 export { tokens, type Tokens } from "../../tokens/generated/tokens.ts";

package/dist/src/pieces/index.js

@@ -10,5 +10,5 @@ export { COLOUR_TOKENS, DATA_COLOUR, MAX_ITEMS, paint, MAX_SIZE, checkParams, co
 export { definePiece } from "./piece.js";
 export * from "./library.js";
 export { EIP_ICONS, EIP_ICON_NAMES, EIP_ICON_HEIGHT, EIP_ICON_WIDTH } from "./eip-icons.js";
-export { SAFE_ID, backgroundNames, comparePaths, coverTree, validateCoverSpec } from "./cover.js";
+export { FORMATS, SAFE_ID, backgroundNames, bannerRingCount, comparePaths, coverTree, validateCoverSpec } from "./cover.js";
 export { tokens } from "../../tokens/generated/tokens.js";

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

@@ -1,4 +1,6 @@
 export * from "./metro.ts";
+export * from "./ui-icons.ts";
+export * from "./link-icons.ts";
 type Point = [number, number];
 export type PillParams = {
     x: number;
@@ -10,13 +12,16 @@ export type PillParams = {
 /** Pill label centred on (x, y), usually overlapping the top edge of what it names. */
 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). */
+export declare const MAX_RINGS = 1000;
 export type RingsParams = {
     cx: number;
     cy: number;
     radius?: number;
     color?: string;
+    count?: number;
 };
-/** Concentric rings around (cx, cy): 14 rings, step and width from the cover tokens. */
+/** Concentric rings around (cx, cy): `count` rings (14 by default), step and width from the cover tokens. */
 export declare const rings: import("./piece.ts").Piece<RingsParams>;
 export type SheetRow = {
     lead?: "none" | "checkbox" | "checked" | "question";
@@ -266,6 +271,10 @@ export declare const PIECES: {
     readonly hexNode: import("./piece.ts").Piece<import("./metro.ts").NodeParams>;
     readonly messageArrow: import("./piece.ts").Piece<import("./metro.ts").MessageArrowParams>;
     readonly ledgerMark: import("./piece.ts").Piece<import("./metro.ts").LedgerMarkParams>;
+    readonly renewalRing: import("./piece.ts").Piece<import("./metro.ts").RenewalRingParams>;
+    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 pill: import("./piece.ts").Piece<PillParams>;
     readonly rings: import("./piece.ts").Piece<RingsParams>;
     readonly sheet: import("./piece.ts").Piece<SheetParams>;
@@ -292,6 +301,8 @@ export declare const PIECES: {
     readonly book: import("./piece.ts").Piece<BookParams>;
     readonly muleFlow: import("./piece.ts").Piece<MuleFlowParams>;
     readonly eipIcon: import("./piece.ts").Piece<EipIconParams>;
+    readonly uiIcon: import("./piece.ts").Piece<import("./ui-icons.ts").UiIconParams>;
+    readonly linkIcon: import("./piece.ts").Piece<import("./link-icons.ts").LinkIconParams>;
 };
 export type PieceName = keyof typeof PIECES;
 export declare const PIECE_NAMES: PieceName[];

package/dist/src/pieces/library.js

@@ -12,7 +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 { uiIcon } from "./ui-icons.js";
+import { linkIcon } from "./link-icons.js";
 export * from "./metro.js";
+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. */
@@ -23,9 +27,11 @@ export const pill = definePiece("pill", { x: pos(), y: pos(), text: label(), fil
 });
 // ---------- background ----------
 export const RING_COUNT = 14;
-/** Concentric rings around (cx, cy): 14 rings, step and width from the cover tokens. */
-export const rings = definePiece("rings", { cx: pos(), cy: pos(), radius: size(), color: col() }, ({ cx, cy, radius = tokens.cover.ringRadius, color = "color.ring" }) => drawn([
-    g({ fill: "none", stroke: colour(color, "color"), "stroke-width": tokens.cover.ringWidth }, ...Array.from({ length: RING_COUNT }, (_, i) => el("circle", { cx, cy, r: radius + i * tokens.cover.ringStep }))),
+/** Most rings one call draws: enough for a banner's farthest corner from any centre a cover spec accepts (548). */
+export const MAX_RINGS = 1000;
+/** Concentric rings around (cx, cy): `count` rings (14 by default), step and width from the cover tokens. */
+export const rings = definePiece("rings", { cx: pos(), cy: pos(), radius: size(), color: col(), count: count(1, MAX_RINGS) }, ({ cx, cy, radius = tokens.cover.ringRadius, color = "color.ring", count: rings = RING_COUNT }) => drawn([
+    g({ fill: "none", stroke: colour(color, "color"), "stroke-width": tokens.cover.ringWidth }, ...Array.from({ length: rings }, (_, i) => el("circle", { cx, cy, r: radius + i * tokens.cover.ringStep }))),
 ]));
 const rowSchema = {
     lead: { kind: "enum", values: ["none", "checkbox", "checked", "question"] },
@@ -373,5 +379,7 @@ export const PIECES = {
     muleFlow,
     eipIcon,
     ...METRO_PIECES,
+    uiIcon,
+    linkIcon,
 };
 export const PIECE_NAMES = Object.keys(PIECES);

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

@@ -0,0 +1,22 @@
+import { type SvgNode } from "./node.ts";
+import { type SurfaceName } from "./metro.ts";
+export type LinkIcon = {
+    readonly name: string;
+    readonly title: string;
+    readonly description: string; /** A colour token path. */
+    readonly face: string;
+    readonly glyph: readonly SvgNode[];
+};
+/** Every link icon draws in a 46x46 box. */
+export declare const LINK_ICON_SIZE = 46;
+export declare const LINK_ICONS: readonly LinkIcon[];
+export declare const LINK_ICON_NAMES: string[];
+export type LinkIconParams = {
+    icon: string;
+    x: number;
+    y: number;
+    size?: number;
+    surface?: SurfaceName;
+};
+/** One link sticker at (x, y), `size` wide (46 by default), on the light or the dark page. */
+export declare const linkIcon: import("./piece.ts").Piece<LinkIconParams>;

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

@@ -0,0 +1,80 @@
+// Link icons as data (spec illustration-pieces, "Link icons as data"; design §6
+// of stackledger-map-and-link-pieces): the social stickers of brunosouzas.com
+// (public/images/home/social-*.svg at e29b3dd), with every colour replaced by
+// its token, plus a `website` globe in the same style. `linkIcon` draws the
+// site's frame (light, or dark with its rim) around the face and the glyph, at
+// the site's measures (46 box, face 38 at 2, radius 9, outline 2.5).
+//
+// Credit: the GitHub mark is Font Awesome's (fontawesome.com), licensed
+// CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); its description
+// keeps the credit.
+//
+// What can go wrong: an unknown icon is rejected by the schema. No node holds
+// a link, a style, a script or a URL, so the output can ship as a static file.
+import { tokens } from "../../tokens/generated/tokens.js";
+import { drawn, el, g, r2 } from "./node.js";
+import { colour, pos, size } from "./params.js";
+import { definePiece } from "./piece.js";
+import { SURFACES } from "./metro.js";
+const C = tokens.color;
+const INK = C.ink;
+/** Every link icon draws in a 46x46 box. */
+export const LINK_ICON_SIZE = 46;
+export const LINK_ICONS = [
+    {
+        name: "github",
+        title: "GitHub",
+        description: "GitHub icon. The GitHub mark is from Font Awesome (fontawesome.com), CC BY 4.0.",
+        face: "color.white",
+        glyph: [g({ transform: "translate(9.5 9) scale(0.0455)" }, el("path", { d: "M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z", fill: INK, stroke: "none" }))],
+    },
+    {
+        name: "linkedin",
+        title: "LinkedIn",
+        description: "LinkedIn icon.",
+        face: "color.caller",
+        glyph: [
+            el("rect", { x: 12, y: 18.5, width: 4, height: 11.5, rx: 1, fill: INK, stroke: "none" }),
+            el("circle", { cx: 14, cy: 13.8, r: 2.4, fill: INK, stroke: "none" }),
+            el("path", { d: "M19.5,30 V18.5 H23.5 V20.3 C24.5,19 26.2,18.1 28,18.1 C31.2,18.1 32.5,20.2 32.5,23.6 V30 H28.5 V24.3 C28.5,22.7 27.8,21.9 26.6,21.9 C25.2,21.9 23.5,22.8 23.5,24.7 V30 Z", fill: INK, stroke: "none" }),
+        ],
+    },
+    {
+        name: "email",
+        title: "Email",
+        description: "Email icon.",
+        face: "color.transitional",
+        glyph: [
+            el("rect", { x: 9, y: 13, width: 24, height: 17, rx: 3, fill: C.white, stroke: INK, "stroke-width": 2.5 }),
+            el("path", { d: "M10,15 L21,23 L32,15", fill: "none", stroke: INK, "stroke-width": 2.5, "stroke-linejoin": "round" }),
+        ],
+    },
+    {
+        name: "website",
+        title: "Website",
+        description: "Website icon: a globe.",
+        face: "color.healthy",
+        glyph: [
+            el("circle", { cx: 21, cy: 21, r: 10.5, fill: C.white, stroke: INK, "stroke-width": 2.5 }),
+            el("ellipse", { cx: 21, cy: 21, rx: 4.6, ry: 10.5, fill: "none", stroke: INK, "stroke-width": 2 }),
+            el("path", { d: "M10.5 21H31.5M12.5 15.5H29.5M12.5 26.5H29.5", fill: "none", stroke: INK, "stroke-width": 2, "stroke-linecap": "round" }),
+        ],
+    },
+];
+export const LINK_ICON_NAMES = LINK_ICONS.map((icon) => icon.name);
+/** The site's frame: the shadow (and on dark the rim) behind the face. */
+const frame = (surface) => {
+    const s = tokens.surface[surface];
+    return s.rimWidth > 0
+        ? [
+            el("rect", { x: 4, y: 4, width: 41, height: 41, rx: 11, fill: s.shadow, stroke: "none" }),
+            el("rect", { x: 0.5, y: 0.5, width: 41, height: 41, rx: 11, fill: s.rim, stroke: "none" }),
+        ]
+        : [el("rect", { x: 5, y: 5, width: 38, height: 38, rx: 9, fill: s.shadow, stroke: "none" })];
+};
+/** One link sticker at (x, y), `size` wide (46 by default), on the light or the dark page. */
+export const linkIcon = definePiece("linkIcon", { icon: { kind: "enum", required: true, values: LINK_ICON_NAMES }, x: pos(), y: pos(), size: size(), surface: { kind: "enum", values: SURFACES } }, ({ icon, x, y, size: side = LINK_ICON_SIZE, surface = "light" }) => {
+    const data = LINK_ICONS.find((candidate) => candidate.name === icon);
+    const face = el("rect", { x: 2, y: 2, width: 38, height: 38, rx: 9, fill: colour(data.face, "face"), stroke: INK, "stroke-width": 2.5 });
+    return drawn([g({ transform: `translate(${r2(x)} ${r2(y)}) scale(${side / LINK_ICON_SIZE})`, stroke: "none" }, ...frame(surface), face, ...data.glyph)]);
+});

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

@@ -8,13 +8,13 @@ export type Ink = {
 export type LineBadgeParams = Ink & {
     x: number;
     y: number;
-    text: string;
+    text?: string;
     fill: string;
     width?: number;
     height?: number;
     flat?: boolean;
 };
-/** A line's terminal badge: a pill in the line colour with its code in white, centred on (x, y). */
+/** A line's terminal badge: a pill in the line colour with its code in white, centred on (x, y); without `text`, the pill alone. */
 export declare const lineBadge: import("./piece.ts").Piece<LineBadgeParams>;
 export type StationMarkerParams = Ink & {
     cx: number;
@@ -76,9 +76,44 @@ export type LedgerMarkParams = {
     y: number;
     size?: number;
     line?: string;
+    surface?: SurfaceName;
 };
-/** stackledger's mark (favicon, header): an ink square with a bent line and two stations, 32 units scaled to `size`. */
+/** 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). */
 export declare const ledgerMark: import("./piece.ts").Piece<LedgerMarkParams>;
+export type RenewalRingParams = Ink & {
+    cx: number;
+    cy: number;
+    r: number;
+    width?: number;
+};
+/** The renewal ring: bands like a bent pipe round a station (rim on dark, ink, then color.blocked), no shadow. */
+export declare const renewalRing: import("./piece.ts").Piece<RenewalRingParams>;
+export type SuggestedHaloParams = {
+    cx: number;
+    cy: number;
+    r: number;
+    surface?: SurfaceName;
+};
+/** The suggested-position halo: a dashed muted circle, no ink. */
+export declare const suggestedHalo: import("./piece.ts").Piece<SuggestedHaloParams>;
+export type LicenceMarkParams = Ink & {
+    cx: number;
+    cy: number;
+    state?: "owned" | "toBuy";
+    size?: number;
+};
+/** A licence: a small disc sticker, green when held, white to buy. Its own room rule: size ≥ 3 × outline. */
+export declare const licenceMark: import("./piece.ts").Piece<LicenceMarkParams>;
+export type ZoneParams = {
+    points: Point[];
+    fill: string;
+    title?: string;
+    titleAt?: Point;
+    surface?: SurfaceName;
+};
+/** A zone: the outline the caller gives (stackledger's hull), widened by a round stroke, at the surface's zone opacity; an optional title. */
+export declare const zone: import("./piece.ts").Piece<ZoneParams>;
 export declare const METRO_PIECES: {
     readonly lineBadge: import("./piece.ts").Piece<LineBadgeParams>;
     readonly stationMarker: import("./piece.ts").Piece<StationMarkerParams>;
@@ -89,5 +124,9 @@ export declare const METRO_PIECES: {
     readonly hexNode: import("./piece.ts").Piece<NodeParams>;
     readonly messageArrow: import("./piece.ts").Piece<MessageArrowParams>;
     readonly ledgerMark: import("./piece.ts").Piece<LedgerMarkParams>;
+    readonly renewalRing: import("./piece.ts").Piece<RenewalRingParams>;
+    readonly suggestedHalo: import("./piece.ts").Piece<SuggestedHaloParams>;
+    readonly licenceMark: import("./piece.ts").Piece<LicenceMarkParams>;
+    readonly zone: import("./piece.ts").Piece<ZoneParams>;
 };
 export {};

package/dist/src/pieces/metro.js

@@ -50,9 +50,10 @@ const sticker = (shape, face, inkParams) => {
 // 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 });
-const badgeWidth = ({ width, text }) => width ?? Math.max(30, 7.6 * Array.from(text).length + 18);
-/** A line's terminal badge: a pill in the line colour with its code in white, centred on (x, y). */
-export const lineBadge = definePiece("lineBadge", { x: pos(), y: pos(), text: label(), fill: dataColour(), width: size(), height: size(), flat: { kind: "boolean" }, ...inkSchema }, (params) => {
+// 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);
+/** A line's terminal badge: a pill in the line colour with its code in white, centred on (x, y); without `text`, the pill alone. */
+export const lineBadge = definePiece("lineBadge", { x: pos(), y: pos(), text: label(false), fill: dataColour(), width: size(), height: size(), flat: { kind: "boolean" }, ...inkSchema }, (params) => {
     const { x, y, text, fill, height = M.badgeHeight, flat = false } = params;
     const width = badgeWidth(params);
     const face = paint(fill);
@@ -60,7 +61,7 @@ export const lineBadge = definePiece("lineBadge", { x: pos(), y: pos(), text: la
     const inset = flat ? outline / 2 : 0;
     const shape = pill(x - width / 2 + inset, y - height / 2 + inset, width - 2 * inset, height - 2 * inset);
     const body = flat ? [shape(0, 0, { fill: face, stroke: ink, "stroke-width": r2(outline), "stroke-linejoin": "round" })] : sticker(shape, face, params);
-    return drawn(body, [words(x, y + 4.5, text, { fill: white, "font-size": M.badgeTextSize, "font-weight": bold, "text-anchor": "middle" })]);
+    return drawn(body, text === undefined ? [] : [words(x, y + 4.5, text, { fill: white, "font-size": M.badgeTextSize, "font-weight": bold, "text-anchor": "middle" })]);
 }, (params) => {
     const height = params.height ?? M.badgeHeight;
     return limits(atLeast("width", badgeWidth(params), height, "the height"), roomFor("height", height, params));
@@ -125,10 +126,11 @@ const nodeSchema = {
 const nodeLimits = (kind) => (params) => {
     const { width, height = M.nodeHeight, subtitle, state = "normal" } = params;
     const radius = params.radius ?? M.nodeRadius;
-    return limits(atLeast("width", width, 2 * height, "twice the height"), kind === "box" && radius > height / 2 && { path: "radius", message: `must be at most half the height (${r2(height / 2)}), found ${r2(radius)}` }, state === "placeholder" && subtitle !== undefined && { path: "subtitle", message: "a placeholder has no subtitle" }, state !== "placeholder" && roomFor("height", height, params));
+    return limits(atLeast("width", width, 2 * height, "twice the height"), kind === "box" && radius > height / 2 && { path: "radius", message: `must be at most half the height (${r2(height / 2)}), found ${r2(radius)}` }, state !== "placeholder" && roomFor("height", height, params));
 };
 const drawNode = (kind, params) => {
     const { x, y, width, height = M.nodeHeight, title, subtitle, state = "normal" } = params;
+    const inset = kind === "box" ? 12 : height / 2;
     const radius = kind === "pill" ? height / 2 : (params.radius ?? M.nodeRadius);
     const shape = kind === "hex"
         ? (dx, dy, attrs) => {
@@ -140,10 +142,16 @@ const drawNode = (kind, params) => {
     const { s } = inkOf(params);
     const middle = y + height / 2;
     if (state === "placeholder") {
-        return drawn([shape(0, 0, { fill: "none", stroke: s.muted, "stroke-width": 1.5, "stroke-dasharray": "5 4", "stroke-linejoin": "round" })], [words(x + width / 2, middle + 4.5, title, { fill: s.muted, "font-size": M.labelSize, "font-weight": 400, "text-anchor": "middle" })]);
+        const dashed = [shape(0, 0, { fill: "none", stroke: s.muted, "stroke-width": 1.5, "stroke-dasharray": "5 4", "stroke-linejoin": "round" })];
+        // With a subtitle, a normal node's text layout, every word muted (stackledger's unlinked box; card 167).
+        return drawn(dashed, subtitle === undefined
+            ? [words(x + width / 2, middle + 4.5, title, { fill: s.muted, "font-size": M.labelSize, "font-weight": 400, "text-anchor": "middle" })]
+            : [
+                words(x + inset, middle - 3, title, { fill: s.muted, "font-size": M.labelSize, "font-weight": bold, "text-anchor": "start" }),
+                words(x + inset, middle + 14, subtitle, { fill: s.muted, "font-size": 11, "font-weight": 400, "text-anchor": "start" }),
+            ]);
     }
     const focus = state === "focus";
-    const inset = kind === "box" ? 12 : height / 2;
     const titleFill = focus ? ink : s.text;
     const text = subtitle === undefined
         ? [words(x + inset, middle + 4.5, title, { fill: titleFill, "font-size": M.labelSize, "font-weight": bold, "text-anchor": "start" })]
@@ -198,8 +206,61 @@ export const messageArrow = definePiece("messageArrow", {
     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)}` });
 });
-/** stackledger's mark (favicon, header): an ink square with a bent line and two stations, 32 units scaled to `size`. */
-export const ledgerMark = definePiece("ledgerMark", { x: pos(), y: pos(), size: { kind: "number", min: 12, max: 512 }, line: col() }, ({ x, y, size: side = 32, line = "illustration.accent" }) => drawn([
-    g({ transform: `translate(${r2(x)} ${r2(y)}) scale(${side / 32})` }, el("rect", { x: 0, y: 0, width: 32, height: 32, rx: 7, fill: ink, stroke: "none" }), el("path", { d: "M7 23 L14 16 L25 16", fill: "none", stroke: colour(line, "line"), "stroke-width": 4.5, "stroke-linecap": "round", "stroke-linejoin": "round" }), el("circle", { cx: 14, cy: 16, r: 4, fill: white, stroke: ink, "stroke-width": 2 }), el("circle", { cx: 25, cy: 16, r: 2.6, fill: white, stroke: ink, "stroke-width": 1.6 })),
-]));
-export const METRO_PIECES = { lineBadge, stationMarker, pipe, countBadge, nodeBlock, pillNode, hexNode, messageArrow, ledgerMark };
+/** 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). */
+export const ledgerMark = definePiece("ledgerMark", { x: pos(), y: pos(), size: { kind: "number", min: 12, max: 512 }, line: col(), surface: surfaceParam }, ({ x, y, size: side = 32, line = "illustration.accent", surface = "light" }) => {
+    const { rimWidth, rim } = tokens.surface[surface];
+    const band = 2 * rimWidth;
+    const square = rimWidth > 0
+        ? [
+            el("rect", { x: 0, y: 0, width: 32, height: 32, rx: 7, fill: rim, stroke: "none" }),
+            el("rect", { x: band, y: band, width: 32 - 2 * band, height: 32 - 2 * band, rx: 7 - band, fill: ink, stroke: "none" }),
+        ]
+        : [el("rect", { x: 0, y: 0, width: 32, height: 32, rx: 7, fill: ink, stroke: "none" })];
+    return drawn([
+        g({ transform: `translate(${r2(x)} ${r2(y)}) scale(${side / 32})` }, ...square, el("path", { d: "M7 23 L14 16 L25 16", fill: "none", stroke: colour(line, "line"), "stroke-width": 4.5, "stroke-linecap": "round", "stroke-linejoin": "round" }), el("circle", { cx: 14, cy: 16, r: 4, fill: white, stroke: ink, "stroke-width": 2 }), el("circle", { cx: 25, cy: 16, r: 2.6, fill: white, stroke: ink, "stroke-width": 1.6 })),
+    ]);
+});
+/** The renewal ring: bands like a bent pipe round a station (rim on dark, ink, then color.blocked), no shadow. */
+export const renewalRing = definePiece("renewalRing", { cx: pos(), cy: pos(), r: size(true), width: { kind: "number", min: 0, exclusiveMin: true, max: 50 }, ...inkSchema }, (params) => {
+    const { cx, cy, r, width = M.ringWidth } = params;
+    const { s, outline, rim } = inkOf(params);
+    // Radius and band widths as given, like pipe's widths: a valid hairline must not round to zero.
+    const band = (stroke, strokeWidth) => el("circle", { cx: r2(cx), cy: r2(cy), r, fill: "none", stroke, "stroke-width": strokeWidth });
+    return drawn([...(s.rimWidth > 0 ? [band(s.rim, width + outline + 2 * rim)] : []), band(ink, width + outline), band(tokens.color.blocked, width)]);
+}, (params) => {
+    const { outline, rim } = inkOf(params);
+    const need = ((params.width ?? M.ringWidth) + outline + 2 * rim) / 2;
+    return limits(params.r < need && { path: "r", message: `leaves no room for the ring's bands: needs at least ${r2(need)}` });
+});
+/** The suggested-position halo: a dashed muted circle, no ink. */
+export const suggestedHalo = definePiece("suggestedHalo", { cx: pos(), cy: pos(), r: size(true), surface: surfaceParam }, ({ cx, cy, r, surface = "light" }) => drawn([el("circle", { cx: r2(cx), cy: r2(cy), r, fill: "none", stroke: tokens.surface[surface].muted, "stroke-width": M.haloWidth, "stroke-dasharray": "4 3" })]));
+/** A licence: a small disc sticker, green when held, white to buy. Its own room rule: size ≥ 3 × outline. */
+export const licenceMark = definePiece("licenceMark", { cx: pos(), cy: pos(), state: { kind: "enum", values: ["owned", "toBuy"] }, size: size(), ...inkSchema }, (params) => {
+    const { cx, cy, state = "owned", size: side = M.licenceSize } = params;
+    const shape = (dx, dy, attrs) => el("circle", { cx: r2(cx + dx), cy: r2(cy + dy), r: r2(side / 2), ...attrs });
+    return drawn(sticker(shape, state === "owned" ? tokens.color.healthy : white, params));
+}, (params) => {
+    const need = 3 * inkOf(params).outline;
+    const side = params.size ?? M.licenceSize;
+    return limits(side < need && { path: "size", message: `leaves no room for the licence's face: needs at least ${r2(need)} at this ink scale` });
+});
+/** Mixes a #RRGGBB colour with white by `amount` (stackledger's zone title tint). */
+const tint = (hex, amount) => "#" + [1, 3, 5].map((i) => Math.round(parseInt(hex.slice(i, i + 2), 16) * (1 - amount) + 255 * amount).toString(16).padStart(2, "0").toUpperCase()).join("");
+/** A zone: the outline the caller gives (stackledger's hull), widened by a round stroke, at the surface's zone opacity; an optional title. */
+export const zone = definePiece("zone", { points: { kind: "array", required: true, minItems: 1, maxItems: 10000, of: point() }, fill: dataColour(), title: label(false), titleAt: point(false), surface: surfaceParam }, ({ points, fill, title, titleAt, surface = "light" }) => {
+    const colourOf = paint(fill);
+    const pad = M.zonePadding;
+    const at = (p) => `${r2(p[0])},${r2(p[1])}`;
+    const shape = points.length === 1
+        ? el("circle", { cx: r2(points[0][0]), cy: r2(points[0][1]), r: pad, fill: colourOf })
+        : points.length === 2
+            ? el("line", { x1: r2(points[0][0]), y1: r2(points[0][1]), x2: r2(points[1][0]), y2: r2(points[1][1]), stroke: colourOf, "stroke-width": 2 * pad, "stroke-linecap": "round" })
+            : el("polygon", { points: points.map(at).join(" "), fill: colourOf, stroke: colourOf, "stroke-width": 2 * pad, "stroke-linejoin": "round" });
+    const titleFill = surface === "dark" ? tint(colourOf, M.zoneTitleTint) : colourOf;
+    const text = title !== undefined && titleAt !== undefined
+        ? [words(titleAt[0], titleAt[1] + 13, title, { fill: titleFill, "font-size": M.labelSize, "font-weight": bold, "text-anchor": "start" })]
+        : [];
+    return drawn([g({ opacity: tokens.surface[surface].zoneOpacity, stroke: "none" }, shape)], text);
+}, ({ title, titleAt }) => limits(title !== undefined && titleAt === undefined && { path: "titleAt", message: "is required with a title" }, titleAt !== undefined && title === undefined && { path: "title", message: "is required with titleAt" }));
+export const METRO_PIECES = { lineBadge, stationMarker, pipe, countBadge, nodeBlock, pillNode, hexNode, messageArrow, ledgerMark, renewalRing, suggestedHalo, licenceMark, zone };

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

@@ -0,0 +1,20 @@
+import type { SvgNode } from "./node.ts";
+export type UiIcon = {
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly nodes: readonly SvgNode[];
+};
+/** Every UI icon draws in a 24x24 box. */
+export declare const UI_ICON_SIZE = 24;
+export declare const UI_ICONS: readonly UiIcon[];
+export declare const UI_ICON_NAMES: string[];
+export type UiIconParams = {
+    name: string;
+    x: number;
+    y: number;
+    size?: number;
+    colour?: string;
+};
+/** One UI icon at (x, y), `size` wide (24 by default), in one token colour (`color.ink` by default). */
+export declare const uiIcon: import("./piece.ts").Piece<UiIconParams>;

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

@@ -0,0 +1,34 @@
+import { el, g, drawn, r2 } from "./node.js";
+import { col, pos, size } from "./params.js";
+import { definePiece } from "./piece.js";
+import { colour } from "./params.js";
+/** Every UI icon draws in a 24x24 box. */
+export const UI_ICON_SIZE = 24;
+const stroked = (d) => el("path", { d, fill: "none", "stroke-width": 2, "stroke-linecap": "round", "stroke-linejoin": "round" });
+const filled = (d) => el("path", { d, stroke: "none" });
+export const UI_ICONS = [
+    {
+        name: "sun",
+        title: "Sun",
+        description: "Light theme: a disc with eight rays.",
+        nodes: [el("circle", { cx: 12, cy: 12, r: 4.5, stroke: "none" }), stroked("M12 2.5v2.5M12 19v2.5M2.5 12H5M19 12h2.5M5.3 5.3l1.8 1.8M16.9 16.9l1.8 1.8M5.3 18.7l1.8-1.8M16.9 7.1l1.8-1.8")],
+    },
+    { name: "moon", title: "Moon", description: "Dark theme: a crescent moon.", nodes: [filled("M20.5 14.6A8.6 8.6 0 0 1 9.4 3.5a8.6 8.6 0 1 0 11.1 11.1Z")] },
+    { name: "zoomIn", title: "Zoom in", description: "A magnifier with a plus.", nodes: [stroked("M10.5 4a6.5 6.5 0 1 0 0 13a6.5 6.5 0 1 0 0-13ZM15.3 15.3l5.2 5.2M7.5 10.5h6M10.5 7.5v6")] },
+    { name: "zoomOut", title: "Zoom out", description: "A magnifier with a minus.", nodes: [stroked("M10.5 4a6.5 6.5 0 1 0 0 13a6.5 6.5 0 1 0 0-13ZM15.3 15.3l5.2 5.2M7.5 10.5h6")] },
+    { name: "reset", title: "Reset", description: "A circular arrow: back to the start.", nodes: [stroked("M4.5 12A7.5 7.5 0 1 0 6.7 6.7M4 3.5v4.5h4.5")] },
+    {
+        name: "calendar",
+        title: "Calendar",
+        description: "A calendar page with one day marked.",
+        nodes: [stroked("M5.5 5h13a2 2 0 0 1 2 2v11.5a2 2 0 0 1-2 2h-13a2 2 0 0 1-2-2V7a2 2 0 0 1 2-2ZM3.5 10h17M8 3v4M16 3v4"), el("rect", { x: 7, y: 13, width: 3, height: 3, rx: 0.5, stroke: "none" })],
+    },
+    { 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" }) => {
+    const icon = UI_ICONS.find((candidate) => candidate.name === name);
+    const paint = 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

@@ -1,4 +1,9 @@
 export declare const tokens: {
+    readonly banner: {
+        readonly height: 420;
+        readonly radius: 20;
+        readonly width: 1200;
+    };
     readonly color: {
         readonly backend: "#FF6B6B";
         readonly blocked: "#FF8A3D";
@@ -131,14 +136,19 @@ export declare const tokens: {
         readonly countHeight: 16;
         readonly countTextSize: 11;
         readonly edgeWidth: 2.5;
+        readonly haloWidth: 1.5;
         readonly interchangeExtra: 2;
         readonly labelSize: 13;
+        readonly licenceSize: 10;
         readonly lineWidth: 12;
         readonly nodeHeight: 46;
         readonly nodeRadius: 10;
         readonly outline: 3;
+        readonly ringWidth: 3;
         readonly shadow: 3.5;
         readonly stopRadius: 12;
+        readonly zonePadding: 32;
+        readonly zoneTitleTint: 0.6;
     };
     readonly motion: {
         readonly dimOpacity: 0.42;
@@ -228,6 +238,7 @@ export declare const tokens: {
             readonly rimWidth: 1;
             readonly shadow: "#4C5CB8";
             readonly text: "#EEF2FF";
+            readonly zoneOpacity: 0.22;
         };
         readonly light: {
             readonly background: "#EEF2FF";
@@ -238,6 +249,7 @@ export declare const tokens: {
             readonly rimWidth: 0;
             readonly shadow: "#0A1033";
             readonly text: "#0A1033";
+            readonly zoneOpacity: 0.12;
         };
     };
 };

package/dist/tokens/generated/tokens.js

@@ -1,5 +1,10 @@
 // Generated from tokens/source.json by scripts/tokens.ts (npm run tokens). Do not edit by hand.
 export const tokens = {
+    "banner": {
+        "height": 420,
+        "radius": 20,
+        "width": 1200
+    },
     "color": {
         "backend": "#FF6B6B",
         "blocked": "#FF8A3D",
@@ -132,14 +137,19 @@ export const tokens = {
         "countHeight": 16,
         "countTextSize": 11,
         "edgeWidth": 2.5,
+        "haloWidth": 1.5,
         "interchangeExtra": 2,
         "labelSize": 13,
+        "licenceSize": 10,
         "lineWidth": 12,
         "nodeHeight": 46,
         "nodeRadius": 10,
         "outline": 3,
+        "ringWidth": 3,
         "shadow": 3.5,
-        "stopRadius": 12
+        "stopRadius": 12,
+        "zonePadding": 32,
+        "zoneTitleTint": 0.6
     },
     "motion": {
         "dimOpacity": 0.42,
@@ -228,7 +238,8 @@ export const tokens = {
             "rim": "#EEF2FF",
             "rimWidth": 1,
             "shadow": "#4C5CB8",
-            "text": "#EEF2FF"
+            "text": "#EEF2FF",
+            "zoneOpacity": 0.22
         },
         "light": {
             "background": "#EEF2FF",
@@ -238,7 +249,8 @@ export const tokens = {
             "rim": "#EEF2FF",
             "rimWidth": 0,
             "shadow": "#0A1033",
-            "text": "#0A1033"
+            "text": "#0A1033",
+            "zoneOpacity": 0.12
         }
     }
 };

package/package.json

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

@@ -1,5 +1,8 @@
 /* Generated from tokens/source.json by scripts/tokens.ts (npm run tokens). Do not edit by hand. */
 :root {
+  --ds-banner-height: 420px;
+  --ds-banner-radius: 20px;
+  --ds-banner-width: 1200px;
   --ds-color-backend: #FF6B6B;
   --ds-color-blocked: #FF8A3D;
   --ds-color-caller: #8FB2FF;
@@ -79,14 +82,19 @@
   --ds-map-count-height: 16px;
   --ds-map-count-text-size: 11px;
   --ds-map-edge-width: 2.5px;
+  --ds-map-halo-width: 1.5px;
   --ds-map-interchange-extra: 2px;
   --ds-map-label-size: 13px;
+  --ds-map-licence-size: 10px;
   --ds-map-line-width: 12px;
   --ds-map-node-height: 46px;
   --ds-map-node-radius: 10px;
   --ds-map-outline: 3px;
+  --ds-map-ring-width: 3px;
   --ds-map-shadow: 3.5px;
   --ds-map-stop-radius: 12px;
+  --ds-map-zone-padding: 32px;
+  --ds-map-zone-title-tint: 0.6;
   --ds-motion-dim-opacity: 0.42;
   --ds-motion-draw-arrow: 20;
   --ds-motion-fade: 10;
@@ -149,6 +157,7 @@
   --ds-surface-dark-rim-width: 1px;
   --ds-surface-dark-shadow: #4C5CB8;
   --ds-surface-dark-text: #EEF2FF;
+  --ds-surface-dark-zone-opacity: 0.22;
   --ds-surface-light-background: #EEF2FF;
   --ds-surface-light-grid: #E0E7FB;
   --ds-surface-light-muted: #5B6694;
@@ -157,4 +166,5 @@
   --ds-surface-light-rim-width: 0px;
   --ds-surface-light-shadow: #0A1033;
   --ds-surface-light-text: #0A1033;
+  --ds-surface-light-zone-opacity: 0.12;
 }

package/tokens/generated/tokens.json

@@ -1,4 +1,9 @@
 {
+  "banner": {
+    "height": 420,
+    "radius": 20,
+    "width": 1200
+  },
   "color": {
     "backend": "#FF6B6B",
     "blocked": "#FF8A3D",
@@ -131,14 +136,19 @@
     "countHeight": 16,
     "countTextSize": 11,
     "edgeWidth": 2.5,
+    "haloWidth": 1.5,
     "interchangeExtra": 2,
     "labelSize": 13,
+    "licenceSize": 10,
     "lineWidth": 12,
     "nodeHeight": 46,
     "nodeRadius": 10,
     "outline": 3,
+    "ringWidth": 3,
     "shadow": 3.5,
-    "stopRadius": 12
+    "stopRadius": 12,
+    "zonePadding": 32,
+    "zoneTitleTint": 0.6
   },
   "motion": {
     "dimOpacity": 0.42,
@@ -227,7 +237,8 @@
       "rim": "#EEF2FF",
       "rimWidth": 1,
       "shadow": "#4C5CB8",
-      "text": "#EEF2FF"
+      "text": "#EEF2FF",
+      "zoneOpacity": 0.22
     },
     "light": {
       "background": "#EEF2FF",
@@ -237,7 +248,8 @@
       "rim": "#EEF2FF",
       "rimWidth": 0,
       "shadow": "#0A1033",
-      "text": "#0A1033"
+      "text": "#0A1033",
+      "zoneOpacity": 0.12
     }
   }
 }

package/tokens/generated/tokens.ts

@@ -1,6 +1,11 @@
 // Generated from tokens/source.json by scripts/tokens.ts (npm run tokens). Do not edit by hand.
 
 export const tokens = {
+  "banner": {
+    "height": 420,
+    "radius": 20,
+    "width": 1200
+  },
   "color": {
     "backend": "#FF6B6B",
     "blocked": "#FF8A3D",
@@ -133,14 +138,19 @@ export const tokens = {
     "countHeight": 16,
     "countTextSize": 11,
     "edgeWidth": 2.5,
+    "haloWidth": 1.5,
     "interchangeExtra": 2,
     "labelSize": 13,
+    "licenceSize": 10,
     "lineWidth": 12,
     "nodeHeight": 46,
     "nodeRadius": 10,
     "outline": 3,
+    "ringWidth": 3,
     "shadow": 3.5,
-    "stopRadius": 12
+    "stopRadius": 12,
+    "zonePadding": 32,
+    "zoneTitleTint": 0.6
   },
   "motion": {
     "dimOpacity": 0.42,
@@ -229,7 +239,8 @@ export const tokens = {
       "rim": "#EEF2FF",
       "rimWidth": 1,
       "shadow": "#4C5CB8",
-      "text": "#EEF2FF"
+      "text": "#EEF2FF",
+      "zoneOpacity": 0.22
     },
     "light": {
       "background": "#EEF2FF",
@@ -239,7 +250,8 @@ export const tokens = {
       "rim": "#EEF2FF",
       "rimWidth": 0,
       "shadow": "#0A1033",
-      "text": "#0A1033"
+      "text": "#0A1033",
+      "zoneOpacity": 0.12
     }
   }
 } as const;