@brunosouzas/design-system 0.3.2 → 0.4.0

package/README.md

@@ -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,7 +131,7 @@ 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 51 pieces, with their anchors, parameters and defaults, are listed in [design §4](openspec/changes/archive/2026-10-23-illustration-pieces/design.md) (the 26 cover pieces), in [design §3](openspec/changes/archive/2026-10-23-metro-and-diagram-pieces/design.md) of `metro-and-diagram-pieces` (the nine map and diagram pieces) and in [design §3, §5 and §6](openspec/changes/archive/2026-10-23-stackledger-map-and-link-pieces/design.md) of `stackledger-map-and-link-pieces` (the six markers, zones and icons) and in [design §3 to §5](openspec/changes/archive/2026-10-23-body-diagram-pieces/design.md) of `body-diagram-pieces` (the ten body diagram pieces); the rules are in [`openspec/specs/illustration-pieces/`](openspec/specs/illustration-pieces/spec.md). `npm run pieces:sheet -- --out <file.svg>` draws them all.
+- 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
 
@@ -160,7 +160,8 @@ Ten pieces draw what the blog's body diagrams need beyond the map pieces: `diagr
 - The shapes take one to three centred lines (`text`), an optional `subtitle` and `textSize`. Without `fill` the face is the surface's panel; with a fill, every word is ink.
 - Backticks mark code: `` "adopts a `correlationId`" `` draws `correlationId` in the monospace stack, as a `tspan`. An odd number of backticks is drawn as is.
 - Widths the piece estimates (`tagWidth`, `conditionWidth`, a label's `width`) can be passed by a caller that measures its text.
-- A body diagram is 800 wide. Lay it out in 560 units and show it 800 wide: the pieces then come out at the sizes of the published diagrams (text about 18, outline about 4); only the hard shadow is shallower (5 instead of 8).
+- A 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
 
@@ -180,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
@@ -195,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 {};

package/dist/src/pieces/cover.js

@@ -1,5 +1,6 @@
 // Cover specs (spec cover-cli; design §6): validation of the JSON a cover is
-// written in, and the 800x420 frame that draws it from the pieces.
+// written in, and the frames that draw it from the pieces: the 800x420 cover,
+// the banner, the body diagram and the icon (change designer-formats).
 //
 // Why here and not in scripts/: the validation and the frame are pure, so the
 // tests and a future site build can use them without the command line.
@@ -9,12 +10,16 @@
 // attributes, because the cover is published as SVG.
 import { tokens } from "../../tokens/generated/tokens.js";
 import { PIECE_NAMES, PIECES, rings } from "./library.js";
-import { el, g } from "./node.js";
+import { EIP_ICON_HEIGHT, EIP_ICON_WIDTH, EIP_ICONS } from "./eip-icons.js";
+import { LINK_ICON_SIZE } from "./link-icons.js";
+import { el, g, r2 } from "./node.js";
+import { UI_ICON_SIZE } from "./ui-icons.js";
 import { COLOUR_TOKENS, CURRENT_COLOUR, checkParams, isColourLiteral, MAX_SIZE, PATH_DATA } from "./params.js";
 export const SAFE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const TOP_LEVEL = ["id", "title", "description", "format", "background", "rings", "pieces", "custom"];
-/** Cover (800x420, the default) or banner (1200x420, rounded corners): spec cover-cli, "Banner output". */
-export const FORMATS = ["cover", "banner"];
+const TOP_LEVEL = ["id", "title", "description", "format", "background", "rings", "pieces", "custom", "customAt", "height", "text"];
+/** 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 const FORMATS = ["cover", "banner", "diagram", "icon"];
 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([
@@ -134,118 +139,278 @@ export const comparePaths = (a, b) => {
     }
     return left.length - right.length;
 };
-/** Every problem of a parsed spec, sorted by path; empty when the spec is valid. */
-export const validateCoverSpec = (spec) => {
-    if (!isPlainObject(spec))
-        return [{ path: "(root)", message: `a cover spec must be a JSON object, found ${Array.isArray(spec) ? "an array" : describe(spec)}` }];
+// ---------- text tables (spec cover-cli "Text tables", "Text references", "Language choice"; design §3) ----------
+/** A language of a text table and of `--lang`: `pt`, `en`, `pt-br`. */
+export const LANGUAGE = /^[a-z]{2}(-[a-z]{2})?$/;
+const TEXT_KEY = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const REFERENCE = /^@([A-Za-z][A-Za-z0-9_-]*)$/;
+const isTextValue = (value) => (typeof value === "string" && value !== "") ||
+    (Array.isArray(value) && value.length > 0 && Array.from({ length: value.length }, (_, i) => value[i]).every((item) => typeof item === "string" && item !== ""));
+/** The table `lang` picks, or the problems of the tables and of the language choice. */
+const pickTable = (spec, lang) => {
+    if (spec.text === undefined)
+        return { problems: lang === undefined ? [] : [{ path: "text", message: "--lang needs text tables" }] };
+    const text = spec.text;
+    if (!isPlainObject(text) || Object.keys(text).length === 0)
+        return { problems: [{ path: "text", message: "expected an object of languages (such as en, pt), each a table of text keys" }] };
+    const problems = [];
+    const tables = new Map();
+    for (const [code, table] of Object.entries(text)) {
+        if (!LANGUAGE.test(code))
+            problems.push({ path: `text.${code}`, message: "expected a language code such as pt or en" });
+        else if (!isPlainObject(table))
+            problems.push({ path: `text.${code}`, message: "expected an object of text keys" });
+        else
+            tables.set(code, table);
+    }
+    const keys = new Set();
+    for (const [code, table] of tables) {
+        for (const [key, value] of Object.entries(table)) {
+            keys.add(key);
+            if (!TEXT_KEY.test(key))
+                problems.push({ path: `text.${code}.${key}`, message: "expected a text key (a letter, then letters, digits, _ or -)" });
+            else if (!isTextValue(value))
+                problems.push({ path: `text.${code}.${key}`, message: "expected a non-empty string or a non-empty array of non-empty strings" });
+        }
+    }
+    for (const [code, table] of tables) {
+        for (const key of keys)
+            if (!Object.hasOwn(table, key))
+                problems.push({ path: `text.${code}.${key}`, message: "missing: another language defines it" });
+    }
+    if (problems.length > 0)
+        return { problems };
+    const codes = [...tables.keys()].sort().join(", ");
+    if (lang === undefined)
+        return { problems: [{ path: "text", message: `choose a language with --lang (${codes})` }] };
+    if (!tables.has(lang))
+        return { problems: [{ path: "text", message: `no table for ${lang} (${codes})` }] };
+    return { table: tables.get(lang), problems: [] };
+};
+/** The spec with every `@key` outside `text` replaced once by the table's value; unknown keys by path. */
+const resolveText = (spec, table) => {
+    const unknown = [];
+    const visit = (value, path) => {
+        if (typeof value === "string") {
+            const match = REFERENCE.exec(value);
+            if (!match)
+                return value;
+            if (!Object.hasOwn(table, match[1])) {
+                unknown.push({ path, message: `unknown text key ${match[1]}` });
+                return value;
+            }
+            const found = table[match[1]];
+            return Array.isArray(found) ? [...found] : found;
+        }
+        if (Array.isArray(value))
+            return Array.from({ length: value.length }, (_, i) => visit(value[i], `${path}[${i}]`));
+        if (isPlainObject(value))
+            return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, visit(child, path ? `${path}.${key}` : key)]));
+        return value;
+    };
+    const { text, ...rest } = spec;
+    return { spec: { ...visit(rest, ""), text }, unknown };
+};
+/** The spec the frame draws: resolved for `lang`, with the language in its id (decision 4). */
+const forLanguage = (spec, lang) => {
+    if (spec.text === undefined || lang === undefined)
+        return spec;
+    const resolved = resolveText(spec, spec.text[lang]).spec;
+    // The id may be a reference too: the language goes on the resolved id.
+    return { ...resolved, id: `${resolved.id}-${lang}` };
+};
+// ---------- validation ----------
+/** Icon pieces and the box each draws in (spec cover-cli, "Icon output"). */
+const ICON_PIECES = ["eipIcon", "uiIcon", "linkIcon"];
+const iconBox = (entry) => {
+    if (entry.piece === "eipIcon") {
+        const scale = entry.scale ?? 1;
+        return [EIP_ICON_WIDTH * scale, EIP_ICON_HEIGHT * scale];
+    }
+    const side = entry.size ?? (entry.piece === "uiIcon" ? UI_ICON_SIZE : LINK_ICON_SIZE);
+    return [side, side];
+};
+/** Problems of one `pieces` entry against its piece's parameters (spec cover-cli, "Piece parameters checked"). */
+const checkEntry = (piece, params, at, out) => {
+    const definition = PIECES[piece];
+    const own = checkParams(definition.schema, params, at);
+    // Every output is a standalone image: currentColor (accepted by uiIcon for inline page icons) is refused.
+    for (const [name, spec] of Object.entries(definition.schema)) {
+        if (spec.kind === "color" && spec.currentColor && params[name] === CURRENT_COLOUR) {
+            own.push({ path: `${at}.${name}`, message: "currentColor is for icons inline in a page; a cover uses a token path" });
+        }
+    }
+    out.push(...own);
+    // Limits between parameters are reported with the schema's problems, except on a parameter
+    // already reported; a relation that cannot read a broken parameter reports nothing.
+    let related = [];
+    if (definition.relations) {
+        try {
+            // A relation that reads a broken parameter may return anything: keep only real problems.
+            const found = definition.relations(params);
+            related = Array.isArray(found) ? found.filter((p) => isPlainObject(p) && typeof p.path === "string" && typeof p.message === "string") : [];
+        }
+        catch {
+            related = [];
+        }
+        const reported = new Set(own.map((problem) => problem.path));
+        out.push(...related.map((problem) => ({ path: `${at}.${problem.path}`, message: problem.message })).filter((problem) => !reported.has(problem.path)));
+    }
+    // A valid entry is drawn once: an overflow is a spec problem at the entry, not a crash.
+    if (own.length === 0 && related.length === 0) {
+        try {
+            PIECES[piece](params);
+        }
+        catch (error) {
+            if (error instanceof RangeError && error.message.endsWith(": the drawing overflows"))
+                out.push({ path: at, message: "the drawing overflows" });
+        }
+    }
+};
+const checkRings = (spec, out) => {
+    if (!isPlainObject(spec.rings))
+        return void out.push({ path: "rings", message: "missing or not an object (expected cx, cy and an optional radius)" });
+    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 spec keeps 0.1.0's ±10000, which bounds a banner's and a diagram's ring count.
+    for (const axis of ["cx", "cy"]) {
+        const value = spec.rings[axis];
+        if (ringProblems.some((p) => p.path === `rings.${axis}`) || typeof value !== "number")
+            continue;
+        if (value < -MAX_SIZE)
+            out.push({ path: `rings.${axis}`, message: `expected a number at least -${MAX_SIZE}, found ${value}` });
+        else if (value > MAX_SIZE)
+            out.push({ path: `rings.${axis}`, message: `expected a number at most ${MAX_SIZE}, found ${value}` });
+    }
+    if (Object.hasOwn(spec.rings, "color"))
+        out.push({ path: "rings.color", message: "unknown parameter: the ring colour comes from the background" });
+    if (Object.hasOwn(spec.rings, "count"))
+        out.push({ path: "rings.count", message: "unknown parameter: the ring count comes from the format" });
+};
+const NOT_FOR_ICONS = "not used by the icon format";
+const EIP_TEXT = "comes from the EIP icon, with its CC BY 4.0 credit";
+/** Every problem of a resolved spec (no text references left to resolve). */
+const validateResolved = (spec) => {
     const out = [];
+    const blocked = [];
     colourLiterals(spec, "", out);
     for (const key of Object.keys(spec)) {
         if (!TOP_LEVEL.includes(key))
             out.push({ path: key, message: `unknown key (expected ${TOP_LEVEL.join(", ")})` });
     }
+    if (spec.format !== undefined && (typeof spec.format !== "string" || !FORMATS.includes(spec.format))) {
+        out.push({ path: "format", message: `expected one of ${FORMATS.join(", ")}` });
+    }
+    // An unknown format is checked as a cover, as before this change.
+    const format = FORMATS.includes(spec.format) ? spec.format : "cover";
     if (typeof spec.id !== "string" || !SAFE_ID.test(spec.id))
         out.push({ path: "id", message: `expected a safe slug (lowercase letters, digits, single hyphens), found ${describe(spec.id)}` });
+    const pieces = spec.pieces;
+    const eipIconSpec = format === "icon" && Array.isArray(pieces) && pieces.length === 1 && isPlainObject(pieces[0]) && pieces[0].piece === "eipIcon";
     for (const key of ["title", "description"]) {
-        if (typeof spec[key] !== "string" || spec[key].trim() === "")
+        if (eipIconSpec) {
+            if (spec[key] !== undefined)
+                out.push({ path: key, message: EIP_TEXT });
+        }
+        else if (typeof spec[key] !== "string" || spec[key].trim() === "")
             out.push({ path: key, message: "expected a non-empty string" });
     }
-    if (typeof spec.background !== "string" || !backgroundNames().includes(spec.background)) {
-        out.push({ path: "background", message: `expected one of ${backgroundNames().join(", ")}, found ${describe(spec.background)}` });
+    if (format === "icon") {
+        for (const key of ["background", "rings", "custom", "customAt", "height"])
+            if (spec[key] !== undefined)
+                out.push({ path: key, message: NOT_FOR_ICONS });
+        for (const key of ["background", "rings", "custom"])
+            if (spec[key] !== undefined)
+                blocked.push(key);
     }
-    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" && 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"]) {
-            const value = spec.rings[axis];
-            if (ringProblems.some((p) => p.path === `rings.${axis}`) || typeof value !== "number")
-                continue;
-            if (value < -MAX_SIZE)
-                out.push({ path: `rings.${axis}`, message: `expected a number at least -${MAX_SIZE}, found ${value}` });
-            else if (value > MAX_SIZE)
-                out.push({ path: `rings.${axis}`, message: `expected a number at most ${MAX_SIZE}, found ${value}` });
+        if (format === "diagram") {
+            if (spec.background !== undefined)
+                out.push({ path: "background", message: "a diagram is drawn on color.panel; background is for covers and banners" });
+            const height = spec.height;
+            if (typeof height !== "number" || !Number.isFinite(height) || height < 1 || height > MAX_SIZE)
+                out.push({ path: "height", message: `expected a number from 1 to ${MAX_SIZE}` });
+        }
+        else {
+            if (typeof spec.background !== "string" || !backgroundNames().includes(spec.background)) {
+                out.push({ path: "background", message: `expected one of ${backgroundNames().join(", ")}, found ${describe(spec.background)}` });
+            }
+            if (spec.height !== undefined)
+                out.push({ path: "height", message: "only a diagram takes a height" });
+        }
+        checkRings(spec, out);
+        if (!isPlainObject(spec.rings) && spec.rings !== undefined)
+            blocked.push("rings");
+        if (spec.custom !== undefined) {
+            if (Array.isArray(spec.custom)) {
+                out.push({ path: "custom", message: "one free-form object per cover; a repeated object must be a piece" });
+                blocked.push("custom");
+            }
+            else
+                checkCustom(spec.custom, "custom", out);
+        }
+        if (spec.customAt !== undefined) {
+            const at = spec.customAt;
+            if (spec.custom === undefined)
+                out.push({ path: "customAt", message: "needs custom" });
+            else if (Array.isArray(pieces)) {
+                if (typeof at !== "number" || !Number.isInteger(at) || at < 0 || at > pieces.length)
+                    out.push({ path: "customAt", message: `expected an integer from 0 to ${pieces.length}` });
+            }
+            else if (typeof at !== "number" || !Number.isInteger(at) || at < 0) {
+                // Without a pieces array the count is unknown: the type is still checked.
+                out.push({ path: "customAt", message: "expected an integer from 0 to the number of pieces" });
+            }
         }
     }
