geneseed 4.28.0 → 4.29.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.
Files changed (142) hide show
  1. package/CHANGELOG.md +41 -0
  2. package/README.md +4 -2
  3. package/SHIPPED.md +2 -2
  4. package/adapters/bob/README.md +1 -1
  5. package/adapters/claude-code/README.md +4 -2
  6. package/adapters/opencode/HOW-OPENCODE-LOADS.md +2 -2
  7. package/adapters/opencode/README.md +18 -2
  8. package/adapters/opencode/plugins/geneseed-context.js +155 -18
  9. package/adapters/opencode/plugins/geneseed-guard.js +59 -8
  10. package/adapters/opencode/plugins/geneseed-workflow.js +18 -1
  11. package/adapters/opencode/workflows/_runtime.js +14 -3
  12. package/docs/concepts/enforcement-table.md +5 -4
  13. package/docs/concepts/exclusions.md +3 -3
  14. package/docs/concepts/hooks.md +11 -3
  15. package/docs/concepts/ownership.md +7 -6
  16. package/docs/concepts/skills.md +1 -0
  17. package/docs/guides/set-up-ownership.md +22 -6
  18. package/docs/reference/environment.md +1 -0
  19. package/docs/reference/plugin-context.md +3 -1
  20. package/docs/reference/plugin-guard.md +1 -1
  21. package/docs/understand/enforced-vs-asked.md +3 -3
  22. package/docs/understand/machine-bob.md +1 -1
  23. package/docs/understand/machine-claude.md +1 -1
  24. package/docs/understand/machine-opencode.md +1 -1
  25. package/harness.config.json +1 -1
  26. package/js/README.md +3 -1
  27. package/js/build/driver.mjs +29 -9
  28. package/js/build/emit-opencode.mjs +12 -10
  29. package/js/build/render.mjs +9 -0
  30. package/js/hosts/done-checks.mjs +134 -0
  31. package/js/hosts/geneseed-dir.mjs +116 -0
  32. package/js/hosts/hooks-context.mjs +19 -0
  33. package/js/hosts/hooks-done.mjs +82 -38
  34. package/js/hosts/hooks-learn.mjs +9 -2
  35. package/js/hosts/hooks-prims.mjs +4 -0
  36. package/js/hosts/hooks.mjs +139 -6
  37. package/js/hosts/hosts.mjs +6 -0
  38. package/js/hosts/native.mjs +1 -1
  39. package/js/hosts/owned.mjs +19 -0
  40. package/js/hosts/ownership-gate.mjs +64 -10
  41. package/js/hosts/settings.mjs +115 -74
  42. package/js/inspect/checks-constitution.mjs +5 -1
  43. package/js/inspect/cost.mjs +1 -1
  44. package/js/inspect/doctor.mjs +2 -1
  45. package/js/inspect/inventory.mjs +1 -1
  46. package/js/inspect/status.mjs +2 -1
  47. package/js/inspect/validate.mjs +2 -1
  48. package/js/lib/json.mjs +70 -0
  49. package/js/maintain/uninstall.mjs +18 -5
  50. package/js/web/gates-api.mjs +2 -2
  51. package/package.json +1 -1
  52. package/registry.json +14 -0
  53. package/src/AGENT.md.tmpl +2 -2
  54. package/src/licenses/i-have-adhd.txt +21 -0
  55. package/src/skills/_checkpoints.md +15 -2
  56. package/src/skills/adhd.md +40 -0
  57. package/src/skills/diagram-design/LICENSE +21 -0
  58. package/src/skills/diagram-design/SKILL.md +392 -0
  59. package/src/skills/diagram-design/THIRD_PARTY_LICENSES.md +134 -0
  60. package/src/skills/diagram-design/VENDOR.md +81 -0
  61. package/src/skills/diagram-design/assets/example-architecture.html +183 -0
  62. package/src/skills/diagram-design/assets/example-venn.html +110 -0
  63. package/src/skills/diagram-design/assets/template-dark.html +99 -0
  64. package/src/skills/diagram-design/assets/template-full.html +421 -0
  65. package/src/skills/diagram-design/assets/template-motion.html +448 -0
  66. package/src/skills/diagram-design/assets/template-terminal.html +188 -0
  67. package/src/skills/diagram-design/assets/template.html +100 -0
  68. package/src/skills/diagram-design/references/animation.md +135 -0
  69. package/src/skills/diagram-design/references/layout-budget.md +97 -0
  70. package/src/skills/diagram-design/references/onboarding.md +368 -0
  71. package/src/skills/diagram-design/references/output-spec.md +277 -0
  72. package/src/skills/diagram-design/references/primitive-annotation.md +36 -0
  73. package/src/skills/diagram-design/references/primitive-icons.md +782 -0
  74. package/src/skills/diagram-design/references/primitive-sketchy.md +43 -0
  75. package/src/skills/diagram-design/references/primitive-terminal.md +76 -0
  76. package/src/skills/diagram-design/references/primitives-core.md +144 -0
  77. package/src/skills/diagram-design/references/profiles.md +183 -0
  78. package/src/skills/diagram-design/references/semantic-patterns.md +154 -0
  79. package/src/skills/diagram-design/references/style-guide.md +232 -0
  80. package/src/skills/diagram-design/references/type-architecture-delta.md +143 -0
  81. package/src/skills/diagram-design/references/type-architecture.md +117 -0
  82. package/src/skills/diagram-design/references/type-axonometric-plan.md +83 -0
  83. package/src/skills/diagram-design/references/type-bar.md +108 -0
  84. package/src/skills/diagram-design/references/type-data-flow.md +371 -0
  85. package/src/skills/diagram-design/references/type-db-schema.md +48 -0
  86. package/src/skills/diagram-design/references/type-dependency.md +44 -0
  87. package/src/skills/diagram-design/references/type-deployment.md +45 -0
  88. package/src/skills/diagram-design/references/type-dp-integration.md +407 -0
  89. package/src/skills/diagram-design/references/type-dp-security-matrix.md +379 -0
  90. package/src/skills/diagram-design/references/type-er.md +25 -0
  91. package/src/skills/diagram-design/references/type-exploded.md +115 -0
  92. package/src/skills/diagram-design/references/type-fishbone.md +75 -0
  93. package/src/skills/diagram-design/references/type-flowchart.md +23 -0
  94. package/src/skills/diagram-design/references/type-gantt.md +45 -0
  95. package/src/skills/diagram-design/references/type-heatmap.md +80 -0
  96. package/src/skills/diagram-design/references/type-high-level.md +470 -0
  97. package/src/skills/diagram-design/references/type-it-state.md +468 -0
  98. package/src/skills/diagram-design/references/type-journey.md +55 -0
  99. package/src/skills/diagram-design/references/type-kanban.md +49 -0
  100. package/src/skills/diagram-design/references/type-layers.md +26 -0
  101. package/src/skills/diagram-design/references/type-line.md +337 -0
  102. package/src/skills/diagram-design/references/type-loop.md +223 -0
  103. package/src/skills/diagram-design/references/type-medallion.md +356 -0
  104. package/src/skills/diagram-design/references/type-nested.md +22 -0
  105. package/src/skills/diagram-design/references/type-org-chart.md +44 -0
  106. package/src/skills/diagram-design/references/type-polar.md +136 -0
  107. package/src/skills/diagram-design/references/type-process.md +490 -0
  108. package/src/skills/diagram-design/references/type-pyramid.md +33 -0
  109. package/src/skills/diagram-design/references/type-quadrant.md +81 -0
  110. package/src/skills/diagram-design/references/type-radar.md +82 -0
  111. package/src/skills/diagram-design/references/type-sankey.md +75 -0
  112. package/src/skills/diagram-design/references/type-scatter.md +276 -0
  113. package/src/skills/diagram-design/references/type-sequence.md +130 -0
  114. package/src/skills/diagram-design/references/type-service-blueprint.md +103 -0
  115. package/src/skills/diagram-design/references/type-state.md +30 -0
  116. package/src/skills/diagram-design/references/type-story-map.md +46 -0
  117. package/src/skills/diagram-design/references/type-swimlane.md +22 -0
  118. package/src/skills/diagram-design/references/type-timeline.md +20 -0
  119. package/src/skills/diagram-design/references/type-tree.md +24 -0
  120. package/src/skills/diagram-design/references/type-treemap.md +137 -0
  121. package/src/skills/diagram-design/references/type-uml-class.md +65 -0
  122. package/src/skills/diagram-design/references/type-venn.md +26 -0
  123. package/src/skills/diagram-design/references/type-wardley.md +39 -0
  124. package/src/skills/diagram-design/references/type-waterfall.md +75 -0
  125. package/src/skills/document-project.md +4 -1
  126. package/src/skills/ownership.md +26 -4
  127. package/src/upstreams.json +14 -0
  128. package/themes/_TEMPLATE.json +1 -0
  129. package/themes/biker.json +1 -0
  130. package/themes/commentator.json +1 -0
  131. package/themes/cyberpunk.json +1 -0
  132. package/themes/gamer.json +1 -0
  133. package/themes/imperial.json +1 -0
  134. package/themes/joker.json +1 -0
  135. package/themes/marvin.json +1 -0
  136. package/themes/mean.json +1 -0
  137. package/themes/military.json +1 -0
  138. package/themes/neutral.json +1 -0
  139. package/themes/pirate.json +1 -0
  140. package/themes/sports.json +1 -0
  141. package/themes/verstappen.json +1 -0
  142. package/themes/wizard.json +1 -0
