@brunosouzas/design-system 0.3.1 → 0.4.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), the metro and diagram pieces (item 6) and stackledger's map markers, zones and icons (AB#167, 0.3.0) are implemented: the static drawing library that covers, banners, diagrams and scenes share, with a command that builds a blog cover from a JSON spec. The published covers are not ported to it yet (item 5).
+Early. The first change of the [roadmap](docs/roadmap.md) is implemented: the token source and its CSS, TypeScript and JSON exports, the motion components, and the circuit-breaker state machine as the first catalogue scene (16:9 and 4:5, Portuguese and English), with commands to render its stills and videos. The first variety scene, `publish-subscribe`, is implemented with independent message copies, Publish acceptance, two ACKs and a local invoice NACK. Its owner stills/video approval is pending; implementation is not visual approval. The illustration pieces (roadmap item 3), the metro and diagram pieces (item 6) stackledger's map markers, zones and icons (AB#167, 0.3.0) and the body diagram pieces (AB#141, 0.3.2) are implemented: the static drawing library that covers, banners, diagrams and scenes share, with a command that builds a blog cover from a JSON spec. The published covers are not ported to it yet (item 5).
 
 ## What it is
 
@@ -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 (or a banner) from its spec
+npm run cover -- cover.json --out card.svg        # build a blog cover (or a banner, diagram or icon) 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
 ```
@@ -131,11 +131,11 @@ The components take every colour and size from the tokens, and what is visible a
 - `toSvg(node)` writes a tree as SVG text; `toReact(node)` turns the same tree into React elements. Both describe the same elements, attributes and text, which the tests check.
 - `pose(node, { x, y, tilt, squash, hop, scale, shake, opacity })` animates any piece around its base point; a scene recomputes the numbers every frame.
 - Every colour parameter is a token path (`"color.healthy"`, `"illustration.accent"`), never a hex value, except the three data fills of the map pieces below. Each piece checks its parameters before drawing and names the first wrong one. Positions and points take any finite number, because a map has no edge; sizes stay within 10000. A drawing that would hold a non-finite number throws `<piece>: the drawing overflows`.
-- The 41 pieces, with their anchors, parameters and defaults, are listed in [design §4](openspec/changes/archive/2026-10-23-illustration-pieces/design.md) (the 26 cover pieces), in [design §3](openspec/changes/archive/2026-10-23-metro-and-diagram-pieces/design.md) of `metro-and-diagram-pieces` (the nine map and diagram pieces) and in [design §3, §5 and §6](openspec/changes/archive/2026-10-23-stackledger-map-and-link-pieces/design.md) of `stackledger-map-and-link-pieces` (the six markers, zones and icons); the rules are in [`openspec/specs/illustration-pieces/`](openspec/specs/illustration-pieces/spec.md). `npm run pieces:sheet -- --out <file.svg>` draws them all.
+- The 52 pieces, with their anchors, parameters and defaults, are listed in [design §4](openspec/changes/archive/2026-10-23-illustration-pieces/design.md) (the 26 cover pieces), in [design §3](openspec/changes/archive/2026-10-23-metro-and-diagram-pieces/design.md) of `metro-and-diagram-pieces` (the nine map and diagram pieces) and in [design §3, §5 and §6](openspec/changes/archive/2026-10-23-stackledger-map-and-link-pieces/design.md) of `stackledger-map-and-link-pieces` (the six markers, zones and icons) and in [design §3 to §5](openspec/changes/archive/2026-10-23-body-diagram-pieces/design.md) of `body-diagram-pieces` (the ten body diagram pieces), plus `stateStart` ([design §4](openspec/changes/archive/2026-10-24-designer-formats/design.md) of `designer-formats`); the rules are in [`openspec/specs/illustration-pieces/`](openspec/specs/illustration-pieces/spec.md). `npm run pieces:sheet -- --out <file.svg>` draws them all.
 
 ### Maps and diagrams
 
-Thirteen pieces draw a metro map and its page diagrams, for [stackledger](https://github.com/brunosouzas/stackledger) and any other map in this style: `lineBadge`, `stationMarker` (stop, interchange as a capsule, deprecated), `pipe`, `countBadge`, `nodeBlock`, `pillNode`, `hexNode` (normal, focus, placeholder), `messageArrow` (curved or straight, with a head and an optional label) `ledgerMark` (stackledger's mark; `surface: "dark"` lines it with a light rim), `renewalRing` (orange bands round a station), `suggestedHalo` (a dashed muted circle), `licenceMark` (a 10-unit disc, green when held, white to buy) and `zone` (the outline the caller gives, widened by a round 32-unit stroke at the surface's zone opacity, with an optional title). They paint what the caller lays out: positions, hulls, text measurement and truncation stay with the map engine.
+Thirteen pieces draw a metro map and its page diagrams, for [stackledger](https://github.com/brunosouzas/stackledger) and any other map in this style: `lineBadge`, `stationMarker` (stop, interchange as a capsule, deprecated), `pipe`, `countBadge`, `nodeBlock`, `pillNode`, `hexNode` (normal, focus, placeholder), `messageArrow` (curved, straight or through two `controls` points, with a head and an optional label; `kind` `reply`, `failure` or `failFast` dashes it and paints it as ADR 0003 says), `ledgerMark` (stackledger's mark; `surface: "dark"` lines it with a light rim), `renewalRing` (orange bands round a station), `suggestedHalo` (a dashed muted circle), `licenceMark` (a 10-unit disc, green when held, white to buy) and `zone` (the outline the caller gives, widened by a round 32-unit stroke at the surface's zone opacity, with an optional title). They paint what the caller lays out: positions, hulls, text measurement and truncation stay with the map engine.
 
 - A `placeholder` node may have a `subtitle` (drawn like a normal node's, all muted), and `lineBadge` may have no `text` (the pill alone, 30 wide by default).
 - The licence's disc is small, so it has its own room rule: `size` at least three outlines (9 at ink scale 1).
@@ -153,6 +153,16 @@ const stop = stationMarker({ cx: 120, cy: 40, surface: "dark" });
 const badge = lineBadge({ x: 250, y: 40, text: "SH", fill: "#7B3FE4", surface: "dark" });
 ```
 
