geneseed 5.5.0 → 5.6.0
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.
- package/CHANGELOG.md +24 -0
- package/README.md +9 -9
- package/SHIPPED.md +1 -1
- package/docs/concepts/enforcement-table.md +1 -1
- package/docs/concepts/foreman-mode.md +1 -1
- package/docs/concepts/hooks.md +1 -1
- package/docs/extending.md +1 -1
- package/docs/guides/install.md +5 -5
- package/docs/reference/profiles.md +84 -0
- package/harness.config.json +1 -1
- package/js/build/export.mjs +11 -16
- package/js/hosts/hooks.mjs +20 -6
- package/package.json +1 -1
- package/profiles/autonomous.json +14 -0
- package/profiles/corporate.json +14 -0
- package/profiles/mentor.json +13 -0
- package/profiles/minimal.json +15 -0
- package/src/agents/devops-engineer.md +6 -5
- package/src/agents/kubernetes-specialist.md +3 -1
- package/src/agents/spring-boot-engineer.md +3 -3
- package/src/agents/spring-reviewer.md +4 -2
- package/src/skills/codebase-design.md +2 -2
- package/src/skills/commit.md +4 -0
- package/src/skills/diagram-design/SKILL.md +12 -7
- package/src/skills/diagram-design/VENDOR.md +19 -14
- package/src/skills/diagram-design/references/layout-budget.md +7 -1
- package/src/skills/diagram-design/references/onboarding.md +1 -1
- package/src/skills/diagram-design/references/primitives-core.md +1 -1
- package/src/skills/diagram-design/references/semantic-patterns.md +1 -1
- package/src/skills/diagram-design/references/style-guide.md +1 -1
- package/src/skills/diagram-design/references/type-dependency.md +69 -0
- package/src/skills/diagram-design/references/type-event-modeling.md +36 -0
- package/src/skills/diagram-design/references/type-requirement-traceability.md +45 -0
- package/src/skills/diagram-design/references/type-sbgn.md +80 -0
- package/src/skills/diagram-design/references/type-scatter.md +1 -1
- package/src/skills/diagram-design/references/type-steps.md +180 -0
- package/src/skills/diagram-design/references/type-unit-grid.md +63 -0
- package/src/skills/geneseed-code-review.md +2 -1
- package/src/skills/parallel-agents.md +1 -1
- package/src/skills/react-view-transitions/AGENTS.md +26 -26
- package/src/skills/react-view-transitions/SKILL.md +1 -1
- package/src/skills/react-view-transitions/VENDOR.md +12 -3
- package/src/skills/spring-boot/cloud.md +19 -1
- package/src/skills/spring-boot/logging.md +5 -3
- package/src/skills/spring-boot/web.md +27 -2
- package/src/skills/spring-boot.md +4 -2
- package/src/skills/spring-data-jpa.md +18 -4
- package/src/skills/spring-testing.md +4 -0
- package/src/upstreams.json +4 -4
- package/web/dist/assets/{Activity-LKsDzsnK.js → Activity-bUSPM3Dl.js} +1 -1
- package/web/dist/assets/{ActivityDetail-DhwTfPm6.js → ActivityDetail-AHRoXeFN.js} +1 -1
- package/web/dist/assets/{Bonsai-CePMLrpr.js → Bonsai-B5XY9pid.js} +1 -1
- package/web/dist/assets/{CopyButton-CuoaJ6k7.js → CopyButton-C0wwRR9H.js} +1 -1
- package/web/dist/assets/{Dashboard-D1VKuvLe.js → Dashboard-DPAA96EI.js} +2 -2
- package/web/dist/assets/{Docs-CUrHJKaU.js → Docs-CpGDq165.js} +1 -1
- package/web/dist/assets/{Factories-Ci1XfmSy.js → Factories-cNhETa5Q.js} +1 -1
- package/web/dist/assets/{GreenhouseView-CNfH2lPK.js → GreenhouseView-DO3ADmT9.js} +1 -1
- package/web/dist/assets/{Installs-ZHQZM1iS.js → Installs-D3dDyq10.js} +1 -1
- package/web/dist/assets/{JournalView-CMsWahkS.js → JournalView--W-Lw_V9.js} +1 -1
- package/web/dist/assets/{Kits-CkliyK0n.js → Kits-ChfehxY6.js} +1 -1
- package/web/dist/assets/Laws-CNxYmV36.js +4 -0
- package/web/dist/assets/{LibRows-Brv0Hmkr.js → LibRows-CiPvsRYB.js} +1 -1
- package/web/dist/assets/{Library-BYmiLjJr.js → Library-BxQvbwVU.js} +1 -1
- package/web/dist/assets/{Loops-ytm-xJ68.js → Loops-DAblKkyq.js} +1 -1
- package/web/dist/assets/{OperatorHudView-KaqCx_HP.js → OperatorHudView-QtSaSyYm.js} +1 -1
- package/web/dist/assets/{Personal-CmcnRKYE.js → Personal-DxSGv638.js} +1 -1
- package/web/dist/assets/{Settings-tUrpdOfq.js → Settings-CgTbhvRv.js} +1 -1
- package/web/dist/assets/{Tabs-CD7etcGD.js → Tabs-Cf4X1hdz.js} +1 -1
- package/web/dist/assets/{index-COKbhFNo.js → index-B_pTwZra.js} +3 -3
- package/web/dist/assets/index-CzfImiYb.css +1 -0
- package/web/dist/index.html +2 -2
- package/web/dist/assets/Laws-hh4O3HZ4.js +0 -4
- package/web/dist/assets/index-Ba_Kg3Af.css +0 -1
|
@@ -27,8 +27,8 @@ a design talk that keeps stumbling over ambiguous terms, or another {{SKILL}} ne
|
|
|
27
27
|
3. Aim for **deep modules** — much behaviour behind a small interface: callers
|
|
28
28
|
get leverage, maintainers get locality. To find what to deepen, start from
|
|
29
29
|
`git log` hot spots — what keeps changing. Design a new or reshaped interface
|
|
30
|
-
twice before choosing: 2–3 radically different shapes (in parallel
|
|
31
|
-
where the host runs them), compared on depth, locality and seam placement;
|
|
30
|
+
twice before choosing: 2–3 radically different shapes (in parallel fresh
|
|
31
|
+
subagents, never forks, where the host runs them), compared on depth, locality and seam placement;
|
|
32
32
|
recommend one — a hybrid if parts combine — never a menu.
|
|
33
33
|
4. Seams sparingly: the interface is the test surface. Internal seams for the
|
|
34
34
|
module's own tests are fine but never exposed; a test that must reach past
|
package/src/skills/commit.md
CHANGED
|
@@ -19,6 +19,10 @@
|
|
|
19
19
|
repo has no discernible convention, default to **Conventional Commits**:
|
|
20
20
|
`type(scope): subject` (`feat`, `fix`, `docs`, `refactor`, `test`, `chore`…),
|
|
21
21
|
with a `!` before the colon or a `BREAKING CHANGE:` footer for a breaking change.
|
|
22
|
+
**Pass the message as data the commit gate can read:** one quoted `-m '…'` for a
|
|
23
|
+
subject alone; for a body, under bash, `git commit -F - <<'EOF'` … `EOF` with the
|
|
24
|
+
delimiter quoted. Never `-m "$(cat <<'EOF' … EOF)"`: the gate cannot see inside a `$(`,
|
|
25
|
+
so it asks even on your own branch.
|
|
22
26
|
5. **Commit on your own branch; never on the main branch ({{DOCTRINE:consent-before-push}}).**
|
|
23
27
|
On your own branch, commit without asking once steps 1–4 hold. The main branch
|
|
24
28
|
(`main`, `master`, the remote's default, and from a linked worktree the main checkout's branch) takes no direct
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: diagram-design
|
|
3
|
-
description: "Branded HTML/SVG diagrams and charts — architecture, flowchart, sequence, ER, timeline, Gantt, Sankey and dozens more — with .drawio, Mermaid
|
|
3
|
+
description: "Branded HTML/SVG diagrams and charts — architecture, flowchart, sequence, ER, timeline, Gantt, Sankey and dozens more — with .drawio, Mermaid, .excalidraw and PlantUML import. Use when the user asks for a diagram, chart or visual map."
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
6
|
version: "2.6"
|
|
@@ -10,7 +10,7 @@ metadata:
|
|
|
10
10
|
|
|
11
11
|
Create diagrams as self-contained HTML files with inline SVG and an editorial design system.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Fifty visual types. Semantic patterns describe behavior; type references describe layout.
|
|
14
14
|
|
|
15
15
|
---
|
|
16
16
|
|
|
@@ -49,7 +49,7 @@ Applied to schematics:
|
|
|
49
49
|
|
|
50
50
|
## 2. When to Use
|
|
51
51
|
|
|
52
|
-
Use for any of the
|
|
52
|
+
Use for any of the 50 visual types (§3) when a reader will learn more from a visual than from prose, a table, or a bulleted list.
|
|
53
53
|
|
|
54
54
|
**Don't use for:**
|
|
55
55
|
|
|
@@ -80,7 +80,7 @@ When behavior, state, enforcement, or risk carries the meaning, first load [`ref
|
|
|
80
80
|
|
|
81
81
|
The pattern owns semantic primitives and its tighter budget; the type owns layout grammar. Use [`references/animation.md`](references/animation.md) only when motion is requested or materially clarifies ordered change; static remains the default.
|
|
82
82
|
|
|
83
|
-
### Visual-type guide (
|
|
83
|
+
### Visual-type guide (50)
|
|
84
84
|
|
|
85
85
|
| If you're showing… | Use | Reference |
|
|
86
86
|
|---|---|---|
|
|
@@ -91,6 +91,7 @@ The pattern owns semantic primitives and its tighter budget; the type owns layou
|
|
|
91
91
|
| Time-ordered messages between actors | **Sequence** | [type-sequence.md](references/type-sequence.md) |
|
|
92
92
|
| States + transitions + guards | **State machine** | [type-state.md](references/type-state.md) |
|
|
93
93
|
| Entities + fields + relationships | **ER / data model** | [type-er.md](references/type-er.md) |
|
|
94
|
+
| A short ordered method with numbered stages, icons, and brief explanations | **Steps** | [type-steps.md](references/type-steps.md) |
|
|
94
95
|
| Events positioned in time | **Timeline** | [type-timeline.md](references/type-timeline.md) |
|
|
95
96
|
| Cross-functional process with handoffs | **Swimlane** | [type-swimlane.md](references/type-swimlane.md) |
|
|
96
97
|
| Two-axis positioning / prioritization | **Quadrant** | [type-quadrant.md](references/type-quadrant.md) |
|
|
@@ -125,10 +126,14 @@ The pattern owns semantic primitives and its tighter budget; the type owns layou
|
|
|
125
126
|
| What a person does across stages of an experience, and how it feels | **User journey** | [type-journey.md](references/type-journey.md) |
|
|
126
127
|
| What the customer does vs what the service hides, across stages, with a line of visibility | **Service blueprint** | [type-service-blueprint.md](references/type-service-blueprint.md) |
|
|
127
128
|
| Where software runs — zones, hosts, artifacts, replicas, ports | **Deployment** | [type-deployment.md](references/type-deployment.md) |
|
|
128
|
-
| What depends on what, with fan-in and cycles a tree cannot express | **Dependency graph** | [type-dependency.md](references/type-dependency.md) |
|
|
129
|
+
| What depends on what, with fan-in and cycles a tree cannot express; arc diagram (nodes on a line, height is skip-span) variant | **Dependency graph** | [type-dependency.md](references/type-dependency.md) |
|
|
129
130
|
| Classes with operations, inheritance, composition (other UML routes elsewhere) | **UML class** | [type-uml-class.md](references/type-uml-class.md) |
|
|
130
131
|
| Narrative backbone sliced into releases, with the cut line | **Story map** | [type-story-map.md](references/type-story-map.md) |
|
|
131
132
|
| Physical tables: SQL types, constraints, indexes, column-level FKs | **Database schema** | [type-db-schema.md](references/type-db-schema.md) |
|
|
133
|
+
| A biological process as a bipartite species/process graph | **SBGN** | [type-sbgn.md](references/type-sbgn.md) |
|
|
134
|
+
| Source requirements, design elements, and tests linked by stable IDs, with gaps explicit | **Requirement traceability** | [type-requirement-traceability.md](references/type-requirement-traceability.md) |
|
|
135
|
+
| Commands, resulting events, and read models across ordered stages | **Event modeling** | [type-event-modeling.md](references/type-event-modeling.md) |
|
|
136
|
+
| One bounded whole counted in equal discrete units out of 100 | **Unit Grid** | [type-unit-grid.md](references/type-unit-grid.md) |
|
|
132
137
|
|
|
133
138
|
Rules of thumb:
|
|
134
139
|
|
|
@@ -338,9 +343,9 @@ Every diagram ships in three variants (see `assets/`):
|
|
|
338
343
|
|
|
339
344
|
---
|
|
340
345
|
|
|
341
|
-
## 11. Importing an Existing Diagram (draw.io), Mermaid, and
|
|
346
|
+
## 11. Importing an Existing Diagram (draw.io), Mermaid, Excalidraw, and PlantUML
|
|
342
347
|
|
|
343
|
-
Sources: `.drawio*`, `.mmd`, `.mermaid`, Markdown containing a fenced `mermaid` block,
|
|
348
|
+
Sources: `.drawio*`, `.mmd`, `.mermaid`, Markdown containing a fenced `mermaid` block, `.excalidraw`, `.puml`, `.plantuml`, `.pu`, and Markdown containing a fenced `plantuml` / `puml` block. Follow this section for "convert this", "redraw this diagram", and "make this presentable".
|
|
344
349
|
|
|
345
350
|
The short version:
|
|
346
351
|
|
|
@@ -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
|
|
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
|
|
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/` (
|
|
30
|
-
~
|
|
31
|
-
`references/primitive-icons.md` already holds);
|
|
32
|
-
`references/export-registry.md` (the Python/Playwright export
|
|
33
|
-
(Python and host-plugin diagnostics);
|
|
34
|
-
`references/import-mermaid.md
|
|
35
|
-
Python extractors). Upstream's
|
|
36
|
-
`docs/`, the repository-level
|
|
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
|
|
51
|
-
list of source formats, and step 1 reads the source file as text instead of
|
|
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
|
|
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;
|
|
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
|
|
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
|
|
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
|
|