geneseed 5.5.0 → 5.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +9 -9
  3. package/SHIPPED.md +1 -1
  4. package/docs/extending.md +1 -1
  5. package/docs/guides/install.md +5 -5
  6. package/docs/reference/profiles.md +84 -0
  7. package/harness.config.json +1 -1
  8. package/js/build/export.mjs +11 -16
  9. package/js/hosts/hooks.mjs +4 -1
  10. package/package.json +1 -1
  11. package/profiles/autonomous.json +14 -0
  12. package/profiles/corporate.json +14 -0
  13. package/profiles/mentor.json +13 -0
  14. package/profiles/minimal.json +15 -0
  15. package/src/agents/devops-engineer.md +6 -5
  16. package/src/agents/kubernetes-specialist.md +3 -1
  17. package/src/agents/spring-boot-engineer.md +3 -3
  18. package/src/agents/spring-reviewer.md +4 -2
  19. package/src/skills/codebase-design.md +2 -2
  20. package/src/skills/diagram-design/SKILL.md +12 -7
  21. package/src/skills/diagram-design/VENDOR.md +19 -14
  22. package/src/skills/diagram-design/references/layout-budget.md +7 -1
  23. package/src/skills/diagram-design/references/onboarding.md +1 -1
  24. package/src/skills/diagram-design/references/primitives-core.md +1 -1
  25. package/src/skills/diagram-design/references/semantic-patterns.md +1 -1
  26. package/src/skills/diagram-design/references/style-guide.md +1 -1
  27. package/src/skills/diagram-design/references/type-dependency.md +69 -0
  28. package/src/skills/diagram-design/references/type-event-modeling.md +36 -0
  29. package/src/skills/diagram-design/references/type-requirement-traceability.md +45 -0
  30. package/src/skills/diagram-design/references/type-sbgn.md +80 -0
  31. package/src/skills/diagram-design/references/type-scatter.md +1 -1
  32. package/src/skills/diagram-design/references/type-steps.md +180 -0
  33. package/src/skills/diagram-design/references/type-unit-grid.md +63 -0
  34. package/src/skills/geneseed-code-review.md +2 -1
  35. package/src/skills/parallel-agents.md +1 -1
  36. package/src/skills/react-view-transitions/AGENTS.md +26 -26
  37. package/src/skills/react-view-transitions/SKILL.md +1 -1
  38. package/src/skills/react-view-transitions/VENDOR.md +12 -3
  39. package/src/skills/spring-boot/cloud.md +19 -1
  40. package/src/skills/spring-boot/logging.md +5 -3
  41. package/src/skills/spring-boot/web.md +27 -2
  42. package/src/skills/spring-boot.md +4 -2
  43. package/src/skills/spring-data-jpa.md +18 -4
  44. package/src/skills/spring-testing.md +4 -0
  45. package/src/upstreams.json +4 -4
  46. package/web/dist/assets/{Activity-LKsDzsnK.js → Activity-bUSPM3Dl.js} +1 -1
  47. package/web/dist/assets/{ActivityDetail-DhwTfPm6.js → ActivityDetail-AHRoXeFN.js} +1 -1
  48. package/web/dist/assets/{Bonsai-CePMLrpr.js → Bonsai-B5XY9pid.js} +1 -1
  49. package/web/dist/assets/{CopyButton-CuoaJ6k7.js → CopyButton-C0wwRR9H.js} +1 -1
  50. package/web/dist/assets/{Dashboard-D1VKuvLe.js → Dashboard-DPAA96EI.js} +2 -2
  51. package/web/dist/assets/{Docs-CUrHJKaU.js → Docs-CpGDq165.js} +1 -1
  52. package/web/dist/assets/{Factories-Ci1XfmSy.js → Factories-cNhETa5Q.js} +1 -1
  53. package/web/dist/assets/{GreenhouseView-CNfH2lPK.js → GreenhouseView-DO3ADmT9.js} +1 -1
  54. package/web/dist/assets/{Installs-ZHQZM1iS.js → Installs-D3dDyq10.js} +1 -1
  55. package/web/dist/assets/{JournalView-CMsWahkS.js → JournalView--W-Lw_V9.js} +1 -1
  56. package/web/dist/assets/{Kits-CkliyK0n.js → Kits-ChfehxY6.js} +1 -1
  57. package/web/dist/assets/Laws-CNxYmV36.js +4 -0
  58. package/web/dist/assets/{LibRows-Brv0Hmkr.js → LibRows-CiPvsRYB.js} +1 -1
  59. package/web/dist/assets/{Library-BYmiLjJr.js → Library-BxQvbwVU.js} +1 -1
  60. package/web/dist/assets/{Loops-ytm-xJ68.js → Loops-DAblKkyq.js} +1 -1
  61. package/web/dist/assets/{OperatorHudView-KaqCx_HP.js → OperatorHudView-QtSaSyYm.js} +1 -1
  62. package/web/dist/assets/{Personal-CmcnRKYE.js → Personal-DxSGv638.js} +1 -1
  63. package/web/dist/assets/{Settings-tUrpdOfq.js → Settings-CgTbhvRv.js} +1 -1
  64. package/web/dist/assets/{Tabs-CD7etcGD.js → Tabs-Cf4X1hdz.js} +1 -1
  65. package/web/dist/assets/{index-COKbhFNo.js → index-B_pTwZra.js} +3 -3
  66. package/web/dist/assets/index-CzfImiYb.css +1 -0
  67. package/web/dist/index.html +2 -2
  68. package/web/dist/assets/Laws-hh4O3HZ4.js +0 -4
  69. package/web/dist/assets/index-Ba_Kg3Af.css +0 -1
@@ -21,19 +21,20 @@ The skill follows the [Agent Skills](https://agentskills.io/) format (`SKILL.md`
21
21
 
22
22
  ## What was trimmed
23
23
 
24
- Upstream's `skills/diagram-design/` is about 5.9 MB. This copy keeps about 0.8 MB:
24
+ Upstream's `skills/diagram-design/` is about 6.4 MB. This copy keeps about 0.8 MB:
25
25
 
26
- - **Kept:** `SKILL.md`; every `references/*.md` except the six below; the five
26
+ - **Kept:** `SKILL.md`; every `references/*.md` except the seven below; the five
27
27
  `assets/template*.html` files (§10 tells the agent to copy them); two examples,
28
28
  `assets/example-venn.html` and `assets/example-architecture.html`.
29
- - **Dropped:** `scripts/` (six Python helpers — Geneseed carries no Python at runtime); the other
30
- ~218 `assets/example-*.html` files and `assets/icons.html` (a gallery of the icons
31
- `references/primitive-icons.md` already holds); `references/export.md` and
32
- `references/export-registry.md` (the Python/Playwright export helpers); `references/doctor.md`
33
- (Python and host-plugin diagnostics); `references/import-drawio.md`,
34
- `references/import-mermaid.md` and `references/import-excalidraw.md` (built around the
35
- Python extractors). Upstream's repository files (plugin manifests, `commands/`, `prompts/`,
36
- `docs/`, the repository-level `scripts/verify-*.py`) were never part of the skill folder.
29
+ - **Dropped:** `scripts/` (eight Python helpers — Geneseed carries no Python at runtime); the other
30
+ ~230 `assets/example-*.html` files, `assets/index.html` (the example gallery) and
31
+ `assets/icons.html` (a gallery of the icons `references/primitive-icons.md` already holds);
32
+ `references/export.md` and `references/export-registry.md` (the Python/Playwright export
33
+ helpers); `references/doctor.md` (Python and host-plugin diagnostics);
34
+ `references/import-drawio.md`, `references/import-mermaid.md`, `references/import-excalidraw.md`
35
+ and `references/import-plantuml.md` (built around the Python extractors). Upstream's
36
+ repository files (plugin manifests, `commands/`, `prompts/`, `docs/`, the repository-level
37
+ `scripts/verify-*.py`) were never part of the skill folder.
37
38
 