+### Body diagrams
+
+Ten pieces draw what the blog's body diagrams need beyond the map pieces: `diagramBox` (a box or pill with a fill and centred lines), `decisionNode` (diamond), `storeNode` (cylinder), `queueNode` (box with two rails), `exchangeNode` (hexagon), `taggedContainer` (a frame with its name on a tab), `lifeline` (dashed, or sparse dots once nothing calls it), `phaseBand` (a pill across a sequence in its state's colour), `altFrame` (alt/else frame with a tag and condition per part) and `edgeLabel` (words next to an arrow, optionally on a backdrop). They take `surface` and, the stickers, `inkScale`, like the map pieces, and paint what the caller lays out.
+
+- The shapes take one to three centred lines (`text`), an optional `subtitle` and `textSize`. Without `fill` the face is the surface's panel; with a fill, every word is ink.
+- Backticks mark code: `` "adopts a `correlationId`" `` draws `correlationId` in the monospace stack, as a `tspan`. An odd number of backticks is drawn as is.
+- Widths the piece estimates (`tagWidth`, `conditionWidth`, a label's `width`) can be passed by a caller that measures its text.
+- A body diagram is 800 wide. Lay it out in 560 units and show it 800 wide: the pieces then come out at the sizes of the published diagrams (text about 18, outline about 4); only the hard shadow is shallower (5 instead of 8). 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.
+
 ### A cover
 
 A cover is a JSON spec kept with its article, outside this repository: drafts are private, and only the pieces are public. `npm run cover -- <spec.json> --out <file.svg>` validates it, reports every problem with its JSON path, and writes an 800x420 SVG; the same spec always gives the same bytes. With `"format": "banner"` the same command writes a site banner instead (see below).
@@ -171,10 +181,10 @@ A cover is a JSON spec kept with its article, outside this repository: drafts ar
 }
 ```
 
-- `background` names one of the 21 pairs in `coverBackground` (a background and its ring colour, measured from the published covers). Each pair is used by one cover only.
+- `background` names one of the 21 pairs in `coverBackground` (a background and its ring colour, measured from the published covers). Which covers may share a pair is the `designer` skill's rule, not the package's.
 - `pieces` are drawn in order; their words go on top.
 - The `rings` centre stays within ±10000 in a cover spec, and a piece that overflows is reported at its entry (`pieces[1]: the drawing overflows`).
-- `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.
+- `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. It is painted after every piece's shapes; `customAt: <i>` paints it before `pieces[i]` instead, so a pill can sit on top of it (words always stay on top).
 - The three published covers that proved the pieces are the test fixtures in `test/fixtures/covers/`.
 
 ### Banners
@@ -186,6 +196,19 @@ A spec with `"format": "banner"` (the default is `"cover"`) builds a home banner
 
 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.
 
+### Body diagrams and icons from a spec
+
+The same command draws the blog's body diagrams and icons, so a consumer needs no script and no local install:
+
+```sh
+npx --yes --package @brunosouzas/design-system@<version> brunosouzas-cover design/<topic>.json --lang pt --out images/<topic>-pt.svg
+```
+
+- `"format": "diagram"` takes a `height` in layout units (1 to 10000) and no `background`: the spec is laid out 560 wide and written 800 wide, on the `color.panel` panel with rounded corners (`bodyDiagram.radius`, 14 at 800) and rings in `color.ring` that show at step 28 and width 2, out to the farthest corner. Pieces get the map outline (3) and label size (13), which show at 4.3 and 18.6. `test/fixtures/covers/circuit-breaker-states.json` is the circuit breaker article's state diagram.
+- `"format": "icon"` holds one `eipIcon`, `uiIcon` or `linkIcon` at 0,0 and writes it in a box of its own size (64x40 for an EIP icon). An EIP icon takes its title and description, with the CC BY 4.0 credit, from the icon's data, so its spec has neither; a UI or link icon spec needs both. No `background`, `rings` or `custom`.
+- **Text tables.** `"text": { "pt": { "open": ["taxa de falha", "> limite"] }, "en": { ... } }` holds one table per language with the same keys; any string `"@open"` elsewhere in the spec (pieces, `title`, `description`, even `id`) is replaced by that key's value for the language passed with `--lang <code>`. Every language must define every key, and the ids in the output gain the language (`<id>-pt`). Without `text`, strings are drawn as written, so `"@home"` stays a label.
+- Like a cover, a diagram or icon is a standalone image: `uiIcon` `colour: "currentColor"` is refused in every format.
+
 ### 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.

package/dist/scripts/cover.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-export declare const COVER_USAGE = "usage: npm run cover -- <spec.json> --out <file.svg>";
+export declare const COVER_USAGE = "usage: npm run cover -- <spec.json> --out <file.svg> [--lang <code>]";
 export type CoverIo = {
     cwd: string;
     log: (line: string) => void;
@@ -10,12 +10,13 @@ export declare const parseCoverArgs: (args: string[], cwd: string) => {
     ok: true;
     spec: string;
     out: string;
+    lang?: string;
 } | {
     ok: false;
     problem: string;
 };
 /** Builds the cover text for a spec file's contents, or the problem lines. */
-export declare const buildCover: (text: string, label: string) => {
+export declare const buildCover: (text: string, label: string, lang?: string) => {
     ok: true;
     svg: string;
 } | {

package/dist/scripts/cover.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// `npm run cover -- <spec.json> --out <file.svg>`, installed as the bin
+// `npm run cover -- <spec.json> --out <file.svg> [--lang <code>]`, installed as the bin
 // `brunosouzas-cover` (spec cover-cli; design §6):
 // builds one blog cover from a cover spec kept with its article in the vault.
 //
@@ -14,23 +14,29 @@ import { closeSync, existsSync, openSync, readFileSync, realpathSync, renameSync
 import { randomUUID } from "node:crypto";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { coverTree, validateCoverSpec } from "../src/pieces/cover.js";
+import { coverTree, LANGUAGE, validateCoverSpec } from "../src/pieces/cover.js";
 import { toSvg } from "../src/pieces/render.js";
-export const COVER_USAGE = "usage: npm run cover -- <spec.json> --out <file.svg>";
+export const COVER_USAGE = "usage: npm run cover -- <spec.json> --out <file.svg> [--lang <code>]";
 /** The first invocation problem, in the order of the spec, or the two paths. */
 export const parseCoverArgs = (args, cwd) => {
     const specs = [];
     const outs = [];
+    const langs = [];
     let unknown;
     let outWithoutValue = false;
+    let langWithoutValue = false;
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
-        if (arg === "--out") {
+        if (arg === "--out" || arg === "--lang") {
             const value = args[i + 1];
-            if (value === undefined || value.startsWith("--"))
-                outWithoutValue = true;
+            if (value === undefined || value.startsWith("--")) {
+                if (arg === "--out")
+                    outWithoutValue = true;
+                else
+                    langWithoutValue = true;
+            }
             else {
-                outs.push(value);
+                (arg === "--out" ? outs : langs).push(value);
                 i++;
             }
         }
@@ -56,11 +62,17 @@ export const parseCoverArgs = (args, cwd) => {
     const target = resolve(cwd, out);
     if (existsSync(target) && statSync(target).isDirectory())
         return { ok: false, problem: `the output is a folder: ${out}` };
+    if (langWithoutValue)
+        return { ok: false, problem: "--lang needs a value: <code>" };
+    if (langs.length > 1)
+        return { ok: false, problem: "--lang given more than once" };
+    if (langs.length === 1 && !LANGUAGE.test(langs[0]))
+        return { ok: false, problem: `--lang expects a language code such as pt or en, found ${langs[0]}` };
     if (specs.length === 0)
         return { ok: false, problem: "missing the cover spec: <spec.json>" };
     if (specs.length > 1)
         return { ok: false, problem: `one cover spec at a time, found ${specs.length}` };
-    return { ok: true, spec: specs[0], out };
+    return { ok: true, spec: specs[0], out, ...(langs.length === 1 ? { lang: langs[0] } : {}) };
 };
 /** Parses the spec text; a syntax error names the line and column. */
 const parseJson = (text, label) => {
@@ -82,14 +94,14 @@ const parseJson = (text, label) => {
     }
 };
 /** Builds the cover text for a spec file's contents, or the problem lines. */
-export const buildCover = (text, label) => {
+export const buildCover = (text, label, lang) => {
     const parsed = parseJson(text, label);
     if ("problem" in parsed)
         return { ok: false, lines: [parsed.problem] };
-    const problems = validateCoverSpec(parsed.value);
+    const problems = validateCoverSpec(parsed.value, { lang });
     if (problems.length > 0)
         return { ok: false, lines: problems.map((p) => `${p.path}: ${p.message}`) };
-    return { ok: true, svg: `${toSvg(coverTree(parsed.value))}\n` };
+    return { ok: true, svg: `${toSvg(coverTree(parsed.value, { lang }))}\n` };
 };
 export const runCover = (args, io) => {
     const invocation = parseCoverArgs(args, io.cwd);
@@ -108,7 +120,7 @@ export const runCover = (args, io) => {
         io.error(COVER_USAGE);
         return 1;
     }
-    const result = buildCover(text, invocation.spec);
+    const result = buildCover(text, invocation.spec, invocation.lang);
     if (!result.ok) {
         for (const line of result.lines)
             io.error(line);

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

@@ -2,8 +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"];
+/** Cover (800x420, the default), banner (1200x420, rounded corners), body diagram (560 laid out, 800 shown) or icon:
+ * spec cover-cli, "Banner output", "Diagram output", "Icon output". */
+export declare const FORMATS: readonly ["cover", "banner", "diagram", "icon"];
 export type CoverFormat = (typeof FORMATS)[number];
 export type CoverPiece = {
     piece: PieceName;
@@ -13,26 +14,64 @@ export type CustomNode = {
     attrs?: Record<string, unknown>;
     children?: (CustomNode | string)[];
 };
-export type CoverSpec = {
+export type CoverRings = {
+    cx: number;
+    cy: number;
+    radius?: number;
+};
+type SpecCommon = {
     id: string;
+    pieces: CoverPiece[];
+    /** One table per language; `"@key"` strings elsewhere are replaced for the language asked. */
+    text?: Record<string, Record<string, string | string[]>>;
+};
+type Framed = SpecCommon & {
     title: string;
     description: string;
-    format?: CoverFormat;
-    background: string;
-    rings: {
-        cx: number;
-        cy: number;
-        radius?: number;
-    };
-    pieces: CoverPiece[];
+    rings: CoverRings;
     custom?: CustomNode;
+    /** `custom` is drawn before `pieces[customAt]`; default after every piece. */
+    customAt?: number;
 };
+/** A cover spec, by format (spec cover-cli, "Cover spec format" and each format's keys). */
+export type CoverSpec = (Framed & {
+    format?: "cover" | "banner";
+    background: string;
+    height?: never;
+}) | (Framed & {
+    format: "diagram"; /** Layout units. */
+    height: number;
+    background?: never;
+}) | (SpecCommon & {
+    format: "icon";
+    /** Not in an eipIcon spec: the icon's own title and description, with the credit, are drawn. */
+    title?: string;
+    description?: string;
+    background?: never;
+    rings?: never;
+    custom?: never;
+    customAt?: never;
+    height?: never;
+});
 export declare const backgroundNames: () => string[];
 /** Compares JSON paths: segment by segment, array indexes as numbers, names by code point. */
 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[];
+/** A language of a text table and of `--lang`: `pt`, `en`, `pt-br`. */
+export declare const LANGUAGE: RegExp;
+export type CoverOptions = {
+    lang?: string;
+};
+/** Every problem of a parsed spec, sorted by path; empty when the spec is valid. `lang` picks a text table. */
+export declare const validateCoverSpec: (spec: unknown, options?: CoverOptions) => 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;
+/** Rings of a diagram (spec cover-cli, "Diagram rings at the shown scale"): the cover's step and width at the shown scale. */
+export declare const diagramRings: (cx: number, cy: number, height: number, radius?: number) => {
+    count: number;
+    step: number;
+    width: number;
+    radius: number;
+};
+/** The cover's (banner's, diagram's, icon's) node tree. The spec must be valid for `lang` (validateCoverSpec returned no problem). */
+export declare const coverTree: (input: CoverSpec, options?: CoverOptions) => SvgNode;
+export {};