@brunosouzas/design-system 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Bruno Souza
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/README.md

@@ -1,3 +1,212 @@
-# Temporary Holding Version
+# brunosouzas-design-system
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/brunosouzas/brunosouzas-design-system/actions/workflows/ci.yml/badge.svg)](https://github.com/brunosouzas/brunosouzas-design-system/actions/workflows/ci.yml)
+[![OpenSpec](https://github.com/brunosouzas/brunosouzas-design-system/actions/workflows/openspec.yml/badge.svg)](https://github.com/brunosouzas/brunosouzas-design-system/actions/workflows/openspec.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+The visual identity of [brunosouzas.com](https://brunosouzas.com): design tokens, and animated explainers made with code.
+
+![Four frames of the animated circuit-breaker state machine: CLOSED collecting call results, the arrow to OPEN, HALF_OPEN testing calls, and the full loop back to CLOSED.](docs/spikes/2026-10-22-motion-pilot/contact-sheet-16x9-en.png)
+
+## Contents
+
+- [Status](#status)
+- [What it is](#what-it-is)
+- [How it works](#how-it-works)
+- [Install](#install)
+- [Commands](#commands)
+- [How a scene is built](#how-a-scene-is-built)
+- [Illustration pieces and covers](#illustration-pieces-and-covers)
+- [Decisions](#decisions)
+- [How this project is built](#how-this-project-is-built)
+- [Security](#security)
+- [Contributing](#contributing)
+- [Licence](#licence)
+
+## 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).
+
+## What it is
+
+The blog's articles explain how systems behave: a circuit breaker opening, a pipeline promoting a build, a message being retried. Static diagrams show the states; an animation shows the change. This repository keeps both in one visual language, so a reader recognises the site in an article, on LinkedIn and on a slide.
+
+- **Design tokens, one source.** Colours with fixed meanings (green healthy, orange blocked, yellow transitional, red the failure path), the Lato type scale, the thick ink outline, the hard offset shadow, radii, and motion timings. Exported as CSS variables for the site, TypeScript for the animations and JSON for anything else (the SVG generators of the static diagrams).
+- **Motion components.** React components for [Remotion](https://www.remotion.dev): an ink block with a hard shadow, a pill label, an arrow that draws itself, a token travelling along a transition, call-result squares, a countdown ring. Flow primitives in `src/brand/flow-components.tsx` add a white hexagonal `Exchange`, rail-ended `Queue`, yellow-tab `TaggedContainer` and persistent `PositionedToken` (stationary or path-positioned). Copy identities, splits and ACK/NACK rules belong to scenes, not to a generic message engine.
+- **Illustration pieces.** The objects the blog's covers and diagrams draw again and again (pill label, sheet, code panel, robot, server stack, gear, road, the 26 EIP icons and more), each a pure TypeScript function that returns an SVG node tree from the tokens. The same tree becomes an SVG file for a cover and React elements for a scene, and a scene animates a piece by recomputing its parameters every frame. See [Illustration pieces and covers](#illustration-pieces-and-covers).
+- **A catalogue of scenes.** Each scene animates something a published article already says, in 16:9 (article) and 4:5 (LinkedIn), in Portuguese and English from one text table. The first is the [circuit-breaker state machine](docs/spikes/2026-10-22-motion-pilot/README.md).
+
+The style follows the illustration covers of the [Spotify Engineering blog](https://engineering.atspotify.com/): flat shapes, a dark ink outline, a hard shadow with no blur, saturated colours on a calm page.
+
+## How it works
+
+```text
+tokens/source.json ──► tokens/generated/tokens.css  ──► brunosouzas.com (site repository, planned)
+                   ├─► tokens/generated/tokens.ts   ──► src/brand (motion components) ──► src/scenes ──► MP4 per format and language
+                   └─► tokens/generated/tokens.json ──► other scripts
+
+src/pieces (pure functions → SVG node tree) ──► toSvg   ──► covers (npm run cover), diagrams
+                                            └─► toReact ──► Remotion scenes
+```
+
+The generated files are committed, so a consumer can read them without running Node. CSS custom properties carry the prefix `--ds-` (for example `--ds-color-ink`, `--ds-motion-pop-damping`) so they do not clash with the site's own theme names.
+
+## Install
+
+The tokens and the illustration pieces are published on npm as [`@brunosouzas/design-system`](https://www.npmjs.com/package/@brunosouzas/design-system), with provenance; releases follow [docs/release.md](docs/release.md). The package has no runtime dependency: Remotion, the motion components and the scenes stay in this repository.
+
+```bash
+npm install @brunosouzas/design-system
+```
+
+| Import | What it gives |
+|---|---|
+| `@brunosouzas/design-system` | the pieces, `toSvg`, `pose`, the cover spec helpers and `tokens` |
+| `@brunosouzas/design-system/react` | `toReact`, for React and Remotion (needs `react` 19) |
+| `@brunosouzas/design-system/tokens` | the typed `tokens` object |
+| `@brunosouzas/design-system/tokens.css` | the `--ds-*` custom properties |
+| `@brunosouzas/design-system/tokens.json` | the plain values |
+
+```ts
+import { pill, toSvg, tokens } from "@brunosouzas/design-system";
+const label = pill({ x: 60, y: 30, text: "main" });
+```
+
+The package also installs the cover command as `brunosouzas-cover <spec.json> --out <file.svg>`.
+
+## Commands
+
+Requirements: Node.js 22.12 or later. Rendering also needs the network: Remotion downloads its headless browser on first use, and every render fetches Lato from Google Fonts.
+
+```bash
+npm ci                                            # install the pinned dependencies
+npm run tokens                                    # validate tokens/source.json and write tokens/generated/
+npm run tokens:check                              # fail if tokens/generated/ is stale (CI runs this)
+npm run typecheck                                 # tsc over src/, scripts/ and test/
+npm test                                          # unit and integration tests (no rendering, no network)
+npm run stills -- circuit-breaker-states          # key-frame PNGs to out/stills/<composition>/<frame>.png
+npm run render -- circuit-breaker-states          # out/master/<id>.mp4 and the web copy out/web/<id>.mp4
+npm run stills -- publish-subscribe               # 24 phase/final PNGs (six per composition)
+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 pieces:sheet -- --out out/pieces.svg      # every piece once, labelled, for review
+npm run studio                                    # Remotion Studio, for frame-by-frame review
+```
+
+- Change a token value in `tokens/source.json` and run `npm run tokens`; never edit `tokens/generated/` by hand. An invalid source prints every problem and writes nothing.
+- `stills` and `render` take one scene name and an optional `--dry-run`, which prints the commands without running them. A render writes a hardware-encoded master (about 28 MB for 33 s) and an x264 web copy (under 1 MB) made with the ffmpeg bundled with Remotion, and prints one line per composition with its time and sizes. The four circuit-breaker clips take about four to five minutes on an Apple M3.
+- Everything rendered goes to `out/`, which Git ignores.
+
+## How a scene is built
+
+The catalogue contains:
+
+| Scene | Sources | Review status |
+|---|---|---|
+| `circuit-breaker-states` | [EN](https://brunosouzas.com/blog/circuit-breaker-in-mulesoft), [PT](https://brunosouzas.com/pt/blog/circuit-breaker-in-mulesoft) | approved pilot, unchanged |
+| `publish-subscribe` | [EN](https://brunosouzas.com/wiki/publish-subscribe-in-mulesoft/), [PT](https://brunosouzas.com/pt/wiki/publish-subscribe-in-mulesoft/) and their Anypoint MQ diagrams | owner media gate pending |
+
+Studio lists four compositions per scene in catalogue order. Pub-sub runs for 1000 frames at 30 fps, with the final 90 frames static. It depicts the article's AUTO acknowledgment case with a propagated invoice error, not every acknowledgment mode. Publish confirms exchange acceptance, not queue delivery. No redelivery is animated. After owner stills approval, `npm run render -- publish-subscribe` produces the four masters and four web copies; do not run it before that gate.
+
+A scene lives in `src/scenes/<scene>/` with:
+
+- `scene.ts`: the scene data, with no React: id, formats, languages, the timeline in frames, the text table per language (every string taken from the article) and the source article URL per language.
+- `layout.ts`: one layout per format, in composition pixels; the 4:5 layout has its own arrow routes.
+- `Scene.tsx`: the composition, which arranges the components from `src/brand/`.
+
+`src/scenes/index.ts` lists the scenes and `src/Root.tsx` registers each one as a Studio folder with one composition per format and language (`<scene>-16x9-pt`, `-16x9-en`, `-4x5-pt`, `-4x5-en`). The tests check every registered scene: the same text keys in both languages, phases inside the composition and in order, events inside phases, and a reading hold of at least three seconds at the end.
+
+`SceneContract<TTimeline>` supplies common metadata and phase ranges (`from`, `to`, events with `at`), duration and outro. `SceneData` remains the legacy state-machine alias with `Timeline`: states, slots, call results and transition fires retain their window checks. `CatalogueScene` also accepts `FlowSceneData` with `kind: "flow"`; it needs no active states or slots. The flow validator rejects unknown endpoints, invalid frames/ranges, trips crossing the outro, and impossible copy ownership/handoffs. There is no plug-in or graph-interpreter API.
+
+Pub-sub separates `text.ts`, `timeline.ts` and pure `flow.ts` from its data entry. Half-open ownership intervals transfer each token atomically at split/arrival/ACK/NACK boundaries. Caption windows use phase ids internally, never as visible labels; captions and labels are frozen against source fixtures. Both media scripts consume only common phase ends and duration, without React or fonts.
+
+The components take every colour and size from the tokens, and what is visible at a frame (arrow progress, travelling tokens, focus and dimming, captions, countdown, call results) comes from pure functions in `src/brand/motion.ts`, which the tests check without rendering.
+
+## Illustration pieces and covers
+
+`src/pieces/` holds the drawing library. A piece is a function from plain parameters to `{ body, text }`: `body` holds the shapes, drawn inside the outlined group, and `text` the words and glyphs, drawn after every shape so the outline never strokes a letter. Pieces read only the generated tokens and never a file, so a Remotion scene can import them.
+
+- `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.
+
+### 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.
+
+- `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).
+- `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.
+
+```ts
+import { lineBadge, pipe, stationMarker, toSvg } from "@brunosouzas/design-system";
+const line = pipe({ d: "M20,40 L220,40", fill: "#7B3FE4" });
+const stop = stationMarker({ cx: 120, cy: 40, surface: "dark" });
+const badge = lineBadge({ x: 250, y: 40, text: "SH", fill: "#7B3FE4", surface: "dark" });
+```
+
+### 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.
+
+```json
+{
+  "id": "sdd",
+  "title": "A one-line request becomes a reviewed spec before any code",
+  "description": "Illustration. On the left, a small slip …",
+  "background": "blush",
+  "rings": { "cx": 400, "cy": 220, "radius": 96 },
+  "pieces": [
+    { "piece": "speechBubble", "x": 52, "y": 174, "width": 160, "height": 74 },
+    { "piece": "pill", "x": 132, "y": 174, "text": "request", "width": 104 }
+  ]
+}
+```
+
+- `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.
+- `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.
+- The three published covers that proved the pieces are the test fixtures in `test/fixtures/covers/`.
+
+### 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.
+
+### 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.
+
+## Decisions
+
+Project-wide decisions are recorded as ADRs in [`docs/adr/`](docs/adr/README.md).
+
+- **Animations are code, made with Remotion.** A scene is React components and data, so a correction is a re-render and every format and language comes from one composition. AI video generators were rejected because their outputs are not consistent between clips. [ADR 0001](docs/adr/0001-remotion-for-motion.md)
+- **One token source.** Colours, type, outline, shadow and motion timings live in one file; the site, the animations and the SVG scripts read generated exports instead of keeping their own copies. [ADR 0002](docs/adr/0002-one-token-source.md)
+- **One visual language, fixed colour meanings.** Green is always healthy, orange always blocked, red always the failure path, so a reader learns the code once. Rotated text is allowed since the 2026-10-23 amendment. [ADR 0003](docs/adr/0003-visual-language-and-colour-meaning.md)
+- **Scenes illustrate published articles.** Every string on screen comes from the article, so an animation never says more than the reviewed text. [ADR 0004](docs/adr/0004-scenes-illustrate-published-articles.md)
+
+## How this project is built
+
+- Changes are specified first with [OpenSpec](https://github.com/Fission-AI/OpenSpec): active changes in [`openspec/changes/`](openspec/changes/), the current behaviour in [`openspec/specs/`](openspec/specs/).
+- Decisions: [`docs/adr/`](docs/adr/README.md).
+- Order of work: [`docs/roadmap.md`](docs/roadmap.md).
+- Evidence from experiments: [`docs/spikes/`](docs/spikes/).
+
+## Security
+
+No secrets, credentials or telemetry belong in this repository. Report a vulnerability privately: see [SECURITY.md](SECURITY.md).
+
+## Contributing
+
+Issues and pull requests are welcome, especially corrections and ideas for the components. The scenes illustrate the author's own articles, so new scenes come from the blog.
+
+## Licence
+
+Code and tokens: [Apache-2.0](LICENSE). The identity (the look of brunosouzas.com) is also the look of the author's other products, such as [stackledger](https://github.com/brunosouzas/stackledger), whose generated sites carry it. The licence does not grant use of the name or of the brunosouzas.com identity as someone else's brand: to build your own, fork it and change the token values.
+
+The animations use [Remotion](https://www.remotion.dev), which has its own licence: free for individuals and for companies of up to three people, a company licence above that ([terms](https://www.remotion.dev/docs/license)). Check it before you render with this code at work.

package/dist/scripts/cover.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+export declare const COVER_USAGE = "usage: npm run cover -- <spec.json> --out <file.svg>";
+export type CoverIo = {
+    cwd: string;
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+/** The first invocation problem, in the order of the spec, or the two paths. */
+export declare const parseCoverArgs: (args: string[], cwd: string) => {
+    ok: true;
+    spec: string;
+    out: 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) => {
+    ok: true;
+    svg: string;
+} | {
+    ok: false;
+    lines: string[];
+};
+export declare const runCover: (args: string[], io: CoverIo) => number;

package/dist/scripts/cover.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// `npm run cover -- <spec.json> --out <file.svg>`, 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.
+//
+// Why: covers were drawn by hand and drifted; a spec plus the shared pieces
+// makes every cover reproducible, and only the pieces live in this public
+// repository.
+//
+// What can go wrong: a bad invocation reports its first problem with the
+// usage; an invalid spec reports every problem by JSON path. In both cases the
+// command exits 1 and writes nothing. An existing output file is replaced.
+import { closeSync, existsSync, openSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+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 { toSvg } from "../src/pieces/render.js";
+export const COVER_USAGE = "usage: npm run cover -- <spec.json> --out <file.svg>";
+/** The first invocation problem, in the order of the spec, or the two paths. */
+export const parseCoverArgs = (args, cwd) => {
+    const specs = [];
+    const outs = [];
+    let unknown;
+    let outWithoutValue = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--out") {
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith("--"))
+                outWithoutValue = true;
+            else {
+                outs.push(value);
+                i++;
+            }
+        }
+        else if (arg.startsWith("-"))
+            unknown ??= arg;
+        else
+            specs.push(arg);
+    }
+    if (unknown !== undefined)
+        return { ok: false, problem: `unknown option ${unknown}` };
+    if (outWithoutValue)
+        return { ok: false, problem: "--out needs a value: <file.svg>" };
+    if (outs.length === 0)
+        return { ok: false, problem: "--out <file.svg> is required" };
+    if (outs.length > 1)
+        return { ok: false, problem: "--out given more than once" };
+    const out = outs[0];
+    if (!out.endsWith(".svg"))
+        return { ok: false, problem: `the output must be an .svg file, found ${out}` };
+    const folder = dirname(resolve(cwd, out));
+    if (!existsSync(folder) || !statSync(folder).isDirectory())
+        return { ok: false, problem: `the output folder does not exist: ${dirname(out)}` };
+    const target = resolve(cwd, out);
+    if (existsSync(target) && statSync(target).isDirectory())
+        return { ok: false, problem: `the output is a folder: ${out}` };
+    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 };
+};
+/** Parses the spec text; a syntax error names the line and column. */
+const parseJson = (text, label) => {
+    try {
+        return { value: JSON.parse(text) };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const lineColumn = /line (\d+) column (\d+)/.exec(message);
+        const position = /position (\d+)/.exec(message);
+        let where = "";
+        if (lineColumn)
+            where = ` at line ${lineColumn[1]}, column ${lineColumn[2]}`;
+        else if (position) {
+            const before = text.slice(0, Number(position[1])).split("\n");
+            where = ` at line ${before.length}, column ${before[before.length - 1].length + 1}`;
+        }
+        return { problem: `${label}: invalid JSON${where} (${message})` };
+    }
+};
+/** Builds the cover text for a spec file's contents, or the problem lines. */
+export const buildCover = (text, label) => {
+    const parsed = parseJson(text, label);
+    if ("problem" in parsed)
+        return { ok: false, lines: [parsed.problem] };
+    const problems = validateCoverSpec(parsed.value);
+    if (problems.length > 0)
+        return { ok: false, lines: problems.map((p) => `${p.path}: ${p.message}`) };
+    return { ok: true, svg: `${toSvg(coverTree(parsed.value))}\n` };
+};
+export const runCover = (args, io) => {
+    const invocation = parseCoverArgs(args, io.cwd);
+    if (!invocation.ok) {
+        io.error(invocation.problem);
+        io.error(COVER_USAGE);
+        return 1;
+    }
+    const specPath = resolve(io.cwd, invocation.spec);
+    let text;
+    try {
+        text = readFileSync(specPath, "utf8");
+    }
+    catch (error) {
+        io.error(`cannot read ${invocation.spec}: ${error instanceof Error ? error.message : String(error)}`);
+        io.error(COVER_USAGE);
+        return 1;
+    }
+    const result = buildCover(text, invocation.spec);
+    if (!result.ok) {
+        for (const line of result.lines)
+            io.error(line);
+        io.error(`cover: ${result.lines.length} problem(s) in ${invocation.spec}; no file written`);
+        return 1;
+    }
+    // Write beside the target and rename, so a failed write never leaves half a cover.
+    const target = resolve(io.cwd, invocation.out);
+    // Unpredictable name, created exclusively ("wx"): never follows or reuses an existing path.
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    let created = false;
+    try {
+        const fd = openSync(temporary, "wx");
+        created = true; // ours from here on: remove it on any later failure
+        try {
+            // writeFileSync on a descriptor loops until every byte is written (writeSync may write fewer).
+            writeFileSync(fd, result.svg);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temporary, target);
+    }
+    catch (error) {
+        if (created)
+            rmSync(temporary, { force: true });
+        io.error(`cannot write ${invocation.out}: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+    io.log(`wrote ${invocation.out}`);
+    return 0;
+};
+// Real paths on both sides: an installed bin is a symlink in node_modules/.bin.
+const isMain = (() => {
+    if (process.argv[1] === undefined)
+        return false;
+    try {
+        return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+    }
+    catch {
+        return false;
+    }
+})();
+if (isMain) {
+    process.exitCode = runCover(process.argv.slice(2), { cwd: process.env.INIT_CWD ?? process.cwd(), log: console.log, error: console.error });
+}

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

@@ -0,0 +1,32 @@
+import { type PieceName } from "./library.ts";
+import { type SvgNode } from "./node.ts";
+import { type Problem } from "./params.ts";
+export declare const SAFE_ID: RegExp;
+export type CoverPiece = {
+    piece: PieceName;
+} & Record<string, unknown>;
+export type CustomNode = {
+    tag: string;
+    attrs?: Record<string, unknown>;
+    children?: (CustomNode | string)[];
+};
+export type CoverSpec = {
+    id: string;
+    title: string;
+    description: string;
+    background: string;
+    rings: {
+        cx: number;
+        cy: number;
+        radius?: number;
+    };
+    pieces: CoverPiece[];
+    custom?: CustomNode;
+};
+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[];
+/** The cover's node tree. The spec must be valid (validateCoverSpec returned no problem). */
+export declare const coverTree: (spec: CoverSpec) => SvgNode;