38
39
  SKILL.md §10 and some references still name `example-<type>.html` files and `assets/icons.html` in
39
40
  code spans; those files are not shipped. Many type references name upstream's repository-level
@@ -47,8 +48,9 @@ Each one removes a dependency on a dropped file. Re-apply them on update.
47
48
  tells the agent to run the geometry verifier.
48
49
  - `SKILL.md` §9: the geometry-verifier and motion-verifier runs are cut; the `self_check.py` item
49
50
  is now a check by hand of the same five properties.
50
- - `SKILL.md` §11: the route-by-source links to the three import references are replaced by the
51
- list of source formats, and step 1 reads the source file as text instead of running an extractor.
51
+ - `SKILL.md` §11: the route-by-source links to the four import references are replaced by the
52
+ list of source formats (PlantUML included), and step 1 reads the source file as text instead of
53
+ running an extractor.
52
54
  - `SKILL.md` §12: the "Exporting to PNG / SVG" body is replaced by one paragraph: this copy ships no
53
55
  export helpers, so an `.svg` is the `<svg>` node copied out of the `.html`, and a `.png` cannot be
54
56
  made.
@@ -72,9 +74,12 @@ Each one removes a dependency on a dropped file. Re-apply them on update.
72
74
  - `references/animation.md`: the three-command verifier block is replaced by "check these by hand".
73
75
  - `references/output-spec.md`: two links to `export.md` are removed; the render-linter
74
76
  command is named as upstream's and not shipped.
75
- - `references/primitives-core.md`: three geometry-verifier commands are cut.
77
+ - `references/primitives-core.md`: three geometry-verifier commands are cut, and the font
78
+ substitution paragraph says to check masks by hand instead of naming `self_check.py`; the
79
+ accessible-name rule names `scripts/self_check.py` as upstream's and not shipped.
76
80
  - `references/style-guide.md`: the export/self-check commands become "check that the Google Fonts
77
- link is no longer present".
81
+ link is no longer present"; the width-budget paragraph names `scripts/self_check.py` as
82
+ upstream's and not shipped, and makes its 0.3em label check one to hold by hand.
78
83
  - `references/type-architecture-delta.md`: the verifier commands are named as upstream's and not
79
84
  shipped.
80
85
  - `references/type-treemap.md`: the render-linter command is named as upstream's and not shipped.
@@ -17,7 +17,7 @@ Routed from SKILL.md §7 and §8. SKILL.md keeps the grid rule in one line, the
17
17
 
18
18
  ### Complexity budget (per diagram)
19
19
 
20
- These are the per-type limits. The universal rows in SKILL.md §7 (9 nodes, 12 arrows or transitions, 2 coral elements, 2 annotation callouts, and the motion limits) apply to every type on top of these, and a semantic pattern's own budget in [semantic-patterns.md](semantic-patterns.md) can only tighten them.
20
+ These are the per-type limits. The universal rows in SKILL.md §7 (9 nodes, 12 arrows or transitions, 2 coral elements, 2 annotation callouts, and the motion limits) apply to every type on top of these, and a semantic pattern's own budget in [semantic-patterns.md](semantic-patterns.md) can only tighten them. One type is the exception: SBGN replaces the 9 nodes and 12 arrows rows with its own ceiling below, because a process square is a reaction marker rather than a node and every reaction needs its consumption and production arcs. Its other universal rows still apply, and no other type may exceed 9 nodes or 12 arrows by analogy.
21
21
 
22
22
  | Limit | Rule |
23
23
  |---|---|