-    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))
+    if (!Array.isArray(pieces)) {
         out.push({ path: "pieces", message: "missing or not an array" });
-    else
-        spec.pieces.forEach((entry, index) => {
+        if (pieces !== undefined)
+            blocked.push("pieces");
+    }
+    else if (format === "icon") {
+        const entry = pieces[0];
+        if (pieces.length !== 1 || !isPlainObject(entry) || !ICON_PIECES.includes(entry.piece)) {
+            out.push({ path: "pieces", message: "an icon spec holds exactly one piece: eipIcon, uiIcon or linkIcon" });
+            blocked.push("pieces");
+        }
+        else {
+            const { piece, ...params } = entry;
+            for (const axis of ["x", "y"])
+                if (params[axis] !== undefined && params[axis] !== 0)
+                    out.push({ path: `pieces[0].${axis}`, message: "an icon is drawn at 0, 0" });
+            checkEntry(piece, { ...params, x: 0, y: 0 }, "pieces[0]", out);
+        }
+    }
+    else {
+        for (let index = 0; index < pieces.length; index++) {
+            const entry = pieces[index];
             const at = `pieces[${index}]`;
-            if (!isPlainObject(entry))
-                return void out.push({ path: at, message: "expected an object with piece and its parameters" });
+            if (!isPlainObject(entry)) {
+                out.push({ path: at, message: "expected an object with piece and its parameters" });
+                blocked.push(at);
+                continue;
+            }
             const { piece, ...params } = entry;
             if (typeof piece !== "string" || !PIECE_NAMES.includes(piece)) {
-                return void out.push({ path: `${at}.piece`, message: `unknown piece ${describe(piece)} (expected one of ${PIECE_NAMES.join(", ")})` });
-            }
-            if (piece === "rings")
-                return void out.push({ path: `${at}.piece`, message: "rings belong to the cover's rings field" });
-            const definition = PIECES[piece];
-            const own = checkParams(definition.schema, params, at);
-            // A cover is a standalone image: currentColor (accepted by uiIcon for inline page icons) is refused.
-            for (const [name, spec] of Object.entries(definition.schema)) {
-                if (spec.kind === "color" && spec.currentColor && params[name] === CURRENT_COLOUR) {
-                    own.push({ path: `${at}.${name}`, message: "currentColor is for icons inline in a page; a cover uses a token path" });
-                }
-            }
-            out.push(...own);
-            // Limits between parameters are reported with the schema's problems, except on a parameter
-            // already reported; a relation that cannot read a broken parameter reports nothing.
-            if (definition.relations) {
-                let related = [];
-                try {
-                    related = definition.relations(params);
-                }
-                catch {
-                    related = [];
-                }
-                const reported = new Set(own.map((problem) => problem.path));
-                out.push(...related.map((problem) => ({ path: `${at}.${problem.path}`, message: problem.message })).filter((problem) => !reported.has(problem.path)));
+                out.push({ path: `${at}.piece`, message: `unknown piece ${describe(piece)} (expected one of ${PIECE_NAMES.join(", ")})` });
+                blocked.push(at);
+                continue;
             }
-            // A valid entry is drawn once: an overflow is a spec problem at the entry, not a crash.
-            if (own.length === 0 && !(definition.relations?.(params) ?? []).length) {
-                try {
-                    PIECES[piece](params);
-                }
-                catch (error) {
-                    if (error instanceof RangeError && error.message.endsWith(": the drawing overflows"))
-                        out.push({ path: at, message: "the drawing overflows" });
-                }
+            if (piece === "rings") {
+                out.push({ path: `${at}.piece`, message: "rings belong to the cover's rings field" });
+                blocked.push(at);
+                continue;
             }
-        });
-    if (spec.custom !== undefined) {
-        if (Array.isArray(spec.custom))
-            out.push({ path: "custom", message: "one free-form object per cover; a repeated object must be a piece" });
-        else
-            checkCustom(spec.custom, "custom", out);
-    }
-    // A colour literal is reported once, by the literal check, not again as a bad token path.
-    // A container with the wrong shape is one problem: nothing inside it is reported.
-    const blocked = [];
-    if (!Array.isArray(spec.pieces) && spec.pieces !== undefined)
-        blocked.push("pieces");
-    if (Array.isArray(spec.pieces)) {
-        spec.pieces.forEach((entry, index) => {
-            const known = isPlainObject(entry) && typeof entry.piece === "string" && PIECE_NAMES.includes(entry.piece) && entry.piece !== "rings";
-            if (!known)
-                blocked.push(`pieces[${index}]`);
-        });
+            checkEntry(piece, params, at, out);
+        }
     }
-    if (Array.isArray(spec.custom))
-        blocked.push("custom");
-    if (!isPlainObject(spec.rings) && spec.rings !== undefined)
-        blocked.push("rings");
-    const insideBlocked = (path) => blocked.some((b) => (path.startsWith(`${b}.`) || path.startsWith(`${b}[`)) && path !== `${b}.piece`);
-    out.splice(0, out.length, ...out.filter((p) => !insideBlocked(p.path)));
+    return { problems: out, blocked };
+};
+/** Under a path (the path itself included): `a` covers `a`, `a.b` and `a[0]`. */
+const under = (path, base) => path === base || path.startsWith(`${base}.`) || path.startsWith(`${base}[`);
+/** Sorted, one per path and message; a colour literal replaces any other problem at its path. */
+const finish = (out) => {
     const literalPaths = new Set(out.filter((p) => p.message.startsWith("colour literals")).map((p) => p.path));
     const seen = new Set();
     const unique = out.filter((p) => {
@@ -257,6 +422,26 @@ export const validateCoverSpec = (spec) => {
     });
     return unique.sort((a, b) => comparePaths(a.path, b.path) || compareCodePoints(a.message, b.message));
 };
+/** Every problem of a parsed spec, sorted by path; empty when the spec is valid. `lang` picks a text table. */
+export const validateCoverSpec = (spec, options = {}) => {
+    if (!isPlainObject(spec))
+        return [{ path: "(root)", message: `a cover spec must be a JSON object, found ${Array.isArray(spec) ? "an array" : describe(spec)}` }];
+    // Text problems stop the check: references cannot be resolved, so the rest would report false problems.
+    const { table, problems: textProblems } = pickTable(spec, options.lang);
+    if (textProblems.length > 0)
+        return finish(textProblems);
+    const { spec: resolved, unknown } = table ? resolveText(spec, table) : { spec, unknown: [] };
+    const { problems, blocked } = validateResolved(resolved);
+    // A container with the wrong shape is one problem: nothing inside it is reported (its `piece` problem stays).
+    // An unknown text key replaces every other problem at its path.
+    const insideBlocked = (path) => blocked.some((b) => under(path, b) && path !== b && path !== `${b}.piece`);
+    // Unknown references inside a wrong container are not reported either: the container is one problem.
+    // A reference in an entry's `piece` names the piece: it is reported even when its container is refused.
+    const unknownKept = unknown.filter((u) => !insideBlocked(u.path) || /^pieces\[\d+\]\.piece$/.test(u.path));
+    const kept = problems.filter((p) => !insideBlocked(p.path) && !unknownKept.some((u) => under(p.path, u.path)));
+    return finish([...kept, ...unknownKept]);
+};
+// ---------- drawing ----------
 const resolveCustom = (node) => {
     const attrs = {};
     for (const [name, value] of Object.entries(node.attrs ?? {})) {
@@ -273,28 +458,62 @@ export const bannerRingCount = (cx, cy, radius = tokens.cover.ringRadius) => {
     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) => {
+/** Layout units per shown pixel of a body diagram (560 / 800). */
+const LAYOUT_SCALE = tokens.bodyDiagram.layoutWidth / tokens.bodyDiagram.width;
+/** Rings of a diagram (spec cover-cli, "Diagram rings at the shown scale"): the cover's step and width at the shown scale. */
+export const diagramRings = (cx, cy, height, radius = tokens.bodyDiagram.ringRadius * LAYOUT_SCALE) => {
+    const width = tokens.bodyDiagram.layoutWidth;
+    const step = tokens.cover.ringStep * LAYOUT_SCALE;
+    const far = Math.max(...[[0, 0], [width, 0], [0, height], [width, height]].map(([x, y]) => Math.hypot(x - cx, y - cy)));
+    return { count: Math.max(1, Math.ceil((far - radius) / step) + 1), step, width: tokens.cover.ringWidth * LAYOUT_SCALE, radius };
+};
+const draw = (entry) => {
+    const { piece, ...params } = entry;
+    return PIECES[piece](params);
+};
+/** The outlined group's children: every body in paint order, `custom` before `pieces[customAt]` (default: last). */
+const bodies = (spec, drawnPieces) => {
+    const custom = spec.custom ? resolveCustom(spec.custom) : null;
+    const at = spec.customAt ?? drawnPieces.length;
+    return [...drawnPieces.slice(0, at).flatMap((d) => d.body), custom, ...drawnPieces.slice(at).flatMap((d) => d.body)];
+};
+const root = (id, width, height, viewBox, ...children) => el("svg", { xmlns: "http://www.w3.org/2000/svg", width, height, viewBox, role: "img", "aria-labelledby": `${id}-title ${id}-desc`, "font-family": tokens.font.sans }, ...children);
+/** An icon (spec cover-cli, "Icon output"): the piece at 0,0 in a box of its own size. */
+const iconTree = (spec) => {
+    const entry = spec.pieces[0];
+    const [width, height] = iconBox(entry);
+    const eip = entry.piece === "eipIcon" ? EIP_ICONS.find((icon) => icon.name === entry.name) : undefined;
+    return root(spec.id, width, height, `0 0 ${width} ${height}`, el("title", { id: `${spec.id}-title` }, eip?.title ?? spec.title), el("desc", { id: `${spec.id}-desc` }, eip?.description ?? spec.description), ...draw({ ...entry, x: 0, y: 0 }).body);
+};
+/** A body diagram (spec cover-cli, "Diagram output"): laid out 560 wide, shown 800 wide, on the panel. */
+const diagramTree = (spec) => {
+    const width = tokens.bodyDiagram.layoutWidth;
+    const height = spec.height;
+    const rx = r2(tokens.bodyDiagram.radius * LAYOUT_SCALE);
+    const frame = `url(#${spec.id}-frame)`;
+    const ring = diagramRings(spec.rings.cx, spec.rings.cy, height, spec.rings.radius);
+    const drawnPieces = spec.pieces.map(draw);
+    return root(spec.id, tokens.bodyDiagram.width, r2(height / LAYOUT_SCALE), `0 0 ${width} ${height}`, 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, rx }))), el("rect", { width, height, rx, fill: tokens.color.panel }), g({ "clip-path": frame }, g({ fill: "none", stroke: tokens.color.ring, "stroke-width": r2(ring.width) }, ...Array.from({ length: ring.count }, (_, i) => el("circle", { cx: spec.rings.cx, cy: spec.rings.cy, r: r2(ring.radius + i * ring.step) })))), g({ "clip-path": frame }, g({ stroke: tokens.color.ink, "stroke-width": tokens.map.outline, "stroke-linejoin": "round" }, ...bodies(spec, drawnPieces)), g({ "font-size": tokens.map.labelSize, "font-weight": tokens.cover.labelWeight, fill: tokens.color.ink, "text-anchor": "middle" }, ...drawnPieces.flatMap((d) => d.text))));
+};
+/** The cover's (banner's, diagram's, icon's) node tree. The spec must be valid for `lang` (validateCoverSpec returned no problem). */
+export const coverTree = (input, options = {}) => {
+    const spec = forLanguage(input, options.lang);
+    if (spec.format === "icon")
+        return iconTree(spec);
+    if (spec.format === "diagram")
+        return diagramTree(spec);
     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 drawnPieces = spec.pieces.map(draw);
     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 outlined = g({ stroke: tokens.color.ink, "stroke-width": tokens.outline.block, "stroke-linejoin": "round" }, ...bodies(spec, drawnPieces));
     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,
-        height,
-        viewBox: `0 0 ${width} ${height}`,
-        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, ...corner }))), el("rect", { width, height, ...corner, fill: pair.fill }), g({ "clip-path": frame }, ...rings({ ...spec.rings, color: ringPath, ...ringCount }).body), 
+    return root(spec.id, width, height, `0 0 ${width} ${height}`, 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/diagram.d.ts

@@ -101,6 +101,15 @@ export type EdgeLabelParams = {
 };
 /** Words next to an arrow: lines down from the baseline (x, y), optionally on a backdrop that hides what is behind. */
 export declare const edgeLabel: import("./piece.ts").Piece<EdgeLabelParams>;
+export type StateStartParams = {
+    cx: number;
+    cy: number;
+    r?: number;
+    surface?: SurfaceName;
+};
+/** The initial state of a state machine (change designer-formats, design §4): a filled dot in the surface's text
+ * colour, no outline (its own stroke none, so a cover's outlined group does not grow it), no shadow, no text. */
+export declare const stateStart: import("./piece.ts").Piece<StateStartParams>;
 /** The body diagram pieces, in catalogue order (design §3). */
 export declare const DIAGRAM_PIECES: {
     readonly diagramBox: import("./piece.ts").Piece<DiagramBoxParams>;

package/dist/src/pieces/diagram.js

@@ -194,5 +194,12 @@ export const edgeLabel = definePiece("edgeLabel", { x: pos(), y: pos(), lines: l
         : [];
     return drawn(body, rows.map((row, i) => words(x, y + i * 13 * k, row, { fill: s.text, "font-size": size_, "font-weight": bold, "text-anchor": anchor })));
 });
+/** Default start radius in layout units: the published dot (bodyDiagram.startRadius at the shown width) laid out at 560. */
+const START_RADIUS = (tokens.bodyDiagram.startRadius * tokens.bodyDiagram.layoutWidth) / tokens.bodyDiagram.width;
+/** The initial state of a state machine (change designer-formats, design §4): a filled dot in the surface's text
+ * colour, no outline (its own stroke none, so a cover's outlined group does not grow it), no shadow, no text. */
+export const stateStart = definePiece("stateStart", { cx: pos(), cy: pos(), r: size(), surface: surfaceParam }, ({ cx, cy, r = START_RADIUS, surface = "light" }) => 
+// The radius is written as given (a size, never rounded away); the centre is a position.
+drawn([el("circle", { cx: r2(cx), cy: r2(cy), r, fill: tokens.surface[surface].text, stroke: "none" })]));
 /** The body diagram pieces, in catalogue order (design §3). */
 export const DIAGRAM_PIECES = { diagramBox, decisionNode, storeNode, queueNode, exchangeNode, taggedContainer, lifeline, phaseBand, altFrame, edgeLabel };

package/dist/src/pieces/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 { FORMATS, SAFE_ID, backgroundNames, bannerRingCount, comparePaths, coverTree, validateCoverSpec, type CoverFormat, type CoverPiece, type CoverSpec, type CustomNode } from "./cover.ts";
+export { FORMATS, LANGUAGE, SAFE_ID, backgroundNames, bannerRingCount, comparePaths, coverTree, diagramRings, validateCoverSpec, type CoverFormat, type CoverOptions, type CoverPiece, type CoverRings, 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 { FORMATS, SAFE_ID, backgroundNames, bannerRingCount, comparePaths, coverTree, validateCoverSpec } from "./cover.js";
+export { FORMATS, LANGUAGE, SAFE_ID, backgroundNames, bannerRingCount, comparePaths, coverTree, diagramRings, validateCoverSpec } from "./cover.js";
 export { tokens } from "../../tokens/generated/tokens.js";

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

@@ -325,6 +325,7 @@ export declare const PIECES: {
     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>;
+    readonly stateStart: import("./piece.ts").Piece<import("./diagram.ts").StateStartParams>;
 };
 export type PieceName = keyof typeof PIECES;
 export declare const PIECE_NAMES: PieceName[];

package/dist/src/pieces/library.js

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

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

@@ -4,6 +4,13 @@ export declare const tokens: {
         readonly radius: 20;
         readonly width: 1200;
     };
+    readonly bodyDiagram: {
+        readonly layoutWidth: 560;
+        readonly radius: 14;
+        readonly ringRadius: 70;
+        readonly startRadius: 11;
+        readonly width: 800;
+    };
     readonly color: {
         readonly backend: "#FF6B6B";
         readonly blocked: "#FF8A3D";

package/dist/tokens/generated/tokens.js

@@ -5,6 +5,13 @@ export const tokens = {
         "radius": 20,
         "width": 1200
     },
+    "bodyDiagram": {
+        "layoutWidth": 560,
+        "radius": 14,
+        "ringRadius": 70,
+        "startRadius": 11,
+        "width": 800
+    },
     "color": {
         "backend": "#FF6B6B",
         "blocked": "#FF8A3D",

package/package.json

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

@@ -3,6 +3,11 @@
   --ds-banner-height: 420px;
   --ds-banner-radius: 20px;
   --ds-banner-width: 1200px;
+  --ds-body-diagram-layout-width: 560px;
+  --ds-body-diagram-radius: 14px;
+  --ds-body-diagram-ring-radius: 70px;
+  --ds-body-diagram-start-radius: 11px;
+  --ds-body-diagram-width: 800px;
   --ds-color-backend: #FF6B6B;
   --ds-color-blocked: #FF8A3D;
   --ds-color-caller: #8FB2FF;

package/tokens/generated/tokens.json

@@ -4,6 +4,13 @@
     "radius": 20,
     "width": 1200
   },
+  "bodyDiagram": {
+    "layoutWidth": 560,
+    "radius": 14,
+    "ringRadius": 70,
+    "startRadius": 11,
+    "width": 800
+  },
   "color": {
     "backend": "#FF6B6B",
     "blocked": "#FF8A3D",

package/tokens/generated/tokens.ts

@@ -6,6 +6,13 @@ export const tokens = {
     "radius": 20,
     "width": 1200
   },
+  "bodyDiagram": {
+    "layoutWidth": 560,
+    "radius": 14,
+    "ringRadius": 70,
+    "startRadius": 11,
+    "width": 800
+  },
   "color": {
     "backend": "#FF6B6B",
     "blocked": "#FF8A3D",