@@ -0,0 +1,232 @@
1
+ # Style Guide
2
+
3
+ **The single source of truth for colors, typography, and tokens.** Every diagram draws from this — not from hex values inlined in other reference files. If you want to change the visual skin of Diagram Design, change this file.
4
+
5
+ Default skin is a cool editorial palette — white-smoke paper, jet-black ink, burnt-tangerine accent, blue-slate muted. It's designed to look good out of the box; swap these values (or run [`onboarding.md`](onboarding.md)) and every new diagram inherits the new skin without touching any type-specific logic.
6
+
7
+ To generate your own from a website URL, see [`onboarding.md`](onboarding.md).
8
+
9
+ ---
10
+
11
+ ## Tokens
12
+
13
+ ### Semantic roles
14
+
15
+ Every token is referred to by **semantic role**, not by its hex value. Type references (`type-*.md`) and SKILL.md say `accent`, not `#bf4520`.
16
+
17
+ | Role | Purpose | Default (light) | Default (dark) |
18
+ |---|---|---|---|
19
+ | `paper` | Page background, default node fill | `#f5f5f5` (white-smoke) | `#2d3142` (jet-black) |
20
+ | `paper-2` | Diagram container bg, secondary fill | `#ececec` | `#393e53` |
21
+ | `ink` | Primary text, primary stroke | `#2d3142` (jet-black) | `#f5f5f5` (white-smoke) |
22
+ | `ink-strong` | High-contrast text on warm accent fills | `#111111` | `#111111` |
23
+ | `muted` | Secondary text, default arrow stroke | `#4f5d75` (blue-slate) | `#bfc0c0` (silver) |
24
+ | `soft` | Sublabels, boundary labels | `#5a6580` | `#949eb2` |
25
+ | `rule` | Hairline borders | `rgba(45,49,66,0.12)` | `rgba(245,245,245,0.12)` |
26
+ | `rule-solid` | Stronger borders, baselines | `#bfc0c0` (silver) | `rgba(191,192,192,0.25)` |
27
+ | `accent` | Focal / 1–2 max per diagram | `#bf4520` (burnt-tangerine) | `#f08a59` |
28
+ | `accent-tint` | Fill for accent-bordered boxes | `rgba(191,69,32,0.08)` | `rgba(240,138,89,0.10)` |
29
+ | `link` | HTTP/API calls, external arrows | `#2e5aa8` | `#739fdf` |
30
+
31
+ > **Brand palette source:** this skin maps to a five-color brand palette: `jet-black #2d3142`, `silver #bfc0c0`, `white-smoke #f5f5f5`, `atomic-tangerine`, `blue-slate #4f5d75`. The light `accent` is not the raw brand tangerine. Raw atomic-tangerine reads 2.86:1 on `paper`, too faint for an arrow or a label, so the skin uses `#bf4520`, the same hue darkened until it clears 4.5:1 as text. The `soft`, `rule`, and `link` tokens are derived (a darker slate, ink at opacity, and a saturated variant in the blue-slate hue family) to cover roles the brand palette doesn't name directly. Every derived value is held to the contrast contract below.
32
+
33
+ ### Contrast contract
34
+
35
+ Every token must clear the threshold for each role it plays, against the background it actually sits on, in both skins. `scripts/verify-contrast.py` computes the WCAG 2.x ratio for every row above against the `paper` of its skin (`ink-strong` against the 0.85 `accent` fill it labels) and fails CI when one falls short.
36
+
37
+ | Use | Minimum vs. its actual background |
38
+ |---|---|
39
+ | Regular text, including any `soft`, `link`, or `accent` used as text | 4.5:1 |
40
+ | Large text (24px+, or 18.7px+ at weight 600+) | 3:1 |
41
+ | Essential non-text marks: lines, arrows, borders, focus outlines, data points | 3:1 against the adjacent color |
42
+ | Decorative rules and translucent tints (`rule`, `rule-solid`, `paper-2`, `accent-tint`, fills at opacity) | No minimum, but never the only carrier of meaning |
43
+
44
+ - **A token used in several roles must pass each one.** `accent` is a stroke in one place and a label in another, so it is held to 4.5:1, not the 3:1 its strokes alone would need. Don't assume a token is non-text because it usually is.
45
+ - **Translucent colors are composited first.** An `rgba()` fill or stroke is blended over `paper` before its ratio is measured. A value that clears the bar at full strength can fail at 0.5 opacity.
46
+ - **Surfaces other than `paper` cost contrast.** Inside an `accent-tint` box or on `paper-2` every ratio drops. Measure text placed there against that surface, not against `paper`.
47
+ - **Current defaults:** light `accent` 4.71:1, `soft` 5.34:1, `link` 6.13:1, `muted` 6.11:1 on `#f5f5f5`; dark `accent` 5.21:1, `soft` 4.78:1, `link` 4.76:1 on `#2d3142`.
48
+
49
+ ### Inversion rule (light → dark)
50
+
51
+ Any `rgba(45,49,66, X)` in light becomes `rgba(245,245,245, X)` in dark. Same opacities, RGB flipped. The accent gets a slight hue-shift brighter to read on dark paper.
52
+
53
+ ### Series palette (multi-series chart types only)
54
+
55
+ A small set of desaturated, editorial-tone colors for chart types that genuinely need to distinguish multiple overlapping entities (currently: **radar**). The "1-focal" rule still holds — `accent` is reserved for the focal series; the palette below covers the rest.
56
+
57
+ | Token | Light | Dark | Notes |
58
+ |---|---|---|---|
59
+ | `series-1` | `#7c8f6f` (sage) | `#9caf8f` | Non-focal series |
60
+ | `series-2` | `#5e7a9b` (dusty-blue) | `#82a0c0` | Non-focal series |
61
+ | `series-3` | `#b8915a` (mustard) | `#d3ad7a` | Non-focal series |
62
+ | `series-4` | `#9c6b50` (rust-brown) | `#b88670` | Non-focal series |
63
+ | `series-5` | `#6e6479` (slate) | `#8d8298` | Non-focal series |
64
+
65
+ Fills sit at `0.18` opacity light, `0.22` dark; strokes use the full color. **Don't backfill these tokens to non-chart types** — architecture, swimlane, etc. continue to use muted-ink variants. The series palette is opt-in for diagrams where overlapping shapes demand distinguishable color, not a license to add color elsewhere.
66
+
67
+ ### Terminal skin (opt-in alternate)
68
+
69
+ A self-contained palette for the terminal-window primitive (see [primitive-terminal.md](primitive-terminal.md)) — a CLI-chrome register for dev-tool posts and technical social cards. It does not replace the default skin above and isn't affected by onboarding; it's a second, fixed skin you opt into per-diagram.
70
+
71
+ | Token | Hex | Purpose |
72
+ |---|---|---|
73
+ | `terminal-page` | `#0a0a0a` | Page background behind the window |
74
+ | `terminal-paper` | `#141414` | Window body, node fill |
75
+ | `terminal-bar` | `#1b1b1b` | Titlebar strip |
76
+ | `terminal-border` | `#2b2b2b` | Window border, hairlines |
77
+ | `terminal-ink` | `#f5f5f5` | Primary text, primary stroke (same white-smoke as default `ink`) |
78
+ | `terminal-muted` | `#9a9a9a` | Secondary text, sublabels, ring stroke |
79
+ | `terminal-soft` | `#5c5c5c` | Tertiary — inactive dots, spokes |
80
+ | `terminal-accent` | `#ff5a36` | The one accent — focal station, prompt sign, active dot |
81
+ | `terminal-accent-tint` | `rgba(255,90,54,0.12)` | Fill for accent-bordered boxes |
82
+
83
+ **1-accent rule still holds.** Everything that isn't `terminal-ink` or `terminal-muted`/`terminal-soft` should be `terminal-accent` — never introduce a second hue.
84
+
85
+ ---
86
+
87
+ ## Typography
88
+
89
+ | Role | Family | Size | Weight | Usage |
90
+ |---|---|---|---|---|
91
+ | `title` | Instrument Serif | 1.75rem | 400 | Page H1 |
92
+ | `node-name` | Geist (sans) | 12px | 600 | Human-readable labels |
93
+ | `sublabel` | Geist Mono | 9px | 400 | Port, protocol, URL, field type |
94
+ | `eyebrow` | Geist Mono | 7–8px | 500, tracked 0.18em, uppercase | Type tags, axis labels |
95
+ | `arrow-label` | Geist Mono | 8px | 400, tracked 0.06em | Arrow annotations |
96
+ | `callout` | Instrument Serif *italic* | 14px | 400 | Editorial asides only |
97
+
98
+ ### Font stack
99
+
100
+ ```html
101
+ <link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Geist:wght@400;500;600&family=Geist+Mono:wght@400;500;600&family=Noto+Serif:ital@0;1&family=Noto+Sans+KR:wght@400;500;600&family=Noto+Serif+KR:wght@400&family=Noto+Sans+TC:wght@400;500;600&family=Noto+Serif+TC:wght@400&display=swap" rel="stylesheet">
102
+ ```
103
+
104
+ ### Font source
105
+
106
+ The font source decides whether a diagram makes any network request. It is a skin setting, so a saved profile carries it too.
107
+
108
+ Font source: `web`
109
+
110
+ | Value | What ships | Network |
111
+ |---|---|---|
112
+ | `web` (default) | The Google Fonts `<link>` above; text renders in Instrument Serif, Geist, and Geist Mono | One stylesheet request to `fonts.googleapis.com`, plus the font files |
113
+ | `system` | No font `<link>`; every family stack falls through to the platform's own serif, sans, and monospace faces | None |
114
+
115
+ Use `system` when the user asks for offline output, system fonts, or no Google Fonts, or when this line says `system`. In `system` mode:
116
+
117
+ - Omit the font `<link>` (and the export `@import`) entirely. Keep every `font-family` stack as written: each one already ends in a generic family (`serif`, `system-ui, sans-serif`, `ui-monospace, monospace`), so a viewer who has Geist installed still gets it and everyone else gets their system face.
118
+ - Fallback faces have different metrics from Geist, so keep the 8px label padding intact rather than trimming boxes to the Geist measurement.
119
+ - Check that the Google Fonts link is no longer present.
120
+
121
+ The render linter's default run (`lint-render.py` with network blocked) measures exactly this fallback rendering, so every shipped template and example is already checked in system-font mode.
122
+
123
+ To keep the editorial faces with no network at all, install Instrument Serif, Geist, and Geist Mono locally (all three are SIL Open Font License) and use `system`: the stacks resolve to the installed faces first.
124
+
125
+ ### Korean labels
126
+
127
+ Geist and Instrument Serif carry no Hangul. A Korean `<text>` element extends its own family — never swap the skin:
128
+
129
+ ```svg
130
+ <text font-family="'Geist', 'Noto Sans KR', 'Apple SD Gothic Neo', 'Malgun Gothic', sans-serif">결제 서비스</text>
131
+ ```
132
+
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
+
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.
136
+
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
+
139
+ Three rules follow from Hangul metrics:
140
+
141
+ - **Sublabels stay Latin.** Ports, protocols, field types, and URLs are Latin anyway — keep `Geist Mono` there and don't translate them. Hangul in a 9px mono sublabel is unreadable and has no mono face to fall back to.
142
+ - **Floor of 12px.** Hangul goes muddy below 12px. If a Korean name doesn't fit at 12px, cut the name — don't shrink the type.
143
+ - **Arrow labels, eyebrows, and legend text switch register.** Those slots are 7–8px Geist Mono, uppercase and tracked, which Hangul has neither a face nor legibility for. A Korean label in one of those slots becomes 12px sans at weight 500 with no tracking and no uppercase transform, and its mask rect grows to match (16px tall, width from the budget above, still rounded to a multiple of 4). Latin labels in the same diagram keep the mono treatment.
144
+
145
+ **Load-bearing rule:** Mono is for *technical* content (ports, commands, URLs, field types). Names go in Geist sans. Page title is Instrument Serif. Italic Instrument Serif is reserved for annotation callouts (see [primitive-annotation.md](primitive-annotation.md)). **Never JetBrains Mono** as a blanket "dev" font.
146
+
147
+ ### Traditional Chinese labels
148
+
149
+ Geist and Instrument Serif carry no Han. A Traditional Chinese `<text>` element extends its own family — never swap the skin:
150
+
151
+ ```svg
152
+ <text font-family="'Geist', 'Noto Sans TC', 'PingFang TC', 'Microsoft JhengHei', sans-serif">請求項比對</text>
153
+ ```
154
+
155
+ Both Noto TC 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 TC', serif` — or a mixed Latin/Han title resolves Han through the platform's generic serif and the two halves disagree. Google's `css2` endpoint slices Chinese by unicode-range, so a diagram with a handful of Chinese labels downloads only the slices it touches.
156
+
157
+ **Width budget.** The per-character contract above is unchanged: every Unicode wide or full-width character costs 1em, every other character costs its face's Latin advance, and nonspacing marks cost nothing. Full-width punctuation — `()「」,。:` — is wide and costs 1em as well, which is the part most often dropped.
158
+
159
+ Counting by script is the trap. `請求項 v2.1` is three full-width characters and five narrow ones; a formula that tallies Han and Latin letters silently drops `2`, `.`, and `1` and sizes the box for six of its nine characters.
160
+
161
+ Three rules follow from Han metrics, mirroring the Hangul ones:
162
+
163
+ - **Sublabels stay Latin.** Ports, protocols, field types, and URLs are Latin anyway — keep `Geist Mono` there and don't translate them. Han in a 9px mono sublabel is unreadable and has no mono face to fall back to. A sublabel that is prose rather than a value may be Chinese, but it then switches register by the third rule below.
164
+ - **Floor of 12px.** Han packs more strokes than Hangul into the same em box, so the 12px floor binds at least as hard here. If a Chinese name doesn't fit at 12px, cut the name — don't shrink the type.
165
+ - **Arrow labels, eyebrows, and legend text switch register.** Those slots are 7–8px Geist Mono, uppercase and tracked, which Han has neither a face nor legibility for. A Chinese label in one of those slots becomes 12px sans at weight 500 with no tracking and no uppercase transform, and its mask rect grows to match (16px tall, width from the budget above, still rounded to a multiple of 4). Latin labels in the same diagram keep the mono treatment.
166
+
167
+ Simplified Chinese takes the same three rules with the Simplified stack (`'Noto Sans SC'`, `'PingFang SC'`, `'Microsoft YaHei'`). That face does not ship in the link, so Simplified labels still resolve through whatever the viewer has locally.
168
+
169
+ ### Cyrillic labels
170
+
171
+ Geist and Geist Mono ship Cyrillic (`cyrillic` and `cyrillic-ext` on Google Fonts), so names, sublabels, arrow labels, eyebrows, and legend text in Bulgarian, Russian, Ukrainian, or Serbian keep the Latin treatment: same faces, sizes, tracking, and uppercase. There is no register switch: Hangul and Han switch register because Geist Mono has no face for them, and Geist Mono does cover Cyrillic.
172
+
173
+ Instrument Serif carries no Cyrillic. A page title extends its family — `'Instrument Serif', 'Noto Serif', serif` — or a mixed Latin/Cyrillic title resolves Cyrillic through whatever face comes next and the two halves disagree. Noto Serif ships in the font link above, upright and italic, so an italic callout in Cyrillic takes the same stack.
174
+
175
+ **Noto Serif goes ahead of the CJK serifs.** When a stack also lists `'Noto Serif KR'` or `'Noto Serif TC'`, put `'Noto Serif'` ahead of them. Google Fonts slices Cyrillic into those faces as well, so a stack that reaches a CJK face first draws its Cyrillic from it. That is why the templates put `'Noto Serif'` between `'Instrument Serif'` and `'Noto Serif KR'`; Noto Serif has no Hangul or Han, so Korean and Chinese titles pass straight through it.
176
+
177
+ **Width budget.** The per-character contract above is unchanged: every character costs its face's Latin advance (0.60em sans, 0.62em mono). It fits Geist Mono exactly and Geist sans only on average. Geist Mono is monospaced: a Cyrillic glyph advances exactly as far as a Latin one, so sublabels, arrow labels, eyebrows, legend text, and their mask rects are sized as for Latin. Geist sans is not. Its wide Cyrillic letters, capitals and lowercase alike (such as `Ж Ш Щ Ю Ы`, `ж ш щ ы ю`), run well past the 0.60em average: `Шкаф ODF-2` at 12px is budgeted at 72px and draws at about 76. Rounding the box up to a multiple of 4 recovers at most 3px, so it is not the remedy. Leave the overshoot in the box padding and measure a Cyrillic sans name in the browser — `verify-treemap.py` holds the budget, not the drawn width, so it will not catch the overshoot.
178
+
179
+ Counting by script is still the trap. `Шкаф ODF-2` is four Cyrillic letters, a space, three Latin letters, a hyphen, and a digit; a formula that tallies Cyrillic letters, Latin letters, and spaces silently drops `-` and `2` and sizes the box for eight of its ten characters.
180
+
181
+ **Preserve printed labels.** A label the reader matches against a physical thing — a cabinet, a splice closure, a port map — carries the exact printed string. Don't transliterate it and don't re-case it; if one has to sit in an uppercase slot such as an eyebrow, drop the transform for that label rather than re-case the printed string. `Шкаф ODF-2` stays `Шкаф ODF-2`, not `Shkaf ODF-2`.
182
+
183
+ ---
184
+
185
+ ## Stroke, radius, spacing
186
+
187
+ | Token | Value | Use |
188
+ |---|---|---|
189
+ | `stroke-thin` | `0.8` | Tag-box outlines, leaf nodes |
190
+ | `stroke-default` | `1` | Most strokes |
191
+ | `stroke-strong` | `1.2` | Emphasis strokes |
192
+ | `radius-sm` | `4` | Small tags |
193
+ | `radius-md` | `6` | Node boxes |
194
+ | `radius-lg` | `8` | Containers, rings |
195
+ | `grid` | `4` | Every coord, size, and gap is divisible by 4 (hard rule) |
196
+
197
+ ---
198
+
199
+ ## Node type → treatment
200
+
201
+ Semantic role combinations — reference these by name in type specs.
202
+
203
+ | Type | Fill | Stroke |
204
+ |---|---|---|
205
+ | `focal` (1–2 max) | `accent-tint` | `accent` |
206
+ | `backend` | `#ffffff` (white) | `ink` |
207
+ | `store` | `ink @ 0.05` | `muted` |
208
+ | `external` | `ink @ 0.03` | `ink @ 0.30` |
209
+ | `input` | `muted @ 0.10` | `soft` |
210
+ | `optional` | `ink @ 0.02` | `ink @ 0.20` dashed `4,3` |
211
+ | `security` | `accent @ 0.05` | `accent @ 0.50` dashed `4,4` |
212
+
213
+ ---
214
+
215
+ ## Customizing the skin
216
+
217
+ Four options:
218
+
219
+ 1. **Run onboarding** — see [`onboarding.md`](onboarding.md). Drop a URL; the skill extracts the palette + fonts and rewrites this file.
220
+ 2. **Edit by hand** — change the hex values in the tables above. Run the pre-output taste gate afterward to verify the accent still reads as "focal" against the new paper color.
221
+ 3. **Brand handoff** — paste your existing design-token JSON into a new section here and map its tokens to the semantic roles above.
222
+ 4. **Client profiles** — save and switch named skins, or bind one to a project, using [`profiles.md`](profiles.md).
223
+
224
+ ### Constraints (don't break these)
225
+
226
+ - **Contrast**: every text token (`ink`, `muted`, `soft`, `link`, and `accent`) must clear 4.5:1 on `paper`, in both skins. See the [contrast contract](#contrast-contract); `scripts/verify-contrast.py` checks it.
227
+ - **One accent**: pick one color for `accent`. Two accents erases the focal signal.
228
+ - **No rainbow palette**: if your brand ships 8 colors, pick 3 (paper, ink, accent). The rest become `muted` variants.
229
+ - **Serif + sans + mono**: three families, not more. If brand typography is all sans, keep Instrument Serif for `title` and `callout` anyway — the contrast is load-bearing.
230
+ - **Paper is warm-neutral, not pure white**: pure white turns the design sterile. Pick a cream, bone, or light grey with a hint of warmth.
231
+ - **Dot pattern is optional, not default**: the 22×22 dot pattern is an opt-in "dotted paper" variant (good for long-form editorial hero diagrams). The default background is a clean `paper` fill, no pattern. When the pattern is enabled, it should sit at ~10% opacity of `ink` on `paper` — visible but quiet.
232
+ - **Container is clean by default**: the diagram sits directly on the page paper, no secondary container background or border. A framed variant (`paper-2` bg + `rule` border + 8px radius + padding) is available as an opt-in for card-heavy layouts, but don't reach for it by default — the extra chrome fights the figure.
@@ -0,0 +1,143 @@
1
+ # Architecture delta
2
+
3
+ **Best for:** explaining a system migration, service extraction, infrastructure redesign, or integration change through two synchronized topology snapshots. Show which components and relationships survive, appear, disappear, change their properties, move, or reconnect.
4
+
5
+ **Not this type:**
6
+
7
+ - One system snapshot → **Architecture** (`type-architecture.md`).
8
+ - Attribute-only differences without a topology story → a **comparison table**. Two versions of a configuration do not need two node maps.
9
+ - Requests over time → **Sequence** (`type-sequence.md`); deployment phases → **Timeline** (`type-timeline.md`). A delta has exactly two states and does not establish migration order, downtime, or causality.
10
+ - Host/container placement in one environment → **Deployment** (`type-deployment.md`).
11
+
12
+ ## Layout conventions
13
+
14
+ - **Three panels, one reading order: Before · Changes · After.** Both topology panels use the same width, height, and internal grid pitch. The center panel is a short change ledger, not a third topology. Name the two snapshots with meaningful versions or dates.
15
+ - **Keep the mental map stable.** Start by copying the Before coordinates into After. Move a retained component only when its movement is part of the story and receives a `MOVED` entry. Do not independently run a layout algorithm on each panel.
16
+ - **Panel positions are not component positions.** Put each snapshot in one SVG `<g transform="translate(x y)">`; write component bounds and relationship paths in local coordinates. The Before and After origins share one y-coordinate, with the ledger occupying the horizontal gap.
17
+ - **Shared grid:** use a 4px pitch by default. Every component's local x, y, width, and height is a multiple of that pitch. The shipped example uses two `336 480 4` grids; scale the overall SVG responsively without changing their local geometry.
18
+ - **Budget:** at most **8 unique components**, **10 unique relationships**, and **8 ledger entries** across the complete comparison. A retained ID counts once, not once per snapshot. A component that is both changed and moved consumes two ledger entries. Split larger migrations into named subsystems or phases; never drop edges to fit.
19
+ - **Connectors:** use Architecture's rounded orthogonal routing and port rules. In this type, even straight connectors are `<path>` elements so relationship identity and endpoints have one grammar. Draw paths before components. A stable relationship may take a different route to meet a moved component without becoming `REWIRED`.
20
+ - **Nodes:** print the same stable ID in both states along with the human-readable name. Treat names, responsibilities, implementation versions, and protocols as semantic attributes; identities survive a rename when the underlying object survives.
21
+ - **Ledger:** one brief entry per `(object ID, change)` pair. Begin with the uppercase change word, name the object, and state the actual difference. Do not describe unchanged objects in the ledger. Keep a readable text measure, with wrapped `<tspan>` lines when needed.
22
+ - **Responsive presentation:** preserve the three-panel comparison on small screens with an accessible horizontal scroll region and a visible scroll hint. Do not compress labels until they become illegible or stack snapshots into independently scaled pictures. Print and export keep the whole comparison.
23
+
24
+ ## Change vocabulary and redundant encoding
25
+
26
+ Color is secondary. Every change is readable from text plus a shape or line treatment; unchanged objects remain quiet context. Use the existing skin tokens and reserve the accent for the editorial focus, rather than assigning five status colors.
27
+
28
+ | State | Meaning | Non-color treatment |
29
+ |---|---|---|
30
+ | `unchanged` | Same identity, semantics, position, and endpoints | Plain solid outline; no ledger entry |
31
+ | `added` / **ADDED** | Present only in After | `+` badge or plus-shaped marker; solid outline |
32
+ | `removed` / **REMOVED** | Present only in Before | `−` badge and dashed outline/path |
33
+ | `changed` / **CHANGED** | Retained object whose semantic signature differs | `Δ` badge or inset rule, plus an explicit old → new ledger description |
34
+ | `moved` / **MOVED** | Retained component whose local x or y differs | Direction/position marker and a ledger entry naming the relocation |
35
+ | `rewired` / **REWIRED** | Retained relationship whose ordered source/target IDs differ | Distinct dash treatment or endpoint marker, with old → new endpoints written in the ledger |
36
+
37
+ Do not use a missing After node to stand for a removal without a `REMOVED` entry. Do not substitute an `ADDED` edge for a `REWIRED` edge just to avoid explaining endpoint identity. A replacement component gets a new stable ID and separate removal/addition entries; its location alone cannot establish continuity.
38
+
39
+ ## Public HTML metadata contract
40
+
41
+ This is the authoring and validation surface, not a serialization inferred from visible labels. All attributes below are required where applicable; empty, boolean, duplicate, or malformed declarations are findings. IDs are case-sensitive and match `[A-Za-z][A-Za-z0-9_.:-]*`; they contain no whitespace.
42
+
43
+ ### Diagram and snapshots
44
+
45
+ The file has exactly one `<svg data-diagram="architecture-delta">`. Keep the standard accessible SVG title/description contract. Two direct child `<g>` elements declare `data-snapshot="before"` and `data-snapshot="after"`. Each has:
46
+
47
+ - `data-grid="<width> <height> <pitch>"`: the same three positive finite numbers in both panels. Width and height are multiples of pitch.
48
+ - `transform="translate(<x> <y>)"`: exactly one finite two-number translation, solely for the panel origin. Comma-separated translations are also accepted.
49
+
50
+ Snapshot membership is inherited from the enclosing group. An object cannot be outside both snapshots, in nested snapshots, or nested inside another object. Other geometry transforms, nested SVG viewports, SVG animation, `<use>`, and foreign objects are outside this static grammar. Do not put objects or ledger entries in `<defs>`, `<symbol>`, templates, or other nonrendering containers.
51
+
52
+ ### Components
53
+
54
+ Each component is a `<g>` declaring:
55
+
56
+ | Attribute | Contract |
57
+ |---|---|
58
+ | `data-kind="component"` | Identifies a component group |
59
+ | `data-object-id` | Stable object identity, unique within each snapshot |
60
+ | `data-status` | One lowercase state or the space-separated combination `changed moved` |
61
+ | `data-signature` | Nonempty semantic signature; see the signature rules below |
62
+
63
+ The group contains exactly one **direct** `<rect data-role="bounds">` with explicit finite numeric `x`, `y`, `width`, and `height`. Position is nonnegative, size is positive, and the rectangle stays inside its local grid. All four values align with grid pitch. These are the actual drawn node bounds, not a hidden proxy rectangle.
64
+
65
+ ### Relationships
66
+
67
+ Each relationship is a `<path>` with `data-kind="relationship"`, `data-object-id`, `data-status`, `data-signature`, and `data-from` / `data-to`. Its stable ID is separate from component IDs. Both endpoints resolve to component IDs in the **same snapshot**. Endpoint order is directional: swapping source and target is a rewire.
68
+
69
+ Every path inside a snapshot and outside a component is a relationship and must carry the complete metadata. Decorative paths belong inside their component, or outside the snapshot for panel rules and ledger separators. Deleting all metadata from a connector must not make it disappear from validation.
70
+
71
+ Relationship statuses are `unchanged`, `added`, `removed`, `changed`, `rewired`, or the combination `changed rewired`. `moved` applies to components only; `rewired` applies to relationships only. `unchanged`, `added`, and `removed` cannot be combined with any other token.
72
+
73
+ The `d` attribute is one absolute `M` followed by absolute `L`, `H`, `V`, `Q`, or `C` segments. Implicit repeated coordinate groups are accepted. Relative commands, additional subpaths, closed paths, arcs, missing coordinates, and non-finite coordinates fail closed. Use orthogonal lines and quadratic corners for the standard layout; cubic segments are available for a small crossing bridge. Endpoints and control points remain inside the local grid. The path's start meets the source rectangle's perimeter and its end meets the target's perimeter, within 2px for stroke/arrow-cap rounding.
74
+
75
+ ### Status and signature rules
76
+
77
+ - An ID present only in Before is exactly `removed`; an ID present only in After is exactly `added`.
78
+ - A retained ID keeps its kind and the same status set in both snapshots. Never recycle a component ID for a relationship or vice versa.
79
+ - A signature differs **if and only if** the retained object is `changed`. Construct it deterministically from the semantic attributes you want to compare, such as `orders-api:v2;mode=enqueue` or `protocol=https;operation=create-order`. Include a changed display name if renaming is part of the story. Preserve attribute order and spelling when values are unchanged.
80
+ - Signatures exclude the object ID, snapshot, status, coordinates, visual styles, and relationship endpoints. These have their own checks. A movement or rewire alone must not change the signature.
81
+ - A retained component's local `(x,y)` differs **if and only if** it is `moved`. A width/height change additionally requires `changed` and a changed signature. A changed signature alone does not require different bounds.
82
+ - A retained relationship's ordered `(data-from,data-to)` pair differs **if and only if** it is `rewired`. Its path may reroute while that pair stays the same, for example when an endpoint component moves.
83
+ - Numeric declarations are finite and have absolute values no larger than 10,000,000; unit suffixes, percentages, and CSS calculations are not coordinate declarations.
84
+
85
+ ### Ledger
86
+
87
+ Each entry is a visible SVG `<text>` outside both snapshots, with `data-change="ADDED|REMOVED|CHANGED|MOVED|REWIRED"` and `data-target="<one object ID>"`. Its rendered text begins with the same uppercase word and continues with an explanation. Descendant `<tspan>` text is included when checking the wording; put the metadata on the outer `<text>` only.
88
+
89
+ The ledger is an exact set of `(target, change)` pairs implied by object statuses. There are no missing entries, duplicate pairs, unknown targets, or entries for unchanged objects. The same target can have two entries only when it declares two changes. Every diagram contains at least one ledger entry, at least one component in each snapshot, and at least one relationship overall.
90
+
91
+ ### Worked metadata pattern
92
+
93
+ This excerpt shows one changed component; a complete diagram also needs its other components, relationships, and accessible SVG title/description.
94
+
95
+ ```svg
96
+ <svg data-diagram="architecture-delta" viewBox="0 0 1000 400">
97
+ <g data-snapshot="before" data-grid="320 320 4" transform="translate(24 64)">
98
+ <g data-kind="component" data-object-id="orders" data-status="changed"
99
+ data-signature="orders-api:v1;mode=dispatch">
100
+ <rect data-role="bounds" x="80" y="96" width="144" height="64"/>
101
+ <text x="96" y="120">orders · direct dispatch</text>
102
+ </g>
103
+ </g>
104
+ <g data-snapshot="after" data-grid="320 320 4" transform="translate(656 64)">
105
+ <g data-kind="component" data-object-id="orders" data-status="changed"
106
+ data-signature="orders-api:v2;mode=enqueue">
107
+ <rect data-role="bounds" x="80" y="96" width="144" height="64"/>
108
+ <text x="96" y="120">orders · enqueue</text>
109
+ </g>
110
+ </g>
111
+ <text data-change="CHANGED" data-target="orders" x="376" y="176">
112
+ <tspan>CHANGED orders</tspan>
113
+ <tspan x="376" dy="20">Direct dispatch → enqueue</tspan>
114
+ </text>
115
+ </svg>
116
+ ```
117
+
118
+ ## Verification and its boundaries
119
+
120
+ Upstream checks this with `verify-architecture-delta.py`, which this copy does not ship. Its stdlib HTML parser reads real attributes, including unquoted values and entities, ignores comments, and rejects malformed SVG nesting. Synthetic fixtures prove both legal cases and adversarial changes independently of the shipped coordinates; the light, dark, and full variants are checked too.
121
+
122
+ The verifier enforces the declared structure, differential semantics, grid/bounds geometry, drawn relationship endpoints, budgets, and exact ledger coverage. It rejects CSS transforms/position overrides, CSS sizing that could change bounds, escaped CSS declarations, explicit hidden objects/ledger, and common CSS hiding rules. Ordinary responsive sizing of the outer SVG remains legal.
123
+
124
+ It is **not** a browser renderer or a proof of the source system. Authors remain responsible for honest signatures, labels matching those signatures, readable shape/dash treatments, and an accurate migration story. Exotic CSS cascade/variable effects, clipping and occlusion, connector crossings, intermediate segment clearance, ledger placement, and screen-reader quality still require the normal skin, accessibility, geometry, and rendered-layout gates plus desktop/mobile visual review. Keep semantic geometry in the SVG attributes instead of making CSS part of the data model.
125
+
126
+ ## Anti-patterns
127
+
128
+ - Two independently arranged snapshots that manufacture apparent movement.
129
+ - A center ledger that says only “updated” without naming the object and difference.
130
+ - Color-only statuses or a separate bright color for every kind of change.
131
+ - Unchanged node positions drifting to make room, with no `MOVED` entry.
132
+ - Semantic edits hidden behind an unchanged signature, or all signatures regenerated just because the snapshot changed.
133
+ - Redrawing an edge to a different component while keeping its endpoint metadata unchanged.
134
+ - Counting retained objects twice to justify dropping other objects from the comparison.
135
+ - Treating this comparison as an executable migration plan. Ordering, rollback, availability, and data consistency need their own explanation.
136
+
137
+ ## Examples
138
+
139
+ - `assets/example-architecture-delta.html` — minimal light order-fulfilment migration; all five change kinds.
140
+ - `assets/example-architecture-delta-dark.html` — minimal dark, identical IDs, signatures, topology, and coordinates.
141
+ - `assets/example-architecture-delta-full.html` — full editorial treatment of the same migration.
142
+
143
+ The example retains the storefront and order store, changes the order API to enqueue work, removes the legacy dispatcher, adds a durable order queue, moves the fulfilment worker, and rewires order submission. Stable relationships follow the worker's new location while preserving their IDs and endpoint semantics.
@@ -0,0 +1,117 @@
1
+ # Architecture
2
+
3
+ **Best for:** system overviews, data-flow diagrams, integration maps, infra topology.
4
+
5
+ ## Layout conventions
6
+ - Group components by tier or trust boundary (frontend → backend → data; public → private).
7
+ - Primary flow runs left→right or top→down. Pick one and hold it.
8
+ - Draw arrows before boxes so z-order puts connections behind components.
9
+ - 1–2 coral focal nodes: the primary integration point, the primary data store, or the key decision node.
10
+ - Dashed boundary rectangles mark regions (VPC, security group, trust zone); labels sit on a paper-colored mask over the boundary line.
11
+
12
+ ## Connector style
13
+
14
+ **Rounded right-angle (orthogonal) connectors are MANDATORY** for all non-horizontal/vertical connections — diagonal `<line>` between off-axis nodes is a hard fail (see SKILL.md §6 Mandatory connector rules). Two-bend elbow path with `r=8`:
15
+
16
+ ```svg
17
+ <!-- right+down: from (x1,y1) to (x2,y2), mid = (x1+x2)/2 -->
18
+ <path d="M x1,y1 H mid-8 Q mid,y1 mid,y1+8 V y2-8 Q mid,y2 mid+8,y2 H x2"
19
+ fill="none" stroke="…" stroke-width="1.2" marker-end="url(#arrow)"/>
20
+ ```
21
+
22
+ Flip the vertical signs for right+up. Use a plain `<line>` only when endpoints share the same x or y. Arrow labels sit on the vertical segment, centered horizontally on `mid` and vertically between the two corners.
23
+
24
+ **Port selection for vertical connectors.** When the destination is noticeably above or below the source, enter the destination through its top or bottom edge. Use a single-bend L-path: leave the source through the side edge that faces the destination's column, run horizontally, turn once, and run vertically into the destination:
25
+
26
+ ```svg
27
+ <!-- destination above source: leave the source's right edge at (x_right, y_port), enter the destination's bottom edge at x2 -->
28
+ <path d="M x_right,y_port H x2-8 Q x2,y_port x2,y_port-8 V y_dst"
29
+ fill="none" stroke="…" stroke-width="1.2" marker-end="url(#arrow)"/>
30
+ ```
31
+
32
+ Every segment leaves its box perpendicular to the edge it starts on. Never start a horizontal segment on a top or bottom edge: it runs along the border, hidden behind the node fill, and the arrow looks like it grows out of the corner. When two of these connectors leave the same side edge, fan their ports (primitives-core.md rule 4) and keep each port at least 8px from a corner so it never lands on the corner radius.
33
+
34
+ Reserve left/right ports on the destination for connections that travel primarily horizontally. Entering a node from the side on a mainly-vertical path looks like the arrow punctures the node face rather than arriving from above or below.
35
+
36
+ **Dashed paths — same routing rules.** Optional, return, async, and passive flows use `stroke-dasharray="4,3"` and a lighter stroke weight (`stroke-width="1"`). Apply the **same orthogonal routing, port-selection, and bridge/hop rules** as solid paths — the dash pattern only communicates semantic weight, not a different routing grammar. When a dashed path and a solid path must cross, bridge the dashed one (it is by definition the less important connection).
37
+
38
+ **Zone label margin.** Leave ≥16px between the bottom of the zone eyebrow label and the top of the first enclosed node. Size the zone rect tall enough to contain this header gap (zone `y` = node_top − 32; label mask `y` = zone_y + 4).
39
+
40
+ ## Crossing arrows — bridge / hop
41
+
42
+ When two orthogonal arrows must cross, add a small arc (hop/bridge) on the **less important** arrow at the crossing point. The more important arrow is drawn uninterrupted.
43
+
44
+ ```svg
45
+ <!-- Horizontal hop over a vertical crossing at x=cx, on a line at y -->
46
+ <path d="M x1,y H cx-8 a 8,8 0 0,1 16,0 H x2"
47
+ fill="none" stroke="…" stroke-width="1.2" marker-end="url(#arrow)"/>
48
+ ```
49
+
50
+ `a 8,8 0 0,1 16,0` is an SVG arc: rx=ry=8, large-arc=0, sweep=1 (curves visually upward), advancing 16px right — creating an 8px-radius semicircular bump over the crossing. For a vertical hop over a horizontal, use `a 8,8 0 0,0 0,16` on the vertical path.
51
+
52
+ Decide which arrow to bridge: bridge the one that is less semantically important (passive, secondary, write-back), or the one with lighter stroke weight (dashed, muted). Never bridge both.
53
+
54
+ ## Zone grouping
55
+
56
+ Group 2+ nodes that serve the same tier or trust boundary with a zone rect — drawn **before** arrows and nodes (z-order: bg → zones → arrows → nodes):
57
+
58
+ ```svg
59
+ <rect x="{x}" y="{y}" width="{w}" height="{h}" rx="8"
60
+ fill="{ink @ 0.02}" stroke="{ink @ 0.10}" stroke-width="0.8"/>
61
+ <rect x="{label_x}" y="{y+4}" width="{label_w}" height="12" rx="2" fill="{paper}"/>
62
+ <text x="{label_cx}" y="{y+13}" fill="{soft}" font-size="7"
63
+ font-family="{eyebrow}" text-anchor="middle" letter-spacing="0.14em">LAYER</text>
64
+ ```
65
+
66
+ Rules:
67
+ - Leave 12–16px above the first enclosed node — the eyebrow label sits in this margin.
68
+ - Zone fill: `ink @ 0.02` (2% ink wash). Any stronger competes with node fills.
69
+ - **Zone label: `soft`, never ink at an opacity.** A zone eyebrow is a boundary label, and `soft` is the boundary-label role in [`style-guide.md`](style-guide.md). An opacity such as `ink @ 0.40` composites differently on every `paper`; on a light warm paper it falls near 2.2:1, unreadable at 7px. The role carries its own contrast contract under any skin.
70
+ - Max 3 **flat** zones per diagram. More and it reads like a swimlane (use that type instead). Nested administrative and traffic scopes under **Containment** below are not this cap — they nest, so the cap is sibling traffic scopes at one level.
71
+ - Dark mode: the roles invert with the skin, so nothing is swapped by hand. Take `ink`, `soft`, and `paper` from the dark column in [`style-guide.md`](style-guide.md); opacities stay the same.
72
+
73
+ ## Containment
74
+
75
+ Use this section when **the network hierarchy itself carries the meaning** — the reader must see what sits inside which scope, and a flattened zone label (`VNET · SNET-APP`) would lie about that hierarchy. Connectors stay Architecture; containment geometry comes from Nested (consistent insets, eyebrow per level, fills stepping up inward). This is a variant of Architecture, not a new type and not a provider-specific grammar.
76
+
77
+ Two scope kinds, never interchangeable:
78
+
79
+ | Kind | What it is | Shape | `data-scope-kind` |
80
+ |---|---|---|---|
81
+ | **Administrative** | Billing, permissions, lifecycle. Holds no traffic. | Horizontal **band** — a full-width containment rect with a 24px header | `admin` |
82
+ | **Traffic** | A boundary packets do not cross without an explicit rule. | **Box** — the existing zone rect (`rx=8`) | `traffic` |
83
+
84
+ Provider-neutral metadata (no vendor prefix):
85
+
86
+ - `data-grammar="architecture-containment"` on the root `<svg>` — files without it are ordinary Architecture and this contract does not apply.
87
+ - `data-scope-id` + `data-scope-kind` on every scope's bounds rect (`data-role="bounds"`). Bounds are always a `<rect>`, for scopes and nodes alike.
88
+ - `data-parent` on every nested scope and every node, naming the innermost enclosing `data-scope-id`. Only the outermost scope, which no other scope encloses, may omit it.
89
+ - Nodes: `data-node-id`, `data-kind` of `compute` (workloads inside a traffic scope), `endpoint` (private endpoint inside a traffic scope), or `managed` (PaaS that belongs to an administrative scope).
90
+ - An `endpoint` carries `data-target` naming the `managed` node it reaches.
91
+ - A peering path carries `data-peering`, `data-from`, and `data-to` naming the two traffic scopes it joins.
92
+
93
+ **PaaS placement (normative).** A managed service is never inside a traffic scope. It sits in the administrative band that owns it. What lives in the subnet is its private endpoint. Drawing a database inside a subnet tells the reader it sits behind that subnet's security rules, which it does not. `scripts/verify-architecture-containment.py` fails a `managed` node whose bounds fall inside any `traffic` scope, and an `endpoint` that is not inside one.
94
+
95
+ **Sibling axis.** Sibling traffic scopes at one level share one axis. Directly under an administrative band the parent's aspect chooses it: wider than tall (or square) → a row sharing one `y`; taller than wide → a column sharing one `x`. Nested children take the perpendicular axis: siblings inside a traffic scope that sits in a row form a column, and their own children form a row again. Do not mix axes at one level.
96
+
97
+ **Budget** (tightens Architecture's flat 3-zone cap; see `layout-budget.md`): ≤2 administrative bands, ≤4 traffic scopes, ≤8 nodes, 2 accent elements. Split per subscription when a figure exceeds that.
98
+
99
+ **Draw scopes in place.** Containment is read from each bounds rect's own `x`, `y`, `width`, and `height`. Do not position a scope or node with a `transform` attribute, a moving inline style (`transform`, `translate`, `x`, `y`, `position`, `margin`, and similar), a nested `<svg>`, a `<style>` rule, or an animation, on the element or any group around it. The checker fails each of those. It does not evaluate external stylesheets or script, so keep containment geometry out of both.
100
+
101
+ `scripts/verify-architecture-containment.py` checks unique IDs, resolving innermost parents, geometric containment, `<rect>` bounds, the admin-band vs traffic-box shapes (with `stroke-dasharray` resolved as rendered, so `none` or all-zero dashes count as solid), PaaS placement, endpoint targets, sibling axes, declared peerings, and the moved-geometry rule above. Files without `data-grammar="architecture-containment"` are skipped.
102
+
103
+ ## Anti-patterns
104
+ - Every box in coral ("this is important too") — hierarchy collapses.
105
+ - Bidirectional arrow when one direction is obvious from context.
106
+ - Legend floating inside the diagram area.
107
+ - Flattening two containment levels into one zone eyebrow (`VNET · SNET-APP`) — the hierarchy is the claim.
108
+ - A managed PaaS box drawn inside a subnet or VPC — only its private endpoint belongs there.
109
+ - Colour as the only distinction between an administrative band and a traffic box — the shapes must differ, because greyscale still has to tell them apart.
110
+
111
+ ## Examples
112
+ - `assets/example-architecture.html` — minimal light
113
+ - `assets/example-architecture-dark.html` — minimal dark
114
+ - `assets/example-architecture-full.html` — full editorial
115
+ - `assets/example-architecture-containment.html` — nested admin/traffic scopes, light
116
+ - `assets/example-architecture-containment-dark.html` — nested admin/traffic scopes, dark
117
+ - `assets/example-architecture-containment-full.html` — nested admin/traffic scopes, full editorial
@@ -0,0 +1,83 @@
1
+ # Axonometric plan
2
+
3
+ **Best for:** one floor or one site seen from above at an angle, with what stands on it. An office floor with its rooms and furniture, a campus with its buildings and roads, a warehouse with its zones, a store layout. Use it when the reader needs to see rooms or buildings in relation to each other and how they are used, in a single view.
4
+
5
+ **Not this type:**
6
+
7
+ - Parts of one object pulled apart along an axis → **exploded axonometric** (`type-exploded.md`). A plan has one plate and nothing explodes.
8
+ - Containment without geography → **nested** (`type-nested.md`).
9
+ - Where software runs → **deployment** (`type-deployment.md`).
10
+ - A list of rooms and capacities → a table.
11
+
12
+ ## Projection
13
+
14
+ The same 2:1 dimetric projection as the exploded axonometric, from one function:
15
+
16
+ ```python
17
+ def iso(x, y, z, ox, oy):
18
+ """Model point to SVG point. (ox, oy) is where model (0, 0, 0) lands."""
19
+ return ox + x - y, oy + (x + y) / 2 - z
20
+ ```
21
+
22
+ Every element is a rounded prism standing on the plate: `r = 0` for walls, furniture, and buildings, `r = w / 2` for a tree canopy. `type-exploded.md` § Projection covers the corner ellipse and the face matrices; `scripts/build-axonometric-plan-examples.py` in the repository builds every shipped example from the same helpers.
23
+
24
+ ## Layout conventions
25
+
26
+ - **Plate:** One floor slab (6 units) or one site (8 units, small corner radius). Everything stands on it, and nothing extends past its edge.
27
+ - **Walls:** 6 units thick and cut at desk height, about 22 units, so no wall hides a room. Doors are gaps in a wall. Walls meet without overlapping: run one wall through a junction and stop the other at its face.
28
+ - **Furniture and buildings:** Boxes on the plate with the house face shading (`type-exploded.md` § Faces and lines). Heights are to scale with each other. Two footprints never overlap.
29
+ - **Flat marks:** Roads, paths, and floor tints sit on the plate's top face as flat fills (`ink` at 0.07) with no thickness. A dashed centre line (`ink` at 0.25, `6,5`) may mark a road.
30
+ - **Racks:** Tall shelving is a box of kind `rack` with the house shading, a shelf line every 14 units, and an upright every 30. Run rack rows along x so the reader sees the lit face and the aisles between rows.
31
+ - **Trees:** A canopy cylinder 8 units up on a short trunk, canopy top in `rule-solid` light or `soft` dark. Trees are planting, so keep them small and off every footprint.
32
+ - **Paint order:** The plate first, then flat marks, then every box back to front. Sort with a topological order: box A paints before box B when A lies entirely behind B (`A.x1 <= B.x0` or `A.y1 <= B.y0`) and their screen outlines overlap. A plain `x + y` sort fails on long walls.
33
+ - **Frame:** The canvas is 1000 wide and the plate is centred. The viewBox height follows the plate and its tallest box plus a 48px top margin.
34
+
35
+ ### Tags
36
+
37
+ - Rooms and buildings are named by a horizontal tag: the name in the `node-name` role, 600, 12px, above a sublabel in the `sublabel` role at 8px, on an opaque `paper` backing with a `rule` hairline, 32px tall, width rounded up to a multiple of 4.
38
+ - A room's tag sits on open floor inside the room. A building's tag sits on its roof. Tags paint after every box so walls never cut them.
39
+ - Tags never overlap each other. Move a tag to open floor before you shorten its name.
40
+ - One or two words per name. No leader lines and no numbered key.
41
+
42
+ ### Focal element
43
+
44
+ One room or one building wears the accent. A focal room gets an `accent` tint on its floor and an accent tag; a focal building gets the accent face ramp and an accent tag. Furniture inside a focal room stays neutral, so the accent marks one thing.
45
+
46
+ ## Optional motion
47
+
48
+ A site that is built in phases can reveal its buildings phase by phase with the pinned controller from `assets/template-motion.html` in `reveal` mode. Each building and its tag form one `data-motion-item` whose `data-step` is its phase, at most two per step. Buildings drop 16px into place and fade in, inside the 24px limit in `animation.md`.
49
+
50
+ A floor plan can reveal by zone the same way. Give each zone's furniture a `step`, and the builder paints each phase as one contiguous group of boxes (it contracts a phase to one node in the depth sort, so a phase that would have to paint on both sides of a static wall fails the build) plus one group of that phase's room tags after every box. That is two motion items per phase, inside the limit of two per step. Walls and unphased rooms stay static. The static, no-JavaScript, reduced-motion, print, and export states show the finished site.
51
+
52
+ ## Metadata contract
53
+
54
+ `scripts/verify-axonometric-plan.py` reprojects each element from what it declares:
55
+
56
+ - The figure: one `<g data-axo-plan data-origin="ox oy">`.
57
+ - The plate: one `<g data-plate data-rect="x0 y0 x1 y1 r" data-z="0" data-t="t">`.
58
+ - Each box: a `<g data-box>` with `data-rect`, `data-z` (the plate top, or 8 above it for a tree canopy), `data-h`, `data-kind` (`wall`, `furniture`, `building`, `tree`, `rack`), and for a building `data-name`. Its first path is `data-role="silhouette"`.
59
+ - Each room: a `<g data-room data-name data-rect>`.
60
+ - Each tag: a `<g data-role="tag" data-name data-at="x y z">` with a backing `<rect>` and a `<text data-role="name">`. Its complete text, including inline `<tspan>` descendants, must match the tag's `data-name`. The point sits inside the room it names at the plate top, or on the building's roof.
61
+ - The focal room or building carries `data-focal`.
62
+
63
+ The silhouette verifier accepts signed decimal and scientific-notation coordinates within the existing absolute M/L/A/Z path contract. Every operand must be finite; projected vertices, corner radii, and arc flags are still checked. This does not add relative path commands.
64
+
65
+ ## Anti-patterns
66
+
67
+ - Full-height walls that hide the rooms behind them.
68
+ - Boxes that overlap on the plate, or a box hanging past the plate edge.
69
+ - Painting by `x + y` alone, which draws long walls over the furniture in front of them.
70
+ - Tags tilted onto the floor plane, tags that overlap, or a numbered key under the figure.
71
+ - Accent on the focal room and on its furniture as well.
72
+ - Gradients, shadows, or glow on the plate or the boxes.
73
+
74
+ ## Examples
75
+
76
+ - `assets/example-axonometric-plan.html`: office floor, minimal light
77
+ - `assets/example-axonometric-plan-dark.html`: office floor, minimal dark
78
+ - `assets/example-axonometric-plan-full.html`: office floor, full editorial
79
+ - `assets/example-axonometric-plan-campus.html`, `-dark`, `-full`: campus site plan with roads, trees, and buildings tagged by phase
80
+ - `assets/example-axonometric-plan-coffee-shop.html`, `-dark`, `-full`: a coffee shop with an entrance and queue posts, an espresso bar, round tables, a kitchen, and a restroom
81
+ - `assets/example-axonometric-plan-warehouse.html`, `-dark`, `-full`: a fulfillment floor with dock doors, tall storage racks, a pick zone, packing stations, and shipping docks
82
+ - `assets/example-axonometric-plan-campus-animated.html`: the campus built phase by phase
83
+ - `assets/example-axonometric-plan-coffee-shop-animated.html`, `assets/example-axonometric-plan-warehouse-animated.html`: each floor revealed zone by zone in three phases