@@ -50,6 +50,7 @@ These are the per-type limits. The universal rows in SKILL.md §7 (9 nodes, 12 a
50
50
  | Max cells (treemap) | 8 |
51
51
  | Max series (line chart) | 5 |
52
52
  | Max tasks (Gantt) | 12 |
53
+ | Max stages (steps) | 7, exactly 1 focal stage |
53
54
  | Max points (scatter plot) | 30 |
54
55
  | Max series / outliers (box plot) | 8 / 8, 1 focal series |
55
56
  | Max stages / nodes / flows (sankey) | 3 / 8 / 12 |
@@ -58,11 +59,16 @@ These are the per-type limits. The universal rows in SKILL.md §7 (9 nodes, 12 a
58
59
  | Max columns / cards (kanban) | 5 / 12 total, 4 per column |
59
60
  | Max stages / rows (user journey) | 6 / 3, 2 pain markers |
60
61
  | Max stages / layers (service blueprint) | 6 stages; required customer / frontstage / backstage; optional evidence / support; 1 focal cell |
62
+ | Unit Grid | 100 equal cells; 10 × 10; 4px gutters; 1 count; at most 1 focal completed cell |
61
63
  | Max zones / nodes / paths (deployment) | 3 / 6 / 8, 9 artifacts |
62
64
  | Max nodes / edges (dependency) | 9 / 14, 4 ranks, 1 cycle |
65
+ | Max nodes / arcs (arc diagram) | 9 / 14, 1 focal arc |
66
+ | Max requirement rows / primary design links / primary verification links (requirement traceability) | 6 / 1 per row / 1 per row, 1 focal row |
67
+ | Max stages / commands / events / read models (event modeling) | 6 / 1 per stage / 1 per stage / 1 per stage, 2 accent uses |
63
68
  | Max classes / relationships (UML class) | 7 / 8, 5 members per compartment |
64
69
  | Max activities / slices / cards (story map) | 5 / 3 / 12 |
65
70
  | Max tables / columns / FKs (db schema) | 5 / 8 shown / 6 |
71
+ | Max macromolecules / processes / compartments / source-sink / arcs (SBGN) | 7 / 6 / 1 / 2 / 16; replaces the 9 nodes and 12 arrows rows |
66
72
 
67
73
  If you exceed, split into two diagrams (overview + detail).
68
74
 
@@ -175,7 +175,7 @@ Write the new tokens to `style-guide.md`. Suggest rebuilding one example (upstre
175
175
 
176
176
  After onboarding, the user should:
177
177
 
178
- 1. Open `assets/index.html` (gallery) and confirm the new palette feels coherent across all 45 visual types.
178
+ 1. Open `assets/index.html` (gallery) and confirm the new palette feels coherent across all 50 visual types.
179
179
  2. If any type looks off, they usually need to tune `muted` (often too dark or too light against the new `paper`).
180
180
 
181
181
  ---
@@ -138,7 +138,7 @@ Every diagram is an accessible figure by default:
138
138
 
139
139
  1. Its `<svg>` carries `role="img"` and `aria-labelledby` naming the diagram's `<title>` and `<desc>`.
140
140
  2. `<title>` is the first child of `<svg>`, before `<defs>`. Assistive technology may ignore a title placed later.
141
- 3. The IDs are prefixed per diagram and variant: `<slug>-title` / `<slug>-desc`, where the slug matches the file (`loop`, `loop-dark`, `loop-full`). Bare `title` / `desc` IDs are banned — two inline diagrams would otherwise share one ID, and the second could be announced with the first's name. Each naming ID must also be unique across the whole document, including non-SVG elements; the packaged `scripts/self_check.py` rejects these collisions.
141
+ 3. The IDs are prefixed per diagram and variant: `<slug>-title` / `<slug>-desc`, where the slug matches the file (`loop`, `loop-dark`, `loop-full`). Bare `title` / `desc` IDs are banned — two inline diagrams would otherwise share one ID, and the second could be announced with the first's name. Each naming ID must also be unique across the whole document, including non-SVG elements; upstream's `scripts/self_check.py`, not shipped in this copy, rejects these collisions, so check them by hand.
142
142
  4. `<title>` is the short name of the subject — roughly the page `<h1>`, and about 60 characters or fewer.
143
143
  5. `<desc>` is one sentence stating what the diagram shows in terms a reader needs without the image. Describe the content, not the geometry: “Org chart showing a command center routing work to specialist agents and escalation owners,” not “A box at the top with five boxes below it.” A shape-by-shape narration is worse than no useful description.
144
144
  6. Decorative-only SVG, such as the specimen glyphs in `assets/icons.html`, carries `aria-hidden="true"` instead.
@@ -1,6 +1,6 @@
1
1
  # Semantic patterns
2
2
 
3
- Semantic patterns describe **what a system does**; the 45 visual types describe **how information is arranged**. Choose a pattern first when behavior, state, enforcement, or risk is load-bearing, then use its nearest visual type as the layout grammar. If no pattern matches, choose a visual type directly.
3
+ Semantic patterns describe **what a system does**; the 50 visual types describe **how information is arranged**. Choose a pattern first when behavior, state, enforcement, or risk is load-bearing, then use its nearest visual type as the layout grammar. If no pattern matches, choose a visual type directly.
4
4
 
5
5
  Use one primary pattern per figure. A second pattern may supply at most one supporting primitive; if both need full treatment, split overview and detail. Labels and outcomes must remain complete in a static frame.
6
6
 
@@ -132,7 +132,7 @@ Geist and Instrument Serif carry no Hangul. A Korean `<text>` element extends it
132
132
 
133
133
  Both Noto faces ship in the font link above, so the web font resolves before any locally installed one and the same file renders identically on macOS, Windows, and a reviewer's browser. The local families follow it for offline viewing. Page titles need the serif equivalent — `'Instrument Serif', 'Noto Serif KR', serif` — or a mixed Latin/Korean title resolves Hangul through the platform's generic serif and the two halves disagree. Google's `css2` endpoint slices Korean by unicode-range, so a diagram with a handful of Korean labels downloads only the slices it touches. The four templates carry both faces because a new diagram may contain Hangul; the shipped Latin-only examples keep the shorter link, since a file with no Hangul has nothing to resolve.
134
134
 
135
- **Width budget.** Measure per character, not per script: **every Unicode wide or full-width character costs 1em, every other character costs its face's Latin advance** (0.60em sans, 0.62em mono), and nonspacing/enclosing marks cost nothing. Sum over the string and multiply by the font size for the text width, then add padding and round the box up to the next multiple of 4. `verify-treemap.py` enforces exactly this text width for treemap cell labels; the padding and rounding are authoring convention, and no other type carries an automatic check, so on those the budget is yours to hold.
135
+ **Width budget.** Measure per character, not per script: **every Unicode wide or full-width character costs 1em, every other character costs its face's Latin advance** (0.60em sans, 0.62em mono), and nonspacing/enclosing marks cost nothing. Sum over the string and multiply by the font size for the text width, then add padding and round the box up to the next multiple of 4. `verify-treemap.py` enforces exactly this text width for treemap cell labels. Upstream's `scripts/self_check.py`, not shipped in this copy, applies the same width to text inside a visible box of any type, so here that check is yours: add any letter-spacing, and keep every label within 0.3em of its box edge. Padding, rounding, and labels on paper-coloured arrow-label masks stay yours to hold too.
136
136
 
137
137
  Counting by script is the trap. `주문 v2.1` is two full-width syllables and five narrow characters; a formula that tallies Hangul, Latin letters, and spaces silently drops `2`, `.`, and `1` and sizes the box for four of its seven characters. Every rendered character costs something — measure per character, never per script.
138
138
 
@@ -37,8 +37,77 @@ Over budget: collapse a leaf cluster into one aggregate node labelled with its c
37
37
  - Highlighting more than one cycle in a single diagram — pick the one that matters editorially; a second cycle competes with the first and neither reads.
38
38
  - Omitting the fan-in badges — without them the reader can't see at a glance where dependencies concentrate, which is the entire reason this type exists over a plain tree.
39
39
 
40
+ ### Arc diagram
41
+
42
+ **Best for:** pairwise imports among a handful of packages when the *skip* is the story — nodes on one baseline, each edge a rising semicircle whose height is how many seats it jumps. Use it when a ranked dependency graph would bury a skip-layer import inside the hairball: the shipped example lines seven packages left to right, and Checkout still importing Auth is the tallest arc.
43
+
44
+ Not for: a node with many parents that need rank rows (that is the parent dependency graph); a tree (every node has one parent — use Tree); a cycle that has to be routed around the stack (the parent marks that with one dashed back-edge). An arc diagram has no ranks and no back-edge grammar.
45
+
46
+ #### Layout conventions
47
+
48
+ - **One rail, left to right.** Nodes are `r=6` dots on a shared baseline at `y=400` inside `0 0 1000 500`, equally spaced (the shipped example uses a 140px pitch from `x=80`). Labels sit under the dots, `text-anchor="middle"`.
49
+ - **Node count: 4–9.** Below 4 there is no rail to skip along; above 9 split an overview from a cluster.
50
+ - **Rising semicircles only.** Each import is `M x1,y A r,r 0 0 1 x2,y` with `fill="none"`. Sweep 1 rises in SVG coordinates; sweep 0 would draw the import under the seats. `r` is half the endpoint distance, so height equals span × pitch / 2 — a neighbour cannot wear a skip's arc.
51
+ - **Span is the seat count.** `data-span` is `|i−j|` on the rail. A five-seat skip is five times a neighbour, not a decorative taller curve.
52
+ - **Paint back to front:** longer arcs first, neighbours next, the focal skip last so it is the stroke the eye hits.
53
+ - **4px grid** applies to the designed constants — baseline, label baseline, legend rows, node radius. Positions on the rail are pitch-scaled and exempt.
54
+
55
+ #### Colour
56
+
57
+ - **One accent arc, and one muted treatment for everyone else.** The shipped example accents Checkout → Auth — the skip that will hurt a split — not the package with the most edges.
58
+ - **Stroke, not fill.** An arc is a line. Filling it turns a skip into a wedge.
59
+ - **The nodes stay ink.** Accent lives on the skip, matching the parent's rule that the cycle is the accent and the nodes it touches are not.
60
+
61
+ #### Honest-data rule
62
+
63
+ **Arc height is the seat count, on one shared pitch.** `scripts/verify-arc-diagram.py` gates it.
64
+
65
+ - **One baseline, one pitch.** A node off the rail, or a seat that is a different width from its neighbours, makes two spans of the same count draw at two heights.
66
+ - **`data-span` equals `|i−j|`.** Declaring 2 for a five-seat skip, or drawing a neighbour at a skip's radius, is the type's unforgivable error.
67
+ - **Endpoints are the named nodes.** A path that names Auth and Checkout but lands on Catalog is a different import.
68
+ - **Direction reads off the rail.** Every muted arc runs left to right: its left seat imports its right one, so order the rail by import direction and say so in the caption. The one import against the rail is the accent arc, with a small accent arrowhead on the package it imports. Arrowheads on every arc would pile up at shared seats, where each arc lands vertically.
69
+
70
+ #### Declaring the values
71
+
72
+ **Every arc is bound to the two nodes it joins and the span it encodes.** `data-span` on a `<path>` is the arc-diagram contract — deliberately not `data-value` on a `<circle>` (beeswarm), `data-size` (bubble), `data-series` (slopegraph) or `data-ranks` (bump), so no sibling checker claims an arc-diagram file and this one claims none of theirs.
73
+
74
+ ```svg
75
+ <!-- Seat rail at y=400, pitch 140. Auth is seat 1, Checkout is seat 6. -->
76
+ <circle data-name="Auth" cx="220" cy="400" r="6"/>
77
+ <circle data-name="Checkout" cx="920" cy="400" r="6"/>
78
+ <path data-from="Checkout" data-to="Auth" data-span="5"
79
+ d="M 220,400 A 350,350 0 0 1 920,400"
80
+ fill="none" stroke="{accent}" stroke-width="1.6"/>
81
+ ```
82
+
83
+ What each binding buys, and what it costs to omit:
84
+
85
+ | Binding | Without it |
86
+ |---|---|
87
+ | `data-span` on the path | A decorative tall arc on a neighbour could not be caught — the drawn radius would be the only statement of the skip. |
88
+ | `data-from` / `data-to` | A path that names two packages but lands on two others still looks like their import. |
89
+ | `data-name` on the node circle and its label | Two labels exchanged along the rail rename both packages, with every span still correct in isolation. |
90
+
91
+ `scripts/verify-arc-diagram.py` derives the pitch from the nodes, requires a rising semicircle whose radius matches both the endpoint distance and `pitch · span / 2`, refuses a second accent arc or a muted arc that imports leftward, and checks every bound label against the node it names; `scripts/test-verify-arc-diagram.py` proves each check in both polarities and pins the sibling scope treaty in both directions.
92
+
93
+ **Nothing may position a mark except its own attributes.** The checker reads raw `cx`/`d`/`x`, so anything applied afterwards invalidates the check that passed. Every carrier is refused — the `transform` attribute, an inline `style="…"`, and a rule in a `<style>` block — on a node, on an arc, on a bound label, or on an ancestor `<g>`/`<svg>`. Bake the offset into the coordinates.
94
+
95
+ **Nothing may paint or hide a mark except its own attributes.** A `<style>` rule outranks every presentation attribute, so the checker refuses one that sets `stroke` or `fill`, and one that hides or resets (display, visibility, zero opacity, zero stroke width or `all`) the diagram's `<svg>`, anything inside it, or an element around it. A rule for page-only chrome, such as `.footer{display:none}` or a logo, is fine. The accent arc is read as the shipped orange or the active `--color-accent` set by a rule that reaches the diagram. Give each import its own literal `stroke`.
96
+
97
+ #### Anti-patterns
98
+
99
+ - Drawing a neighbour at a skip's height — the type's one unforgivable error.
100
+ - A ranked layout, a cycle routed around the stack, or fan-in badges (those are the parent).
101
+ - Filling an arc, or using sweep 0 so the import hangs under the seats.
102
+ - Uneven spacing so that height no longer equals span.
103
+ - A hue per edge instead of one muted treatment plus a single accent.
104
+ - Positioning a mark, a bound label or an ancestor group from CSS.
105
+
40
106
  ## Examples
41
107
 
42
108
  - `assets/example-dependency.html` — minimal light
43
109
  - `assets/example-dependency-dark.html` — minimal dark
44
110
  - `assets/example-dependency-full.html` — full editorial
111
+ - `assets/example-arc-diagram.html` — arc diagram, minimal light
112
+ - `assets/example-arc-diagram-dark.html` — arc diagram, minimal dark
113
+ - `assets/example-arc-diagram-full.html` — arc diagram, full editorial
@@ -0,0 +1,36 @@
1
+ # Event modeling
2
+
3
+ **Best for:** showing how commands, resulting domain events, and read models relate across ordered business stages. Use it when the supplied scenario names those elements and their links. The horizontal axis is scenario order unless timestamps or durations are supplied. An illustrative example must say so.
4
+
5
+ **Not this type:** Use [Sequence](type-sequence.md) for actor lifelines, message calls, and replies in temporal order. Use [Data flow](type-data-flow.md) for movement or transformation between systems when commands and resulting events are not the question. Use [Timeline](type-timeline.md) for dated occurrences without command and projection roles. Do not infer an event store, broker, or persistence mechanism from this view.
6
+
7
+ Keep the shipped SVG static: place each paper rectangle behind its own labels, use explicit house ink and readable text, and keep page styles off SVG marks. The verifier checks this bounded layout; the browser render gate checks the shipped pages. Draw each typed arrow with visible, nonzero straight path segments.
8
+
9
+ ## Layout grammar
10
+
11
+ - Arrange numbered stages left to right. Align **Command**, **Event**, and **Read model** in three fixed horizontal lanes. Within each stage, the command sits above the resulting event, and the read model sits below it.
12
+ - A command is an intent/request, named as an imperative. An event is a fact that occurred, named in past tense. A read model is a view or projection, not another event. Show each role explicitly in text and metadata.
13
+ - Draw a directed `emits` link from command to event and a directed `projects` link from event to read model. The diagram claims these links only when supplied by the source. If a link is unknown, label the gap; do not silently connect unrelated marks.
14
+ - Stage order does not encode elapsed time. Do not space stages proportionally to time without a measured axis. If a stage branches, split the scenario or use [Flowchart](type-flowchart.md) for the decision.
15
+
16
+ ### Machine-readable contract
17
+
18
+ Put `data-diagram-type="event-modeling"` on the accessible SVG. Each stage is a group with `data-event-stage="STAGE-ID"`, a unique ID, `data-stage-order` starting at `1`, and `data-diagram-role="timeframe"`. Each role node has `data-event-kind="command|event|read-model"`, a unique `data-event-id` printed in the node, and a matching `data-diagram-role`. Each link has `data-diagram-role="event-link"`, `data-event-rel="emits|projects"`, `data-from`, and `data-to` pointing to IDs in that stage. `scripts/verify-event-modeling.py` checks this structural contract for the shipped examples; it does not establish that an illustrated business event happened.
19
+
20
+ ## Complexity budget
21
+
22
+ - At most six stages. The overview uses one command, one event, and one read model per stage. Split richer scenarios into overview and detail views instead of shrinking labels.
23
+ - At most two accent uses. The event and link labels must carry meaning without color.
24
+
25
+ ## Anti-patterns
26
+
27
+ - Commands and events in the same lane, or an event named as a future instruction.
28
+ - A left-to-right stage layout presented as measured duration.
29
+ - A read model shown as proof of persistence, delivery guarantee, or test coverage.
30
+ - A generic producer-broker-consumer flow renamed as event modeling with no commands or projections.
31
+
32
+ ## Examples
33
+
34
+ - `assets/example-event-modeling.html` — minimal light, illustrative three-stage scenario.
35
+ - `assets/example-event-modeling-dark.html` — the same scenario on the dark skin.
36
+ - `assets/example-event-modeling-full.html` — full editorial page with reading notes.
@@ -0,0 +1,45 @@
1
+ # Requirement traceability
2
+
3
+ **Best for:** answering which identified requirements come from a source, have a design element that satisfies them, and have a test or inspection that verifies them. The fixed source × requirement × design × verification trace makes an absent link visible. Use it only when the IDs and relationships come from supplied sources. An illustrative example must say so.
4
+
5
+ **Not this type:** A generic package dependency graph has no required requirement or verification column; use [Dependency graph](type-dependency.md) for that. Use [Heatmap](type-heatmap.md) when each cell encodes a value rather than a cited element ID and a typed relationship. Use [UML class](type-uml-class.md) for type structure and inheritance.
6
+
7
+ Keep the shipped SVG static: place each paper rectangle behind its own labels, use explicit house ink and readable text, and keep page styles off SVG marks. The verifier checks this bounded layout; the browser render gate checks the shipped pages.
8
+
9
+ ## Layout conventions
10
+
11
+ - One row per requirement, in a stable source order. Four fixed columns: **Source**, **Requirement**, **Satisfied by**, **Verified by**. The latter two headings state the relationship direction without relying on arrow placement.
12
+ - Each source cell prints a source ID and citation. Each requirement cell prints a stable ID and short statement. Each linked cell prints its element ID and short name. Its relationship type is visible in the column heading and in the cell label.
13
+ - Keep the three cells on the same horizontal row. Separate rows with a solid neutral rule. Do not draw links across rows or rely on color alone to imply coverage.
14
+ - If a relationship is absent in real input, show `No linked element` or `No verification` in its cell. Do not invent a link or turn a missing relationship into an empty box.
15
+ - Preserve one focal row at most. Accent may mark a coverage gap or an important requirement, but the text must name the condition.
16
+
17
+ ### Machine-readable contract
18
+
19
+ Each row is a `<g data-trace-row="REQ-ID" data-trace-source="source reference">` containing:
20
+
21
+ - one source and one requirement with `data-trace-kind`, unique `data-trace-id`, and a visible matching ID;
22
+ - an optional design and test element with the same kind and ID attributes;
23
+ - one `derives` relationship from source to requirement;
24
+ - one `satisfies` relationship from design to requirement, or an explicit missing relationship;
25
+ - one `verifies` relationship from test to requirement, or an explicit missing relationship.
26
+
27
+ Relationships use `data-trace-rel`, `data-trace-from`, and `data-trace-to`. A missing relationship uses `data-trace-missing="true"` and `data-trace-to` with no `data-trace-from`. The row ID and printed ID must agree. Every endpoint must be an authored ID in the same SVG. An ID is not evidence that the relationship is true; the source reference and visible label are still required. `scripts/verify-requirement-traceability.py` checks the structural contract for the shipped examples.
28
+
29
+ ## Complexity budget
30
+
31
+ - At most 6 requirement rows, each with one primary design link and one primary verification link in this overview. Split complex many-to-many trace data into an overview and a detail or use a table.
32
+ - At most one focal row. Do not shrink text to fit more rows.
33
+
34
+ ## Anti-patterns
35
+
36
+ - Anonymous boxes, untyped lines, or a design-to-test arrow presented as proof that a test verifies the requirement.
37
+ - A green status that hides a missing test ID or source reference.
38
+ - Repeating one test across requirements without checking that it actually verifies each requirement.
39
+ - Treating an illustrative specimen as evidence of a real system's compliance.
40
+
41
+ ## Examples
42
+
43
+ - `assets/example-requirement-traceability.html` — minimal light, illustrative account-access requirements.
44
+ - `assets/example-requirement-traceability-dark.html` — the same illustrative trace on the dark skin.
45
+ - `assets/example-requirement-traceability-full.html` — full editorial page with reading notes.
@@ -0,0 +1,80 @@
1
+ # SBGN
2
+
3
+ **Best for:** a biological process as a bipartite species/process graph — carotenoid cleavage, a signalling cascade, a metabolic map — where each reaction is a process node, each molecule is a species node, and every arc has a role (consumption, production, reversible, modulation). Use when the reader must see *what is consumed, what is produced, and inside which compartment*.
4
+
5
+ **Not this type:**
6
+
7
+ - Boxes and arrows of a runtime system → **Architecture** (`type-architecture.md`). Architecture has no species/process bipartition and no role-typed arcs.
8
+ - Decision logic with branches → **Flowchart** (`type-flowchart.md`).
9
+ - Containment without reactions → **Nested** (`type-nested.md`). Nested shows scope; it does not host process nodes or consumption/production.
10
+ - A quantity splitting across stages → **Sankey** (`type-sankey.md`). Sankey conserves width, not stoichiometry.
11
+
12
+ Authoring-only: the model arrives as text in the prompt. This type does not import SBML or SBGN-ML.
13
+
14
+ ## Layout conventions
15
+
16
+ - **Bipartite.** Every reaction is a **process** glyph (a 32×32 square). Every molecule is a **macromolecule** (a rounded rectangle). Never attach two species directly; never attach two processes directly.
17
+ - **Compartment first.** Draw the enclosing compartment (cytosol, chloroplast, nucleus) as a zone rect before arrows and nodes. One compartment in the canonical budget. Label it on a paper mask on the top edge.
18
+ - **Primary flow left → right:** substrates, then processes, then products. Fan-in to a shared product uses a dedicated vertical trunk; do not stack two productions on one y.
19
+ - **Orthogonal connectors** with `r=8` elbows (SKILL.md §6). Consumption and production take the filled arrow marker. A reversible pair is two-headed. Modulation takes the open-circle marker.
20
+ - **1 coral focal:** the species or process the figure exists to show, at most two accent elements in all. In the worked fixture that is beta-carotene and its cleavage process v1; every arc stays in ink.
21
+ - **House style, SBGN shapes.** Monochrome ink/muted, one accent. Keep SBGN's shape semantics (square process, rounded macromolecule, empty-set source/sink, circle-headed modulation) rather than colour-coding roles.
22
+
23
+ ### Glyphs (PD subset)
24
+
25
+ | Kind | Shape | `data-kind` |
26
+ |---|---|---|
27
+ | Macromolecule | Rounded rect, `rx=16`, 144×64 (or 160×64) | `macromolecule` |
28
+ | Process | Square 32×32, `rx=2` | `process` |
29
+ | Compartment | Zone rect, `rx=8`, paper-mask label | `compartment` |
30
+ | Source / sink | Empty-set: circle r=12 plus a diagonal | `source-sink` |
31
+ | Consumption | Filled arrow, species → process | `consumption` |
32
+ | Production | Filled arrow, process → species | `production` |
33
+ | Reversible | Two-headed, species ↔ process | `reversible` |
34
+ | Modulation | Open-circle head, species → process | `modulation` |
35
+
36
+ ```svg
37
+ <!-- Macromolecule -->
38
+ <g data-kind="macromolecule" data-entity-id="bcar" data-compartment="cyt">
39
+ <rect data-role="bounds" x="80" y="80" width="144" height="64" rx="16" fill="#f5f5f5"/>
40
+ <rect x="80" y="80" width="144" height="64" rx="16"
41
+ fill="rgba(191,69,32,0.08)" stroke="#bf4520" stroke-width="1"/>
42
+ <text x="152" y="108" …>B-carotene</text>
43
+ </g>
44
+
45
+ <!-- Process -->
46
+ <g data-kind="process" data-process-id="v1" data-compartment="cyt">
47
+ <rect data-role="bounds" x="280" y="96" width="32" height="32" rx="2"
48
+ fill="#f5f5f5" stroke="#2d3142" stroke-width="1"/>
49
+ </g>
50
+
51
+ <!-- Consumption / production -->
52
+ <path data-kind="consumption" data-from="bcar" data-to="v1"
53
+ d="M 224,112 H 280" fill="none" stroke="#4f5d75" stroke-width="1.2"
54
+ marker-end="url(#arrow)"/>
55
+ <path data-kind="production" data-from="v1" data-to="b10"
56
+ d="M 312,112 H 480" fill="none" stroke="#4f5d75" stroke-width="1.2"
57
+ marker-end="url(#arrow)"/>
58
+ ```
59
+
60
+ The file has exactly one `<svg data-diagram="sbgn">`. Process squares are 32×32 so they stay below the geometry-checker's 60×40 node floor; macromolecules are the nodes the connector rules attach to. Source/sink circles are decoration-sized and also below that floor.
61
+
62
+ **Machine-readable contract.** Species, processes, and the compartment carry stable IDs. Every arc declares `data-kind`, `data-from`, and `data-to`. `scripts/verify-sbgn.py` fails duplicate IDs, unresolved endpoints, an arc whose drawn path does not start on its `data-from` glyph's edge and end on its `data-to` glyph's edge, an arc with more than one `M` subpath, an arc that touches any other glyph or meets its own glyphs anywhere but its two ends, an arc hidden by `display`, `visibility`, `opacity`, `stroke-opacity`, `stroke` or `stroke-width`, a glyph part drawn outside its bounds rect, an arc whose `data-kind` is missing or unknown, an arc that skips the bipartite rule, a macromolecule drawn outside its compartment, a glyph or arc moved by a `transform` or positional CSS, and a figure over the Bruno ceiling. Place glyphs with `x`, `y`, `width`, and `height` only, and draw arcs in map coordinates with path data only. Every other `<path>`, `<line>`, `<polyline>`, `<polygon>`, or `<use>` in the map must be a declared arc; legend samples go inside `<g data-role="legend">`, use only `<line>`, `<rect>`, `<circle>`, and `<text>`, and stay clear of every glyph. Arcs never cross, touch, stack, or end on one another, measured on the drawn stroke including curves and corners; two arcs may share only a port on a glyph's edge. Route around first, and where the layout forces a single crossing, bridge it with the hop from [type-architecture.md](type-architecture.md#crossing-arrows--bridge--hop). The shipped map has one, where v3's product route hops v4's.
63
+
64
+ ## Budget
65
+
66
+ ≤7 macromolecules, ≤6 processes, ≤1 compartment, ≤2 source/sink glyphs, ≤16 arcs, 2 accent elements. This ceiling replaces SKILL.md §7's 9 nodes and 12 arrows rows for SBGN only (see [layout-budget.md](layout-budget.md#complexity-budget-per-diagram)); the other universal rows still apply. That ceiling is the Bruno_JExpBot2016 fixture: seven carotenoid species, six cleavage reactions, one cytosol. More species → split the map (overview of the pools, then one cleavage family).
67
+
68
+ ## Anti-patterns
69
+
70
+ - A species–species arrow with no process node — that is a flowchart, and it hides the reaction.
71
+ - A database or architecture box used as a macromolecule.
72
+ - Colour as the only distinction between consumption and modulation — the markers must differ, because greyscale still has to tell them apart.
73
+ - Importing SBML or SBGN-ML in this skill — author from the prompt; an extractor is a later, separate surface.
74
+ - Flattening the compartment into a caption (`all of this is cytosol`) — the compartment is a glyph.
75
+
76
+ ## Examples
77
+
78
+ - `assets/example-sbgn.html` — Bruno carotenoid cleavage, minimal light
79
+ - `assets/example-sbgn-dark.html` — identical IDs, topology, and coordinates, dark
80
+ - `assets/example-sbgn-full.html` — full editorial treatment of the same map
@@ -245,7 +245,7 @@ What each binding buys, and what it costs to omit:
245
245
  | `data-name` on the group and its category label | Two labels exchanged between rows rename both series, with every number still correct in isolation. |
246
246
  | `data-tick` / `data-value` on a tick | The printed axis could be relabelled wholesale — every box honestly placed on a scale the axis lies about. |
247
247
 
248
- `scripts/verify-box-plot.py` derives the value scale from the summaries themselves, requires the five-number order, holds every box, median, whisker and outlier to that scale, refuses an outlier inside the whiskers, caps the accent at one series (read through `var()`, `hsl()` and class, id or attribute selectors), refuses a bound mark hidden by `display`, `visibility` or `opacity`, and checks every bound tick against the mark it describes; `scripts/test-verify-box-plot.py` proves each check in both polarities and pins the sibling scope treaty in both directions.
248
+ `scripts/verify-box-plot.py` derives the value scale from the summaries themselves, requires the five-number order, holds every box, median, whisker and outlier to that scale, refuses an outlier inside the whiskers, caps the accent at one series (read through `var()`, `hsl()` and class, id or attribute selectors), refuses a bound mark hidden by `display`, `visibility` or `opacity` and a bound mark whose own paint draws it nothing (`none`, or a zero `stroke-width`, `stroke-opacity` or `fill-opacity`), and checks every bound tick against the mark it describes; `scripts/test-verify-box-plot.py` proves each check in both polarities and pins the sibling scope treaty in both directions.
249
249
 
250
250
  **Nothing may position a mark except its own attributes.** The checker reads raw `x`/`width`/`x1`/`cx` and `y`/`cy`, so anything applied afterwards invalidates the check that passed. Every carrier is refused — the `transform` attribute, an inline `style="…"`, and a rule in a `<style>` block — on a series group, on a box, on a bound label or tick, or on an ancestor `<g>`/`<svg>`. Bake the offset into the coordinates.
251
251
 
@@ -0,0 +1,180 @@
1
+ # Steps
2
+
3
+ **Best for:** a short, ordered sequence of stages where the order is the claim and each stage needs a number, a compact visual cue, a title, and one brief explanation. Use it for methods, playbooks, onboarding paths, launch checklists, and “how it works” explainers.
4
+
5
+ Prefer **Timeline** when spacing encodes real elapsed time, **Flowchart** when the route branches, **Swimlane** when ownership and handoffs matter, and **Process** when each stage must expose actors, tools, or input/output payloads. Steps has one rail, no branches, no time scale, and no actor lanes.
6
+
7
+ ---
8
+
9
+ ## 1. Inputs
10
+
11
+ ```yaml
12
+ steps: # 3..7, left to right
13
+ - number: "01"
14
+ title: "Frame"
15
+ description: ["Define the decision", "and its success signal"]
16
+ icon: file # optional; from primitive-icons.md
17
+ - number: "02"
18
+ title: "Research"
19
+ description: ["Gather evidence from", "customers and operators"]
20
+ icon: users
21
+ - number: "03"
22
+ title: "Synthesize"
23
+ description: ["Turn observations into", "one testable direction"]
24
+ icon: search
25
+ focal: true
26
+ - number: "04"
27
+ title: "Decide"
28
+ description: ["Commit the scope and", "name the trade-offs"]
29
+ icon: database
30
+ - number: "05"
31
+ title: "Ship"
32
+ description: ["Release, measure, and", "feed learning forward"]
33
+ icon: container
34
+ dark: false
35
+ ```
36
+
37
+ Rules:
38
+
39
+ - `steps` contains 3–7 entries. Fewer than three is a list; more than seven needs grouping or a second diagram.
40
+ - Exactly one step is `focal: true`. It is the decision, transformation, or risk the figure exists to emphasize.
41
+ - `number` is two digits for fewer than 100 steps (`01`, `02`, …) so the rail scans evenly.
42
+ - `description` is one or two short lines, each no longer than 26 characters at the standard ramp. Rewrite rather than shrink.
43
+ - `icon` is optional and must come from [`primitive-icons.md`](primitive-icons.md). Omit icons from every step if a coherent set is unavailable; never mix line icons, emoji, and brand marks.
44
+
45
+ ---
46
+
47
+ ## 2. Layout grammar
48
+
49
+ The canonical `doc-wide` canvas is `1280×720`. All structural coordinates sit on the 4px grid.
50
+
51
+ ```text
52
+ outer_x = 80
53
+ rail_y = 240
54
+ rail_h = 48
55
+ n = len(steps)
56
+ usable_w = 1280 - 2 * outer_x
57
+ stage_w = min(224, 4 * floor(usable_w / (4 * n)))
58
+ content_w = n * stage_w
59
+ start_x = (1280 - content_w) / 2
60
+ stage_x(i) = start_x + i * stage_w
61
+ stage_cx(i) = stage_x(i) + stage_w / 2
62
+ medallion_cy = rail_y + rail_h / 2
63
+ medallion_r = 36
64
+ number_y = 164
65
+ number_rule_y = 184..220
66
+ title_y = 360
67
+ description_y = 388, 408
68
+ legend_rule_y = 600
69
+ legend_y = 636
70
+ ```
71
+
72
+ This yields a 224px stage for 3–5 steps, 184px for 6, and 160px for 7. Keep `stage_w` on the 4px grid, center the combined rail, and preserve at least 24px between description columns. If copy does not fit the narrower six- or seven-stage columns, widen the canvas or rewrite the copy; do not reduce the type ramp.
73
+
74
+ ### Rail
75
+
76
+ - Draw one contiguous horizontal rail from `stage_x(0)` to `stage_x(n-1) + stage_w`.
77
+ - Each stage owns one `stage_w × 48` segment. Alternate `ink @ 0.05` and `ink @ 0.09` fills to make the segmentation visible without introducing a series palette.
78
+ - The focal segment uses `accent-tint` with a 1px `accent` top and bottom rule.
79
+ - The rail itself expresses order. Do not add arrows between adjacent stages; they duplicate the layout.
80
+
81
+ ### Number and guide
82
+
83
+ - Number: `{eyebrow}` role, 8px, weight 600, letter-spacing `0.14em`, centered at `stage_cx(i)`.
84
+ - Guide: 1px vertical rule from `y=184` to `y=220`, `rule-solid`; focal guide uses `accent`.
85
+ - The number is `muted` by default and `accent` for the focal step.
86
+
87
+ ### Icon medallion
88
+
89
+ - Circle center `(stage_cx(i), 264)`, radius 36.
90
+ - Draw an opaque `paper` circle first so the rail does not show through, then a 1px outline.
91
+ - Default outline and icon use `ink`; focal outline and icon use `accent` and the circle may use `accent-tint`.
92
+ - Place one 24×24 primitive at `(stage_cx(i)-12, 252)`. Icons are decorative (`aria-hidden="true"`); the accessible name comes from the SVG title and description.
93
+
94
+ ### Copy block
95
+
96
+ - Title: `{node-name}` role, 12px, weight 600, centered at `y=360`.
97
+ - Description: `{sublabel}` role, 9px, centered, at most two lines at `y=388` and `y=408`.
98
+ - Titles use `ink`; descriptions use `muted`. The focal title may use `accent`; the description remains `muted`.
99
+
100
+ ---
101
+
102
+ ## 3. Focal and color rules
103
+
104
+ One step is focal. Treat its number, guide, rail segment, medallion outline/icon, and title as one visual unit. All remaining steps stay neutral.
105
+
106
+ Do not assign a different hue to every step. The familiar five-color infographic treatment turns sequence into a legend-reading task and conflicts with the global 1–2 accent rule. If stages genuinely encode categories rather than order, use a chart or another type whose color carries data.
107
+
108
+ ---
109
+
110
+ ## 4. Legend
111
+
112
+ Use a bottom strip only when the focal state needs explanation. The canonical examples show:
113
+
114
+ - neutral outlined medallion — `Stage`
115
+ - accent outlined medallion — `Focal stage`
116
+ - italic note — `Equal spacing shows order, not elapsed time.`
117
+
118
+ If the title or subtitle already names the focal stage and the distinction is obvious, remove the legend.
119
+
120
+ ---
121
+
122
+ ## 5. Reproducibility checklist
123
+
124
+ 1. Step count is 3–7 and exactly one entry is focal.
125
+ 2. Step origins, segment widths, medallion centers, and copy anchors derive from §2.
126
+ 3. The rail is contiguous; there are no gaps, arrowheads, or diagonal connectors.
127
+ 4. Every medallion has an opaque paper mask beneath its outline.
128
+ 5. Every step either has one icon from `primitive-icons.md` or all icons are omitted.
129
+ 6. Titles stay at 12px and descriptions at 9px; long copy is rewritten, not shrunk.
130
+ 7. The focal step is the only accent-bearing stage.
131
+ 8. The SVG uses the accessible SVG contract and the wrapper owns horizontal scrolling.
132
+
133
+ ---
134
+
135
+ ## 6. What `verify-steps.py` requires
136
+
137
+ The checker reads attributes, so every mark binds itself to its stage and draws exactly what it states.
138
+
139
+ - **Bindings.** Each stage has one rail `<rect data-role="rail">`, one medallion `<circle data-role="medallion">` and one number `<text data-role="number">`, all with the same unique `data-step`. Rails also carry `data-index` 1..n in left-to-right order. Exactly one rail and its medallion carry `data-focal="true"`.
140
+ - **Geometry.** Rails share `y`, `width` and `height` and touch end to end. Medallions are centered on their segment with one shared radius; numbers are centered on it at `x` and print the two-digit index. Every mark stays inside the viewBox.
141
+ - **Allowed attributes.** A rail may carry only `x y width height fill fill-opacity`, a medallion only `cx cy r fill stroke stroke-width`, a number only `x y fill font-size font-weight font-family text-anchor`, plus their `data-*` bindings. No `style`, `class`, `id`, `transform`, `dx`/`dy`, `opacity` or anything else. A number contains only its text.
142
+ - **Groups.** Marks sit only inside plain `<g>` groups of the one root `<svg>`, never inside `defs`, a nested `svg` or any other element. A group above a mark may carry only `aria-hidden fill stroke stroke-width stroke-linecap stroke-linejoin font-family font-size font-weight letter-spacing text-anchor`. No attribute may appear twice on any element.
143
+ - **Paint and type.** The first `<rect>` in the SVG is the paper (`#f5f5f5` light, `#2d3142` dark). Rails fill with a non-paper house ink above zero alpha. Medallion outlines and numbers use a house ink at 0.4 alpha or more. Numbers resolve to font-size 8 or more, a font family starting with Geist, Geist Mono or Instrument Serif, and `text-anchor="middle"`. Strokes are at most 4 wide.
144
+ - **Page and CSS.** Style marks with presentation attributes. Stylesheet rules that can reach the SVG may set only `box-sizing`, `margin`, `padding` and custom properties; nothing may move or hide the diagram. CONTRIBUTING.md lists the page rules in full.
145
+
146
+ A minimal three-stage figure that passes, with the second stage focal:
147
+
148
+ ```html
149
+ <svg viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="steps-min-title steps-min-desc">
150
+ <title id="steps-min-title">Plan, build, ship</title>
151
+ <desc id="steps-min-desc">Three equal stages on one rail; build is the focal stage.</desc>
152
+ <rect width="100%" height="100%" fill="#f5f5f5"/>
153
+ <g aria-hidden="true">
154
+ <rect x="304" y="240" width="224" height="48" fill="rgba(45,49,66,0.05)" data-role="rail" data-step="plan" data-index="1"/>
155
+ <rect x="528" y="240" width="224" height="48" fill="rgba(191,69,32,0.08)" data-role="rail" data-step="build" data-index="2" data-focal="true"/>
156
+ <rect x="752" y="240" width="224" height="48" fill="rgba(45,49,66,0.05)" data-role="rail" data-step="ship" data-index="3"/>
157
+ </g>
158
+ <g font-family="'Geist Mono', monospace" font-size="8" font-weight="600" letter-spacing="0.14em" text-anchor="middle">
159
+ <text x="416" y="164" fill="#4f5d75" data-role="number" data-step="plan">01</text>
160
+ <text x="640" y="164" fill="#bf4520" data-role="number" data-step="build">02</text>
161
+ <text x="864" y="164" fill="#4f5d75" data-role="number" data-step="ship">03</text>
162
+ </g>
163
+ <g aria-hidden="true" fill="#f5f5f5" stroke-width="1">
164
+ <circle cx="416" cy="264" r="36" stroke="#2d3142" data-role="medallion" data-step="plan"/>
165
+ <circle cx="640" cy="264" r="36" stroke="none"/>
166
+ <circle cx="640" cy="264" r="36" fill="rgba(191,69,32,0.08)" stroke="#bf4520" data-role="medallion" data-step="build" data-focal="true"/>
167
+ <circle cx="864" cy="264" r="36" stroke="#2d3142" data-role="medallion" data-step="ship"/>
168
+ </g>
169
+ </svg>
170
+ ```
171
+
172
+ ---
173
+
174
+ ## 7. Anti-patterns
175
+
176
+ - Rainbow stage bands with no categorical meaning.
177
+ - Using Steps for dated events, branching decisions, actor handoffs, or feedback loops.
178
+ - Paragraphs under each stage; two short lines is the ceiling.
179
+ - A different icon style per stage, emoji mixed with line icons, or icons that repeat the title without adding recognition.
180
+ - Arrowheads between every adjacent segment. The left-to-right rail already says “next.”