$ diagram-design render --type loop
SECTION LABEL
$ diagram-design render --type loop
", out: ""}` — explicit input/output semantic. Either side optional.
- **Array form:** `["", ""]` — first item is input, second is output.
- Codes from §8 (`WB`, `DB`, `TB`, `FL`, `LS`). Position is **fixed**: input chip on the node's bottom-**left**, output chip on the bottom-**right**.
- `nodes[i].color` — optional **per-node color override**. Any valid `"#hex"` string is accepted; the §4 palette is recommended for cross-diagram consistency but not required. Every node can carry its own color independently of others.
---
## 2. Layout formulas — deterministic geometry
```
label_col_w = 140
step_slot_w = 112
right_pad = 28
n_steps = len(steps)
n_lanes = len(lanes)
# Canvas
viewBox_w = label_col_w + n_steps * step_slot_w + right_pad # 5 steps → 728
header_h = 36
lane_h = 80
has_color_row = any(node.color or step.color or lane.color in inputs)
legend_h = 100 if has_color_row else 80 # 4 rows when colors are present
viewBox_h = header_h + n_lanes * lane_h + legend_h # 4 lanes, no colors → 436; with colors → 456
# Header strip (top)
header_y = 0 # ends at header_h = 36
step_chip_y = 6 # 16-px chip at y=6..22
step_label_y = 29 # text line below chip
# Lane positions
lane_y_top(k) = header_h + k * lane_h # 36, 116, 196, 276
lane_y_mid(k) = lane_y_top(k) + lane_h/2 # 76, 156, 236, 316
lane_label_x = label_col_w / 2 # 70
# Step / node center x
step_cx(j) = label_col_w + j * step_slot_w + step_slot_w/2 # 196, 308, 420, 532, 644
# Nodes
node_w = 100
node_h = 64
node_x(j) = step_cx(j) - node_w/2 # 146, 258, 370, 482, 594
node_y(k) = lane_y_top(k) + 8 # 44, 124, 204, 284
# Legend strip (bottom)
legend_y_top = header_h + n_lanes * lane_h # 356
legend_row_y = [legend_y_top + 16, legend_y_top + 37, legend_y_top + 59]
# 372, 393, 415
```
### 2.1 Background structure
- Paper fill across full viewBox.
- Dot pattern: 22×22 grid, `circle r=0.8`, `fill ink @ 0.10`.
- Alternating lane tints: odd-indexed lanes (0, 2, …) receive `ink @ 0.018` fill.
- Lane dividers: horizontal hairlines at every `lane_y_top(k)` and at `legend_y_top`, stroke `ink @ 0.12` width 0.8.
- Label column right border: vertical hairline at `x = label_col_w`, from `y = header_h` to `y = legend_y_top`.
### 2.2 Step header chip
Per step `j`:
```
chip_x(j) = step_cx(j) - 16 # 16×16 chip
chip_y = 6
chip_w = 32
chip_h = 16
chip_rx = 8 # pill-shaped
number_anchor = (step_cx(j), 14)
label_anchor = (step_cx(j), 29)
```
Default fill: `ink @ 0.12`, number text ink, label text muted.
Focal fill: `accent @ 0.20`, number + label text accent.
Per-step `color` override (§4): replaces the fill with `rgba(C, 0.20)` and the text fill with `C`.
### 2.3 Lane labels
Two-line `eyebrow` role label, both lines uppercase, fill muted:
- Line 1 at `(lane_label_x, lane_y_mid(k) - 4)`
- Line 2 at `(lane_label_x, lane_y_mid(k) + 8)`
Per-lane `color` override (§4): replaces the label fill with `C` and the lane tint with `rgba(C, 0.04)` (instead of the default `ink @ 0.018`).
### 2.4 Node content layout (inside the 100×64 rect)
```
role_chip rect 18×10 at (node_x+4, node_y+4), rx=3
role_chip_text centered at (node_x+13, node_y+9), eyebrow role, font-size=6, weight=600
title centered at (step_cx(j), node_y+23), node-name role, font-size=9
sub centered at (step_cx(j), node_y+35), sublabel role, font-size=6.5, muted
tool centered at (step_cx(j), node_y+47), sublabel role, font-size=6.5, soft
data chip IN rect 16×8 at (node_x+4, node_y+54), rx=3 # payload type entering the node
data chip OUT rect 16×8 at (node_x+80, node_y+54), rx=3 # payload type leaving the node
```
Empty cells (no node entry) render **nothing**. No placeholder rect, no role chip, no label — the cell is invisible.
---
## 3. Arrow rules (mandatory)
Four styles, bound to topology. Connectors are drawn **before** all node rects (z-order rule).
| `style` | Stroke | Width | Dash | Marker | When required |
|---|---|---|---|---|---|
| `muted` | `muted` | 1.0 | — | `arr-muted` | Standard data hand-off between steps or within a lane. |
| `trigger` | `muted` | 1.0 | `4,3` | `arr-muted` | Governance trigger — an admin action enables downstream work. Unlabelled. |
| `accent` | `accent` | 1.2 | — | `arr-accent` | Focal cross-role handoff. **Exactly one per diagram**, labeled. |
| `link` | `link` | 1.0 | — | `arr-link` | Published / externally-consumed output. |
**Defs block** (required, three markers):
```svg
```
### 3.1 Routing rules (non-negotiable)
- **Single-bend routing:** horizontal-first, then vertical. Exit a node from the **right edge**; enter from the **left** (same-lane horizontal) or **top/bottom** (cross-lane vertical).
- **No diagonals.** Bends use an 8-px Q-bezier corner.
- **Same-step cross-lane (vertical)**: line directly between `(step_cx(j), lane_y_top(k_to)−12)` and `(step_cx(j), lane_y_top(k_to))`. Used for admin → engineers triggers under the same step.
- **Cross-lane cross-step (focal)**: exit right, run horizontal past the source node's right edge to a corridor x just before the target's step, then drop vertically.
- **Labels:** only the `accent` arrow gets a label. Use a paper-filled rect mask (opaque) 6 px behind the text. Other arrows are unlabelled.
- **Z-order:** all arrows emitted before any node rect (the rect fills mask the line ends inside the node).
---
## 4. Component color override
Any node, lane, or step may declare an optional `color: "#hex"`. Mirrors high-level §3.4 and dp-integration §4 so the rule reads identically across types.
### 4.1 Per-node `color`
Applied to:
| Element | Light | Dark |
|---|---|---|
| Container fill (`rect`) | `rgba(C, 0.06)` | `rgba(C_light, 0.10)` |
| Container stroke | `rgba(C, 0.35)` (stroke-width 1) | `rgba(C_light, 0.45)` |
| Role chip fill | `rgba(C, 0.18)` | `rgba(C_light, 0.22)` |
| Role chip text | `C` | `C_light` |
| Title text | `C` | `C_light` |
| Sub-label | **unchanged** (muted) | **unchanged** (muted) |
| Tool label | **unchanged** (soft) | **unchanged** (soft) |
| Data-type chips | **unchanged** | **unchanged** |
| Arrows touching this node | **unchanged** — topology-driven | **unchanged** |
`C_light` = the same hex lightened ~15% for dark-mode contrast (e.g., `#b85450` → `#d97a78`).
### 4.2 Per-step `color`
Replaces the step header chip's fill with `rgba(C, 0.20)` and the chip's number + label text fill with `C`. The legend's matching step entry uses the same colors.
### 4.3 Per-lane `color`
Replaces the lane stripe tint with `rgba(C, 0.04)` (only for odd-indexed lanes that receive a tint by default — or extend to all lanes if explicitly chosen) and the lane label text fill with `C`. Use sparingly; lane tints are easy to over-apply.
### 4.4 Rules
- **Never on focal nodes / focal steps.** The accent already carries that signal. A `color` on a focal element is ignored.
- **Never on arrows.** Arrows are topology-driven. If you want a colored edge, pick a different `style` from §3, not a color override.
- **Cap at 3 custom-colored elements** per diagram (nodes + lanes + steps combined), in addition to the focal pair (focal node + focal step header). Above 3 the visual signal starts to fragment — if you need more, split the diagram or rethink whether each color carries distinct meaning.
- **Subtitles and tool labels stay muted.** Only the primary identity (border + role chip + title + icon) carries the color signal.
### 4.5 Semantic palette (recommended)
Same palette as high-level / dp-integration so a reader scanning multiple diagrams sees the same colors meaning the same thing:
- `#b85450` rust-red — Security / Identity / Governance (admin nodes, LDAP, access control)
- `#5a7d9a` slate-blue — Observability / Quality (monitoring, data-quality gates, lineage)
- `#7a8c47` olive-green — Governance / Lineage (catalog, metadata)
- `#8c6d3f` warm-brown — Backup / DR / Archive
---
## 5. Focal rule
The data-flow diagram is built around **one cross-role handoff** that defines its central claim. Three focal slots, exactly one entry each:
- **One focal step** (`steps[j].focal: true`) — typically the analytical pivot (Analyze, Model, …). Header chip and legend chip both render in accent.
- **One focal node** (`nodes[i].focal: true`) — the node that *receives* the focal handoff. Accent border + accent role chip + ink title.
- **One focal arrow** (`arrows[i].style: "accent"`) — the cross-role handoff into the focal node. Solid accent stroke + labeled with a short payload descriptor (e.g., `anon data`).
If zero or >1 of any focal slot are declared, halt and ask the user.
---
## 6. Dark mode
| Token | Light | Dark |
|---|---|---|
| Paper | `paper` | `ink` |
| Ink | `ink` | `paper` |
| Muted | `muted` | `soft` |
| Soft | `soft` | `rule-solid` |
| Accent | `accent` | `accent` |
| Link | `link` | `link` |
| Dot pattern | `ink @ 0.10` | `paper @ 0.10` |
| Lane tint | `ink @ 0.018` | `paper @ 0.025` |
| Dividers | `ink @ 0.12` | `paper @ 0.12` |
| Default chip fill | `ink @ 0.12` | `paper @ 0.12` |
| Focal chip fill | `accent @ 0.20` | `accent @ 0.22` |
| Default node fill | `paper` | `paper @ 0.04` |
| Default node stroke | `ink @ 0.25` | `paper @ 0.20` |
| Focal node fill | `accent @ 0.07` | `accent @ 0.12` |
| Focal node stroke | `accent` | `accent` |
| Custom component colors | `C` | `C_light` (lighten ~15%) |
---
## 7. Reproducibility checklist (taste gate)
Before emitting SVG, verify **every** item:
1. `viewBox = "0 0 {viewBox_w} {viewBox_h}"` derived from `n_steps` and `n_lanes` via §2.
2. Header strip at `y=0..36`; legend strip at `y=legend_y_top..viewBox_h` (`legend_y_top = 36 + n_lanes * 80`).
3. Every node at `(step_cx(j) - 50, lane_y_top(k) + 8)` size `100×64`.
4. Empty cells render nothing — no placeholder rect, no text.
5. Exactly **one** focal step (`steps[j].focal: true`).
6. Exactly **one** focal node (`nodes[i].focal: true`).
7. Exactly **one** focal arrow (`style: accent`). Labeled, with a paper-masked rect behind the label.
8. All other arrows unlabelled.
9. All arrows emitted before any node rect (z-order rule).
10. Single-bend routing only — no diagonals. Q-bezier `r=8` at each bend.
11. Custom component colors ≤ 3 (in addition to the focal pair). Arrows never recolored by component `color`.
12. Subtitle and tool labels stay muted regardless of any component `color`.
---
## 8. Data-type chips reference (input + output)
Small `16×8 rx=3` badges at the bottom of each node, one for input and one for output. Position is **non-negotiable**:
- **Input chip** at `(node_x+4, node_y+54)` — bottom-**left** of the node. Represents the payload format *entering* the node from upstream.
- **Output chip** at `(node_x+80, node_y+54)` — bottom-**right** of the node. Represents the payload format *leaving* the node toward downstream.
Either chip may be omitted (e.g., a sink node has only an input chip; a source-only node has only an output chip). Reading the diagram becomes a payload-transformation trace: scan a row, read each node's input → output, and you see exactly what shape the data takes at each hand-off.
### Chip codes
| Code | Color | Meaning |
|------|-------|---------|
| `WB` | `#6e6479` (mauve) | Web / Public data |
| `DB` | `#5e7a9b` (steel-blue) | Dataset / Raw file |
| `TB` | `#b8915a` (amber) | Table / Analysis-ready |
| `FL` | `#9c6b50` (sienna) | File / Report / Export |
| `LS` | `#4a7c59` (forest) | Live stream / Event |
Text inside chip: white, `eyebrow` role at 5px, weight 700.
Data-type chip colors are a **separate semantic axis** from the per-node color override (§4). The chip colors describe *payload format*; the node color override describes *concern type* (governance, observability, …). Don't conflate them — a node can have both an `out: TB` amber chip and a rust-red border color simultaneously.
---
## 9. Legend (3- or 4-row strip)
Each row introduced by a category label at `x=144`. The default legend has **3 rows** (`STEPS` / `DATA TYPE` / `FLOW`); when one or more nodes carry a `color` override (§4), add a 4th `CONCERN` row and grow `legend_h` to 100 (so `viewBox_h = header_h + n_lanes·80 + 100`).
- **Row 1 — `STEPS`** at `y = legend_y_top + 16`: repeat the header chips with their labels. Focal step keeps accent fill.
- **Row 2 — `DATA TYPE`** at `y = legend_y_top + 37`: one swatch per chip type actually used in the diagram. **Append a small sub-hint** in the muted `sublabel` role after the chips: `left chip = input · right chip = output`. This makes the position-based input/output convention explicit for first-time readers.
- **Row 3 — `CONCERN`** (only when color overrides are present) at `y = legend_y_top + 58`: one mini-rect per custom color used, with its semantic label (e.g., `Identity · Governance`, `Data Quality · Observability`). The focal accent swatch is also shown here so the reader sees all three colored axes side-by-side.
- **Row 4 — `FLOW`** (last row, position depends on whether `CONCERN` row exists): short line segments with their marker + text label, one per arrow style actually used.
All legend items align on a single horizontal strip per row. Do not stack vertically inside a box.
---
## 10. Complexity budget
| Dimension | Max |
|---|---|
| Lanes (roles) | 4 |
| Steps | 6 |
| Nodes per lane | Nodes = active steps only — empty cells are invisible (no placeholder box) |
| Labelled arrows | 1 (focal accent only) |
| Data-type chips per node | 2 |
| Custom-colored elements (§4) | 3 (in addition to focal node + focal step) |
Above 4 lanes or 6 steps: split into two diagrams (e.g., ingestion pipeline / analytics pipeline).
---
## 11. Anti-patterns
- **Placeholder empty cells** — if a role doesn't participate in a step, leave the cell empty (no box, no text).
- **More than one labelled arrow** — only the focal cross-role handoff gets a label.
- **Diagonal arrows** — always horizontal-first, then vertical; single right-angle bend.
- **`title` role for node titles** — node titles use the `node-name` role (technical context). Only the page `` uses `title`.
- **Accent on more than one node, one step, one arrow** — focal = one node + one step + one arrow, max.
- **`node-name` role for role labels** — lane labels always use the uppercase `eyebrow` role (they are identifiers, not prose).
- **`color` override on a focal element** — ignored. Accent always wins.
- **Custom-colored arrows** — arrows are topology-driven. Color on a node never spreads to its edges.
- **Lane tints over-applied** — a tint on every lane reads as decoration, not signal. Apply to ≤1 lane.
---
## 12. Examples
- `assets/example-data-flow.html` — minimal light (the platform, 4-role × 5-step: Admin, Engineers, Scientists, Consumers). Gallery default.
- `assets/example-data-flow-dark.html` — same, dark skin.
- `assets/example-data-flow-full.html` — same, editorial-card frame.
- `assets/example-data-flow-extended.html` — exercises §4 color override: Access Control node in rust-red (governance), Clean & Stage node in slate-blue (data quality). Focal accent on Analyze step + Explore & Model node + anon-data arrow unchanged.
- `assets/example-data-flow-extended-dark.html` — extended pattern, dark skin.
- `assets/example-data-flow-extended-full.html` — extended pattern, editorial-card frame.
## references/type-db-schema.md
# Database Schema
**Best for:** the *physical* schema — real tables, real SQL types, real constraints, real indexes, and foreign keys that connect one column to another column. It's the DDL made legible: migrations, review of a real database, and anything where the column type or the `ON DELETE` behavior is the point.
**Not for domain modeling.** [ER / data model](type-er.md) is entity-level: relationship lines join *boxes* and carry cardinality, fields are a plain list, and it's the right tool for a conceptual or domain conversation. Database schema is column-level: the FK connector anchors to the specific column row on both ends — the one capability ER doesn't have, and the reason this type exists. If you're discussing what an Order *is*, use ER. If you're discussing what happens when a row is deleted, use this.
## Layout conventions
### Table box
- **Header band** — `schema.table` (e.g. `public.orders`) in Geist sans 12px weight 600, with a rectangular type tag (`rx=2`, NOT a pill) reading `TABLE`. A hairline separates it from the body.
- **Column rows** — fixed 24px row height so connectors can anchor predictably. Each row: column name in Geist sans 12px anchored left, SQL type in Geist Mono 9px `muted` anchored right (`uuid`, `text`, `numeric(12,2)`, `timestamptz`), and constraint chips between them as small `rx=2` tags in Geist Mono 8px: `PK`, `FK`, `UQ`, `NN`. Alternate row background `ink @ 0.02` on even rows for scannability.
- **Overflow row** — when a table has more columns than the budget allows, the last row is a Geist Mono 9px `muted` line: `+ N more columns`. Never silently truncate a table without saying so.
- **Index compartment** — an optional final compartment separated by a hairline, labelled with a Geist Mono 8px uppercase `INDEXES` eyebrow, listing index names in Geist Mono 9px (`idx_orders_customer_id`, `uq_products_sku`). List only the indexes that matter to the story, not every index on the table.
### Foreign-key connectors — the defining rule
Each FK edge starts at the **vertical centre of its source column row** and ends at the **vertical centre of the referenced column row**, routed with orthogonal rounded elbows (see SKILL.md §6 and [type-architecture.md](type-architecture.md) for the elbow formula and bridge/hop primitive). Label each edge in Geist Mono 8px with its referential action — `ON DELETE CASCADE`, `ON DELETE RESTRICT`, `ON DELETE SET NULL` — masked with the standard 6–10px gap. Fixed 24px row height guarantees ≥12px separation only when two FKs attach to *different* rows on the same table edge — the row spacing itself is the fan. When two or more FKs attach to the *same* row on the same edge (e.g. two child tables both referencing the same parent's primary key), anchoring all of them at the exact row centre would collide at a single point, which SKILL.md §6 rule 4 forbids. Offset each attach point symmetrically around the row's vertical centre instead — ±8px for two edges, keeping every point inside the row's 24px band and ≥12px from its neighbor — so each connector still reads as attaching to that row while remaining independently traceable.
### Schema grouping
Tables in a non-default schema sit inside a containment rect (`rx=8`, `ink @ 0.02` fill, `ink @ 0.20` stroke dashed `4,4`) with a Geist Mono 8px uppercase tracked schema label in its top-left corner. Draw the group rect first so tables paint over it.
### Focal rule
The 2 accent elements are: (1) the one destructive FK (`ON DELETE CASCADE`) — the edge and its label count together, since a labelled edge is one thing; and (2) the table that FK cascades into, carrying `accent-tint` on its **header band only**, never on the whole box. Nothing else on the diagram is `accent`.
If a schema has no destructive FK, it has no focal element. Leave it unaccented rather than promoting an arbitrary table.
## Complexity budget
Max 5 tables, max 8 column rows shown per table, max 6 FK edges, max 2 accent elements. Over budget → show the subsystem, not the database, and say so in a caption.
## Anti-patterns
- Drawing every column of every table — a schema diagram is an argument about a subsystem, not a `\d+` dump.
- FK lines that connect box to box instead of column to column — that's ER, use ER instead.
- Missing SQL types — the type is half the content.
- Unlabelled FK edges — the `ON DELETE` behavior is what a reviewer is looking for.
- Constraint chips on every row until the chips are the noise.
- Index compartments listing every index rather than the ones that matter to the story.
- Mixing conceptual entity names with physical table names in one diagram.
## Examples
- `assets/example-db-schema.html` — minimal light
- `assets/example-db-schema-dark.html` — minimal dark
- `assets/example-db-schema-full.html` — full editorial
## references/type-dependency.md
# Dependency Graph
**Best for:** what depends on what, across packages, modules, or services — specifically to show two things a **tree** cannot structurally express: (a) a node with **more than one parent** (a shared dependency that several things converge on), and (b) a **cycle**. If neither appears in the data — every node has exactly one parent and nothing points backward — use [Tree](type-tree.md) instead; say so explicitly rather than forcing a graph layout on tree-shaped data.
## Layout conventions
- **Ranked layers.** Nodes sit in horizontal rank rows by dependency depth: rank 0 (entry points nothing depends on) at the top, deeper ranks below. Forward edges point downward across ranks, or run horizontal within a single rank row when a dependency compresses to the same depth as its dependent (e.g. a shallow sibling dependency) — never upward outside the one marked cycle. Rank rows are 120px apart.
- Nodes are the standard node-box pattern (§6): `rx=6`, 160px wide, 56px tall.
- **Fan-in badge.** Every node carries a Geist Mono 8px badge in its top-right corner, inside a small `rx=2` box, showing how many nodes depend on it (`4 in`). A mask fully inside a node is a badge chip, not a label — legitimate under §6 rule 6. The node with the highest fan-in is the diagram's structural story; size nothing else to compete with it.
- **Node treatments** (§5 Node type → treatment):
- Internal package/service → white fill + `ink` stroke.
- External / third-party → `ink @ 0.03` fill + `ink @ 0.30` stroke (the External/Cloud treatment).
- Leaf with no outgoing edges → `ink @ 0.05` fill + `muted` stroke.
- **The cycle.** At most one back-edge points upward against rank order. It is the editorial point of the diagram: `accent` stroke, dashed `5,4`, `marker-end="url(#arrow-accent)"`, routed **around the outside** of the node stack — never straight through the middle, and never behind a node it doesn't connect to — with a masked Geist Mono 8px `CYCLE` label at its visible end. The two nodes the cycle touches stay in their normal node treatment (§5) — no accent stroke or fill on the nodes themselves, or the 2-accent budget is blown on the wrong elements.
- **Focal rule:** the 2 accent elements permitted per diagram are the back-edge and its `CYCLE` label. Nothing else in a dependency graph is accent.
- All six §6 Mandatory connector rules apply in full, no exemptions: rounded right-angle elbows (`r=8`) between off-axis nodes, 6–10px label-margin, no overlapping connectors (bridge/hop at crossings), fanned attach points (≥12px apart) where multiple edges share a box edge, no connector passing behind a non-endpoint box, no label mask clipped by a later-painted node.
## Complexity budget
| Limit | Rule |
|---|---|
| Max nodes | 9 |
| Max edges | 14 |
| Max rank layers | 4 |
| Max highlighted cycles | 1 |
| Max accent elements | 2 |
Over budget: collapse a leaf cluster into one aggregate node labelled with its count (e.g. `+6 leaves`), and say so in a caption — don't silently drop nodes.
## Anti-patterns
- Drawing a dependency graph when the data is actually a tree (single parent everywhere, no cycles) — use Tree instead.
- Forward edges that point upward without being the one marked cycle.
- A hairball layout with no rank ordering — rank first, always; ranking is what makes the graph readable, not an optional polish pass.
- One node per file instead of per package/module/service — the graph is about dependency structure, not the filesystem.
- Unlabelled external dependencies — version or registry belongs in the Geist Mono sublabel (`v3.23 · npm`), not left implicit.
- 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.
- 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.
## Examples
- `assets/example-dependency.html` — minimal light
- `assets/example-dependency-dark.html` — minimal dark
- `assets/example-dependency-full.html` — full editorial
## references/type-deployment.md
# Deployment
**Best for:** where the software actually *runs* — hosts, VMs, pods, and managed services placed inside environment or network-boundary zones, with replica counts and versioned artifacts called out. Architecture answers "what talks to what"; deployment answers "what is installed on which host, in which environment, behind which network boundary, at how many replicas." If the diagram has no physical-placement decision to show — no zone boundary, no replica count, no version that matters — use `type-architecture.md` instead; redrawing the logical architecture with hostnames bolted on is the most common deployment anti-pattern.
## Layout conventions
Three nesting levels, outermost to innermost — reuses the containment grammar from `type-nested.md`, specialized for infrastructure:
1. **Zone** — an environment or network boundary (`edge`, `prod / eu-west-1`, `data`). A large rect, `rx=8`, fill `ink @ 0.02`, stroke `ink @ 0.20` dashed `4,4`. A Geist Mono 8px (or 7px for tight layouts) uppercase tracked eyebrow label sits inside the top-left corner, on a paper-colored mask over the border. Zones are drawn **first** — before arrows and nodes — so labels and boxes paint over them (z-order: bg → zones → arrows → labels → nodes).
2. **Infrastructure node** — a host, VM, pod, or managed service inside a zone. The §6 node-box pattern (SKILL.md) at `rx=6`, with a rectangular type tag (`rx=2`, **not** a pill) carrying `POD` / `VM` / `MANAGED` / `CDN` in the top-left corner.
3. **Artifact chip** — what is deployed onto that node. A small 24px-tall rect `rx=4`, fill `ink @ 0.05`, stroke `muted`, holding the image or service name in Geist sans 12px (left-aligned) plus a Geist Mono 9px version tag (right-aligned, e.g. `v2.4.1`). A node can carry more than one chip (stacked with an 8px gap) when more than one artifact is co-located (a sidecar, for example).
**Replica badge.** A node running N copies carries a right-aligned Geist Mono 8px badge (`x3`) inside its own small `rx=2` box in the node's top-right corner. A mask fully inside a node is a badge chip and is a legitimate exception to the "mask must not overlap a later node" rule (SKILL.md §6 rule 6) — it's part of that same node.
**Network paths.** Orthogonal elbows between nodes (SKILL.md §6, elbow formula and port-selection rules in `type-architecture.md`), labelled with protocol and port in Geist Mono 8px (`HTTPS:443`, `TLS:5432`). A path that crosses a zone boundary is `link`-blue; a path that stays inside one zone is `muted`. Async or replication paths are dashed `5,4`.
**Focal rule.** The 2 accent elements are the single-point-of-failure or the newly-introduced piece — never more than 2. In the canonical example: the RDS primary (accent-tint fill, accent stroke) and the replication path to its standby (accent, dashed).
## Complexity budget
| Limit | Rule |
|---|---|
| Max zones | 3 |
| Max infrastructure nodes | 6 |
| Max artifact chips | 9 |
| Max network paths | 8 |
| Max accent elements | 2 |
Over budget → split into one deployment diagram per environment.
## Anti-patterns
- Redrawing the logical architecture with hostnames bolted on. If no placement decision is visible (which host, which zone, how many replicas), use `type-architecture.md` instead.
- Zones that are just visual grouping with no boundary meaning — a zone must be a real environment or network boundary, not a layout convenience.
- Artifact chips without a version tag. The version is why the diagram exists; an unversioned chip is a wasted box.
- One node drawn per replica instead of a single node with a replica badge.
- Cloud-vendor icon soup standing in for named nodes — name the host or service, don't decorate it.
- Unlabelled network paths. Protocol and port are the content of a deployment diagram, not decoration.
- Mixing two environments in one diagram (e.g. staging and production nodes side by side without a zone boundary that actually separates them).
## Examples
- `assets/example-deployment.html` — minimal light
- `assets/example-deployment-dark.html` — minimal dark
- `assets/example-deployment-full.html` — full editorial
## references/type-dp-integration.md
# DP integration
**Best for:** the integration topology of a data platform — which source systems plug in, which consumer surfaces plug out, and which protocol each one speaks. Hub-and-spoke layout wrapped in an explicit **Data platform** layer; no time/phase axis.
Use when the question is *"what surfaces does this platform expose, and over what wire?"* rather than *"how does data move through phases?"*.
This type is **parametric** — like `type-high-level.md`, every coord is derived from a small inputs schema. Two generations from the same inputs must produce visually identical SVG.
---
## 1. Inputs — the parameter contract
```yaml
sources: # left column, 0..6 nodes
- { name: "Databases", type: "db", subtitle: "SQL · MariaDB",
connects_to: [{to: "NiFi", label: "JDBC"},
{to: "Trino", label: "FEDERATE", style: "federated"}] }
- { name: "SFTP drops", type: "sftp", subtitle: "scheduled pulls",
connects_to: [{to: "NiFi", label: "SFTP"}] }
- { name: "Email", type: "mail", subtitle: "IMAP attachments",
connects_to: [{to: "NiFi", label: "IMAP"}] }
- { name: "IBM legacy", type: "mainframe", subtitle: "file export",
connects_to: [{to: "NiFi", label: "FILE"}] }
platform:
name: "DATA PLATFORM" # zone label (paper-masked top border)
rows: # ordered top→bottom; each is bar or row
- { kind: bar, name: "Trino", icon: trino, subtitle: "federated query · push-down",
role: "SQL", focal: true }
- { kind: row, nodes: [
{ name: "Apache NiFi", icon: nifi, role: "INGEST", subtitle: "flow-based ETL" },
{ name: "MinIO", icon: minio, role: "STORE", subtitle: "S3 object store · medallion", focal: true },
{ name: "JupyterLab", icon: jupyter, role: "NOTEBOOK", subtitle: "Python · R · pandas" }
]}
- { kind: bar, name: "Apache Airflow", icon: airflow,
subtitle: "scheduler · DAG triggers · backfill", role: "DAG" }
consumers: # right column, 0..6 nodes
- { name: "Desktop apps", type: "monitor", subtitle: "SPSS · SAS · Stata",
connects_from: [{from: "Trino", label: "ODBC"}] }
- { name: "BI & reports", type: "chart", subtitle: "Tableau · Power BI",
connects_from: [{from: "Trino", label: "JDBC"}] }
- { name: "Public website", type: "globe", subtitle: "NatStat portal",
connects_from: [{from: "Trino", label: "HTTPS"}] }
- { name: "API gateway", type: "api", subtitle: "3rd-party / OAuth2",
connects_from: [{from: "Trino", label: "REST"}] }
footer: # 0..N cross-cutting bars stacked below zone (full-canvas width)
- { name: "Active Directory", icon: key, subtitle: "LDAP · SSO · group RBAC",
color: "#b85450" } # tinted red to flag the security concern
# additional footer nodes (Observability, Backup, …) stack below this one
internal_connections: # explicit platform-component edges
- { from: "NiFi", to: "MinIO", style: "primary", label: "WRITE" }
- { from: "MinIO", to: "JupyterLab", style: "secondary", label: "READ" }
- { from: "MinIO", to: "Trino", style: "secondary" }
- { from: "JupyterLab", to: "Trino", style: "secondary", dashed: true }
- { from: "Airflow", to: ["Apache NiFi", "MinIO", "JupyterLab"], style: "trigger" }
focal_accent: "#eb6c36" # one color for all focal components (default = SKILL accent)
dark: false
```
**Reserved `kind` values for `platform.rows`:**
- `bar` — full-zone-width strip. Default height 44 px (focal bars get 56 px). Required fields: `name`, `icon`. Optional: `subtitle`, `role`, `color`, `focal`.
- `row` — N nodes evenly spaced across zone width. Required: `nodes` list. Each node has `name`, `icon`, optional `role`, `subtitle`, `color`, `focal`.
**Source/consumer `type` values** → icon mapping (extends `references/primitive-icons.md`):
- `db` → cylinder, `sftp` → folder-with-arrow, `mail` → envelope, `mainframe` → server-with-vents
- `monitor` → desktop screen, `chart` → bar-chart, `globe` → globe, `api` → curly braces
- `key` → key + ring (identity / IDP)
- Any explicit icon name in `primitive-icons.md` is also accepted.
**Per-component `color: "#hex"`** is optional on any node, bar, or footer entry. See §4.
---
## 2. Layout formulas — deterministic geometry
```
# Canvas
viewBox_w = 1200
n_sources = len(sources)
n_consumers = len(consumers)
n_footer = len(footer)
# Side columns (sources left, consumers right)
col_top = 92
col_node_h = 64
col_gap = 24 # stride = col_node_h + col_gap = 88
col_h_min = 336 # default fits 4 sources (4 * 88 - 24)
col_h = max(col_h_min, max(n_sources, n_consumers) * 88 - 24)
left_x = 40
left_w = 160
right_x = 1000
right_w = 160
col_node_y(k) = col_top + k * 88
col_node_cy(k) = col_node_y(k) + col_node_h/2 # 124, 212, 300, 388 by default
# Platform zone
zone_x = 260
zone_w = 696
zone_y = 72
zone_h = col_h # zone always matches column height
zone_cx = zone_x + zone_w/2 # 608
zone_pad_x = 16 # inside left/right padding for bars
zone_label_y = zone_y + 3 # paper-masked label across top border
# Footer bars (below zone — each cross-cutting concern is a full-width bar)
footer_top = zone_y + zone_h + 52 # 52-px gap below zone
footer_bar_h = 56
footer_bar_x = 40 # aligned with source column left edge
footer_bar_w = viewBox_w - 80 # = 1120 — spans from source col left to consumer col right
footer_gap = 8
footer_y(k) = footer_top + k * (footer_bar_h + footer_gap)
footer_bottom = footer_top + n_footer * (footer_bar_h + footer_gap) - footer_gap
viewBox_h = max(600, footer_bottom + 84) # 84 reserved for legend
# Platform.rows allocation inside zone
bar_h_focal = 56
bar_h_default = 44
row_h = 72
row_gap = 16
```
### 2.1 Row placement (cursor algorithm)
Allocate each `platform.rows` entry top-to-bottom. The single `row` (or first row when N>1) anchors to side-column row 2 so its connectors stay horizontal:
```
primary_row_idx = index of first kind=row in platform.rows
primary_row_top = col_node_y(1) - (row_h - col_node_h)/2 # 176 by default
# 4-px nudge so cy aligns with side row 2
# Place rows above primary
y = primary_row_top
for entry in platform.rows[:primary_row_idx] reversed:
y -= row_gap
entry.h = bar_h_focal if (entry.kind == bar and entry.focal) else bar_h_default
y -= entry.h
entry.y_top = y # Trino bar lands at y=104
# Place primary row
platform.rows[primary_row_idx].y_top = primary_row_top # NiFi/MinIO/Jupyter at y=176
platform.rows[primary_row_idx].h = row_h
# Place rows below primary
y = primary_row_top + row_h
for entry in platform.rows[primary_row_idx+1:]:
y += row_gap
entry.y_top = y
entry.h = bar_h_focal if (entry.kind == bar and entry.focal) else bar_h_default
y += entry.h
# Constraint: y <= zone_y + zone_h
```
This produces the canonical layout for the standard shape (top bar / 3-node row / bottom bar): Trino at `y=104 h=56`, primary row at `y=176 h=72`, Airflow at `y=324 h=44`. Bottom anchor of Airflow at y=368 (40-px clear from zone bottom at y=408). **Note**: with the canonical layout there's a 76-px gap between the primary row's bottom (y=248) and Airflow's top (y=324). That gap is intentional — Airflow visually sits at the same y-band as source/consumer row 4 (cy=388), so it reads as a sibling of the bottom side-column row.
### 2.2 Node placement inside a `row` entry
```
N = len(row.nodes)
node_w = (zone_w - 2*zone_pad_x - (N-1) * 16) / N
node_x(j) = zone_x + zone_pad_x + j * (node_w + 16)
node_cx(j) = node_x(j) + node_w/2
```
For the canonical 3-node row: `node_w = (696 - 32 - 32) / 3 = 210.67`. The shipped example uses fixed `node_w=160` with custom x positions (`288, 480, 672`) chosen so each node's `cx` aligns to the column for connector convenience: 368, 560, 752. **Both layouts are valid**; the formula above is the default for new diagrams. Document any deviation in the rendered SVG with a comment.
### 2.3 Bar (full-zone-width) placement
```
bar_x = zone_x + zone_pad_x # 276
bar_w = zone_w - 2*zone_pad_x # 664
bar_cx = zone_cx # 608
```
Bars span the full zone width minus 16-px padding on each side. Bars marked `focal: true` use `bar_h_focal=56` and accent styling (fill `rgba(focal_accent, 0.08)`, stroke `focal_accent`). Non-focal bars use `bar_h_default=44` with muted styling (fill `rgba(45,49,66,0.05)`, stroke `rgba(45,49,66,0.32)`).
### 2.4 Source / consumer placement (side columns)
```
source_y(k) = col_top + k * 88 # 92, 180, 268, 356, …
source_cy(k) = source_y(k) + col_node_h/2 # 124, 212, 300, 388, …
consumer_y(k) = source_y(k) # mirrored
consumer_cy(k) = source_cy(k)
```
All side-column nodes use fixed `w=160 h=64`. Same fill / stroke pattern: fill `rgba(79,93,117,0.06)`, stroke `#7a8399`, stroke-width 1.
---
## 3. Connector rules (mandatory)
Five styles, bound to topology. Don't let user override style on focal-touching, bar-originating, or Trino → consumer edges — those are fixed by rule.
| `style` | Stroke | Width | Dash | Marker | When required |
|---|---|---|---|---|---|
| `primary` | `#eb6c36` (focal_accent) | 1.4 | — | `arrow-accent` | Every edge whose endpoint is a `focal: true` component. Also every Trino → consumer edge (serve-flow rule). |
| `secondary` | `#4f5d75` (muted) | 1.2 | — | `arrow` | Default for internal platform-component edges and source → platform edges that don't touch focal. |
| `federated` | `#2e5aa8` (link-blue) | 1.0 | `4,3` | `arrow-link` | Federation queries (e.g., source DB → Trino). |
| `trigger` | `#4f5d75` (muted) | 1.0 | `4,3` | `arrow` | Every edge originating from a `kind: bar` component (Airflow drops). Unlabelled. |
| `auth` | `#eb6c36` | 1.2 | `5,4` | `arrow-accent` | Every edge from a footer node up to the zone bottom edge. **Never to a specific component.** |
**Defs block** (required, five markers — exactly):
```svg
```
### 3.1 Exit / entry sides (non-negotiable)
| Edge kind | Exit side of source | Entry side of target |
|---|---|---|
| Source → platform component | **right** of source | **left** of target |
| Platform → platform (same row) | **right** | **left** |
| Bar → row node (vertical drop) | **bottom** of bar at `node_cx(target)` | **top** of target |
| Platform → consumer | **right** of source platform component | **left** of consumer |
| Footer → zone | **top** of footer (at `footer_auth_x(k)`) | zone bottom edge `y = zone_y + zone_h` |
| Footer → component (any specific one) | **forbidden** |
### 3.2 Routing
- Orthogonal elbows with at most two bends; Q-bezier `r=8` at every corner.
- **Fan-out staggering:** when one node fans out to N targets on the same side, stagger the exit y by ±4 px per index so arrows don't overlap (e.g., Trino → 4 consumers exits at y=124, 132, 140, 148). The vertical segments run in the corridor between the zone edge and the consumer column, also y-staggered.
- **Z-order:** all connectors drawn **before** any rect (so node fills mask the line ends).
- **Markers:** exactly one `marker-end` per `` / ``. Never `marker-start`.
- **Labels:** every `primary`, `secondary`, `federated`, `auth` edge gets a protocol label (Geist Mono 8 px, paper-filled rect mask with 6–10 px clear gap above the stroke). `trigger` edges are unlabelled.
### 3.3 Footer → zone trunk
When N=1 footer: single vertical line at `x = zone_cx` from `footer_y(0)` to `zone_y + zone_h`.
When N≥2 footers: stagger AUTH lines so they don't overlap stacked footers. For footer index `k`:
```
footer_auth_x(k) = zone_cx + (k - (N-1)/2) * 32 # 32-px stride per footer
```
Examples:
- N=1 → 560
- N=2 → 544, 576
- N=3 → 528, 560, 592
Each AUTH line goes from `(footer_auth_x(k), footer_y(k))` up to `(footer_auth_x(k), zone_y + zone_h)`. AUTH labels sit just above the arrowhead at the zone bottom edge.
### 3.4 Crossings
Avoid. Re-route via the corridor x positions before accepting a crossing. If unavoidable, the path drawn second carries a 6-px arc hop over the first.
---
## 4. Component color override (mirrors `type-high-level.md` §3.4)
Any source, consumer, platform component (node or bar), or footer node accepts an optional `color: "#hex"`. Mirrors high-level so the rule reads identically across types.
**Where the color is applied** (`C = color`):
| Element | Light | Dark |
|---|---|---|
| Container fill (`rect` body) | `rgba(C, 0.06)` | `rgba(C_light, 0.10)` |
| Container stroke | `rgba(C, 0.35)` (`stroke-width=1` for nodes, `0.8` for bars) | `rgba(C_light, 0.45)` |
| Role badge stroke | `rgba(C, 0.40)` | `rgba(C_light, 0.55)` |
| Role badge text | `rgba(C, 0.85)` | `rgba(C_light, 1.0)` |
| Icon stroke / fill | `C` | `C_light` |
| Name text | `C` | `C_light` |
| Subtitle text | **unchanged** (muted) | **unchanged** (muted) |
| Connectors touching this component | **unchanged** — topology-driven | **unchanged** |
`C_light` = the same hex lightened ~15% for dark-mode contrast (e.g., `#b85450` → `#d97a78`).
**Rules:**
- **Never on focal components.** `focal_accent` always wins — a `color` on a focal component is ignored.
- **Never on connectors.** If you want a colored edge, pick a different `style` from §3, not a color override.
- **Cap at 2 custom-colored components** per diagram (in addition to the focal pair).
**Semantic palette** (use these unless brand demands otherwise):
- `#b85450` rust-red — Security / Identity (AD, Keycloak, Vault)
- `#5a7d9a` slate-blue — Observability (Prometheus, Datadog, OpenTelemetry)
- `#7a8c47` olive-green — Governance / Lineage (OpenMetadata, DataHub)
- `#8c6d3f` warm-brown — Backup / DR (Velero, Restic)
---
## 5. Focal rule
**Exactly two focal components.** Default: the storage hub (MinIO / S3 / similar) and the federation engine (Trino / Dremio / similar). These two surfaces distinguish a "platform" from a pile of tools. Everything else (NiFi, Jupyter, Airflow, AD, all sources, all consumers) stays ink / muted.
- Mark with `focal: true` on the component entry.
- A focal `kind: bar` uses `bar_h_focal=56` (taller) and accent styling.
- A focal `kind: row` node keeps `row_h=72` but uses accent styling.
- The **Trino → all consumers** edges are always `primary` (accent), regardless of focal flag on each consumer — this is the serve-flow rule.
- If fewer than 2 or more than 2 components are marked `focal: true`, halt and ask the user.
---
## 6. Dark mode
| Token | Light | Dark |
|---|---|---|
| Page paper | `#f5f5f5` | `#2d3142` |
| Ink | `#2d3142` | `#f5f5f5` |
| Muted | `#4f5d75` | `#bfc0c0` |
| Accent | `#eb6c36` | `#f08a59` |
| Link (federated) | `#2e5aa8` | `#6a95d8` |
| Side-column fill | `rgba(79,93,117,0.06)` | `rgba(245,245,245,0.06)` |
| Side-column stroke | `#7a8399` | `rgba(245,245,245,0.30)` |
| Zone fill | `rgba(45,49,66,0.025)` | `rgba(245,245,245,0.04)` |
| Zone stroke | `rgba(45,49,66,0.32)` | `rgba(245,245,245,0.30)` |
| Non-focal bar fill | `rgba(45,49,66,0.05)` | `rgba(245,245,245,0.06)` |
| Focal fill | `rgba(235,108,54,0.08)` | `rgba(240,138,89,0.12)` |
| Focal stroke | `#eb6c36` | `#f08a59` |
| Custom component colors | `C` | `C_light` (lighten ~15%) |
---
## 7. Reproducibility checklist (taste gate)
Before emitting SVG, verify **every** item:
1. `viewBox = "0 0 1200 {viewBox_h}"` where `viewBox_h = max(600, footer_bottom + 84)`.
2. Platform zone at `x=260 y=72 w=696 h=col_h`. Zone label paper-masked across top border at `y=zone_y+3`.
3. Left column at `x=40..200`, right column at `x=1000..1160` — both 160 wide.
4. Source / consumer rows top at `y=92`, stride 88 px.
5. `platform.rows` entries stack inside zone via the §2.1 cursor algorithm; total y-span ≤ `zone_h`.
6. Inside each `kind: row`, node x-centers are evenly spaced across zone width (§2.2).
7. **Exactly 2** focal components (`focal: true`).
8. Every edge originating from a `kind: bar` component uses `style: trigger` (dashed, unlabelled).
9. Every Trino → consumer edge uses `style: primary` (the serve-flow rule).
10. Footer nodes connect only to the zone bottom edge via `auth` style. **No** edge from a footer to a specific component.
11. Custom component colors ≤ 2 (in addition to the focal pair). Connectors never recolored by component `color`.
12. All connectors emitted before any node rect (z-order rule).
---
## 8. Sources and consumers — icon library
Define each icon as `` in ``, drawn at translate(cx, cy) with `stroke="currentColor"` so it inherits the surrounding text color. Common icons:
- `ico-db` (cylinder) — relational sources
- `ico-sftp` (folder with down arrow) — file drops
- `ico-mail` (envelope) — email pulls
- `ico-mainframe` (server with vents) — legacy systems
- `ico-monitor` — desktop analytics tools
- `ico-chart` (bars) — BI / report tools
- `ico-globe` — public websites
- `ico-api` (brackets `{}`) — gateways and 3rd-party clients
- `ico-key` — identity / IDP
- `ico-monitoring` (chart-line) — observability stack
If you need more icons, browse `assets/icons.html` and define matching `` blocks.
---
## 9. Identity, common services → connect to the layer, not to components
**Active Directory** (or Keycloak, IAM, OPA, any cross-cutting identity / policy / secrets store) authenticates *every* component in the platform. Wiring it to one specific tool would understate the trust scope. Connect it instead with a single arrow to the bottom edge of the platform zone, labeled `AUTH` (§3.3).
The same rule applies to any other layer-wide service: centralized logging, secrets vault, observability stack, audit sink, mTLS root. Each goes in the `footer` list, each gets its own row, each gets its own AUTH line up to the zone bottom edge (staggered by index per §3.3). The visual reading is "the platform layer delegates to all of these," which is the architectural truth.
---
## 10. Budget — this type exceeds the default
This is the one type where the default 9-node / 12-arrow budget is intentionally exceeded. A realistic platform integration shows:
- 4–6 source nodes
- 5 platform components
- 4–6 consumer nodes
- 1–3 footer nodes (identity, observability, backup, …)
That's **14–20 nodes**. The complexity is the point — the diagram is making a claim about the *number of distinct integration surfaces*. Compressing them collapses the claim.
When this gets unwieldy:
- Combine clearly-identical source rows (e.g., four MariaDB databases → one `Databases` node with sublabel `4 × MariaDB`)
- Split into two diagrams (one per integration plane: data vs. identity vs. observability)
---
## 11. Anti-patterns
- **Sources or consumers as a single collapsed node** when ≥3 distinct items exist — defeats the whole point of this type. Use Architecture or High-level if you want collapsing.
- **One bus arrow from "sources" to "the platform"** — every wire is labeled with its protocol; this is how integration teams read the diagram.
- **Per-tool color coding** (teal-NiFi, magenta-MinIO, yellow-Jupyter) inside the zone — collapses hierarchy; only the two focal accents earn coral, plus up to 2 custom colors on cross-cutting components (§4 cap).
- **More than 2 focal components** — focal exists to distinguish "platform" from "pile of tools"; >2 erases the signal (same rule as SKILL.md §1).
- **`color` override on a focal component** — ignored. Focal_accent always wins.
- **Footer wired to one specific tool** (e.g., AD → Airflow only) — wrong unless that service truly only protects one tool. The default is the layer-wide connection.
- **Footer or identity inside the zone** — identity gates the layer from outside. Drawing it inside misrepresents the trust model.
- **Phase chevrons across the top** — those belong on `high-level`.
- **Custom-colored connectors** — connectors are topology-driven. Style picks the color; `color` on a component never spreads to its edges.
---
## 12. Examples
- `assets/example-dp-integration.html` — minimal light (1 footer = AD). Gallery default.
- `assets/example-dp-integration-dark.html` — same, dark skin.
- `assets/example-dp-integration-full.html` — same, editorial-card frame.
- `assets/example-dp-integration-extended.html` — exercises §4 color override + multi-footer: AD in rust-red, Observability (Prometheus/Grafana/Loki) in slate-blue. Canvas height grown to fit 2 footer rows.
- `assets/example-dp-integration-extended-dark.html` — extended pattern, dark skin.
- `assets/example-dp-integration-extended-full.html` — extended pattern, editorial-card frame.
## references/type-dp-security-matrix.md
# DP security matrix
**Best for:** documenting per-role / per-component access permissions for a data platform — a grid where each row is a platform component (Keycloak, MinIO bucket, Trino catalog, JupyterHub, NiFi, …) and each column is a role / AD group (Data Administrators, Data Engineers, Data Scientists, Data Consumers, …). Each intersection cell holds a permission value (Admin / Full / R/W / Read / SELECT / Login / No access) with a visual category that matches the permission level. One cell may be marked focal to flag a critical access rule (e.g., "Data Consumers can ONLY `SELECT` from the aggregated catalog — sole consumer access").
Use when stakeholders need to audit *who can do what* across the platform. Prefer **DP integration** when the question is *who can talk to what* (topology/protocol) rather than *who can write/read what* (permissions).
This type is **parametric** — the inputs schema in §1 drives every coordinate via the formulas in §2. The rule shape mirrors `type-medallion.md` / `type-process.md` / `type-data-flow.md` so the focal rule, color override, dark mode, and reproducibility checklist read identically across types.
---
## 1. Inputs — the parameter contract
```yaml
title: "Platform Access Matrix"
subtitle: "Four canonical groups × platform components"
roles: # 2..6 columns, ordered left → right
- { name: "Data Administrators", code: "DL-DataAdmins" }
- { name: "Data Engineers", code: "DL-DataEngineers" }
- { name: "Data Scientists", code: "DL-DataScientists" }
- { name: "Data Consumers", code: "DL-DataConsumers" }
components: # 2..14 rows, ordered top → bottom
- { name: "Keycloak", hint: "SSO" } # `hint` = right-aligned aside in label cell
- { name: "MinIO · raw bucket" }
- { name: "MinIO · anon · staging · agg" }
- { name: "Trino · raw catalog" }
- { name: "Trino · anon-staging" }
- { name: "Trino · aggregated" }
- { name: "JupyterHub" }
- { name: "NiFi" }
cells: # explicit (row, col) entries; omitted → defaults to "none"
# value = displayed text (free-form)
# level = visual category: full | rw | read | none (closed vocabulary, drives styling)
# focal: true (max 1) — overrides level to focal styling
# sub: "second-line text" — used inside focal cell
# color: "#hex" — optional per-cell color override (§4)
- { row: 0, col: 0, value: "Admin", level: "full" }
- { row: 0, col: 1, value: "Login", level: "read" }
- { row: 0, col: 2, value: "Login", level: "read" }
- { row: 0, col: 3, value: "Login", level: "read" }
- { row: 1, col: 0, value: "Full", level: "full" }
- { row: 1, col: 1, value: "R/W", level: "rw" }
- { row: 1, col: 2, value: "No access", level: "none" }
- { row: 1, col: 3, value: "No access", level: "none" }
# ... rows 2..4 follow the same pattern ...
- { row: 5, col: 0, value: "Full", level: "full" }
- { row: 5, col: 1, value: "R/W", level: "rw" }
- { row: 5, col: 2, value: "SELECT", level: "read" }
- { row: 5, col: 3, value: "SELECT only", sub: "sole consumer access", focal: true }
# ... rows 6..7 ...
none_label: "No access" # default text rendered when a cell is omitted
dark: false
```
**Reserved field semantics:**
- `roles[j].name` — primary role label (`node-name` role at 11px, white text on the ink banner)
- `roles[j].code` — secondary AD-group identifier (`sublabel` role, white text at 0.85 opacity)
- `components[i].hint` — optional right-aligned `sublabel` text in the label cell (e.g., `"SSO"`, `"S3 API"`)
- `cells[k].level` — closed vocabulary `full | rw | read | none`. Drives fill/stroke/text-color per §2.4.
- `cells[k].value` — free-form display text. Domain-specific labels (`"R/W"`, `"SELECT"`, `"Login"`) work without inventing new levels.
- `cells[k].focal: true` — exactly **one** cell may declare this. Overrides `level` to focal styling.
- `cells[k].sub` — optional 2nd-line text (used with focal). Renders in the `sublabel` role at 8px below the primary value.
- `cells[k].color: "#hex"` — optional per-cell color override (§4).
---
## 2. Layout formulas — deterministic geometry
```
# Constants
left_pad = 12
right_pad = 48
comp_col_w = 208
comp_role_gap = 12
role_col_w = 148
role_col_gap = 16
header_h = 52
row_h = 36
row_stride = 40
# Counts
n_roles = len(roles) # 2..6
n_components = len(components) # 2..14
# Canvas
viewBox_w = left_pad + comp_col_w + comp_role_gap
+ n_roles * role_col_w + (n_roles - 1) * role_col_gap
+ right_pad
# 4 roles → 12 + 208 + 12 + 592 + 48 + 48 = 920
header_y = 72
row_y(k) = 140 + k * row_stride # 140, 180, 220, ...
rows_bottom = row_y(n_components - 1) + row_h # 8 rows → 456
legend_y_top = rows_bottom + 20 # 476 for 8-row canonical
viewBox_h = legend_y_top + 44 # 520 for 8-row canonical
# Column positions
comp_col_x = left_pad # 12
role_col_x(j) = left_pad + comp_col_w + comp_role_gap
+ j * (role_col_w + role_col_gap)
# 232, 396, 560, 724
role_col_cx(j) = role_col_x(j) + role_col_w / 2 # 306, 470, 634, 798
```
### 2.1 Background
Solid paper fill across the full viewBox. No dot pattern.
### 2.2 Header row (`y = 72, h = 52`)
**Component-column header cell:**
- Rect: `(comp_col_x, header_y, comp_col_w, header_h)`, fill white, stroke `ink @ 0.12` 0.8, `rx=6`
- Two-line label centered at `(comp_col_x + comp_col_w/2, header_y+24)` and `(…, header_y+40)`:
- Line 1: `"Component"` — `node-name` role at 11px, ink
- Line 2: `"vs. AD group"` — `sublabel` role, muted
**Role banners (one per role):**
- Rect: `(role_col_x(j), header_y, role_col_w, header_h)`, fill `ink`, `rx=6`
- Two-line label centered:
- Line 1 at `y=92`: `roles[j].name` — `node-name` role at 11px, white
- Line 2 at `y=108`: `roles[j].code` — `sublabel` role, white at opacity 0.85
### 2.3 Data row (`y = row_y(k), h = 36`)
**Component label cell:**
- Rect: `(comp_col_x, row_y(k), comp_col_w, row_h)`, fill white, stroke `ink @ 0.12` 0.8, `rx=4`
- Name at `(comp_col_x + 12, row_y(k) + 22)`: `node-name` role at 11px, ink, left-aligned
- Hint (if present) at `(comp_col_x + comp_col_w − 12, row_y(k) + 22)`: `sublabel` role, muted, right-aligned
**Value cells (one per role × component):**
- Rect: `(role_col_x(j), row_y(k), role_col_w, row_h)`, `rx=4`, stroke `ink @ 0.12` 0.6
- Fill and text-color depend on `level` (or focal flag) — see §2.4
- Value text centered at `(role_col_cx(j), row_y(k) + 22)`: `node-name` role at 10px
- Focal cell uses a slightly raised primary text at `y=18` and a sub-line at `y=30` (`sublabel` role at 8px)
### 2.4 Cell style table
| `level` | Fill | Stroke | Text color | Text weight |
|---|---|---|---|---|
| `full` | `ink @ 0.08` | `ink @ 0.12` | `ink` | 600 |
| `rw` | `#FFFFFF` | `ink @ 0.12` | `ink` | 400 |
| `read` | `muted @ 0.08` | `ink @ 0.12` | `muted` | 400 |
| `none` | `paper` | `ink @ 0.12` | `soft` | 400 |
| **focal** | `accent @ 0.07` | `accent` (1.4) | `accent` | 600 |
The focal cell can carry a 2nd line (`sub:`) rendered in `accent` with the `sublabel` role at 8px and 0.85 opacity.
### 2.5 Legend (`y_top = legend_y_top, h ≈ 30`)
Hairline separator at `legend_y_top`. Below the separator, one row of style swatches with their labels — only the styles actually used in the diagram appear in the legend.
- "LEGEND" eyebrow at `(left_pad, legend_y_top + 20)`: `eyebrow` role, muted, letter-spacing 0.14em
- Each style: swatch rect (14×12 `rx=2`) followed by a `sublabel` role label
- Item x-positions are tabulated left-to-right with ~120-px stride; legend wraps onto a second visual row only if `n_roles ≥ 6` (otherwise fits in one line)
---
## 3. Cells, not connectors
A matrix diagram has **no connectors** — there are no arrows between cells, no flow lines. The diagram's information is entirely in the cell content + cell styling. The only "connector-like" element is the focal cell's accent border, which visually "calls out" a specific intersection.
Cells emit **no edges**. Don't add arrows pointing into cells or between cells — they belong in a different diagram type.
---
## 4. Color overrides
Three independent override axes — per-cell, per-component (row), per-role (column). All optional, all use the same `color: "#hex"` field, all draw from the same recommended palette. Mirrors §3.4 of `type-high-level.md`, §4 of `type-process.md`, §4 of `type-medallion.md`.
### 4.1 Per-cell `color`
Tints a specific intersection cell. Applied to:
| Element | Light | Dark |
|---|---|---|
| Cell fill | `rgba(C, 0.08)` | `rgba(C_light, 0.12)` |
| Cell stroke | `rgba(C, 0.45)` width 1.0 | `rgba(C_light, 0.55)` width 1.0 |
| Value text | `C` | `C_light` |
| Sub text (if present) | `rgba(C, 0.85)` | `rgba(C_light, 0.95)` |
`C_light` = the same hex lightened ~15% for dark-mode contrast.
### 4.2 Per-component `color` (`components[i].color`)
Tints the row's **label cell only** (left column). The data cells in that row keep their per-cell `level` styling — the row color flags *what* this component is, not *what permissions live in it*.
| Element | Light | Dark |
|---|---|---|
| Label cell fill | `rgba(C, 0.06)` | `rgba(C_light, 0.10)` |
| Label cell stroke | `rgba(C, 0.45)` width 0.8 | `rgba(C_light, 0.55)` width 0.8 |
| Component name | `C` | `C_light` |
| Hint text | unchanged (muted) | unchanged (muted) |
### 4.3 Per-role `color` (`roles[j].color`)
Tints the **column banner only** (top row). Cells underneath keep their `level` styling. Replaces the default navy banner fill with the chosen hex.
| Element | Light & Dark (banner is the same in both modes) |
|---|---|
| Banner fill | `C` |
| Role name + code text | `#FFFFFF` if `C` is dark (luminance ≤ 0.5), else `ink` |
If you pick a mid-luminance hex (e.g., yellow `#c9a23a`), the text auto-flips to ink for contrast. Pair `roles[j].text_color: "#hex"` to override this auto-pick.
### 4.4 Rules
- **Focal cell wins.** A focal cell ignores `color` overrides — accent always.
- **Per-cell `color` overrides `level` styling** for that one cell.
- **Per-component / per-role overrides are scoped:** component → row label only; role → banner only. They do **not** spread into the matrix body. To flag a specific intersection, use per-cell.
- **Cap:** keep total custom-colored entities ≤ 5 per diagram (combining cells + components + roles). Above 5, the matrix reads as colored noise — split into multiple diagrams or rethink which color carries which concern.
### 4.5 Recommended palette (same as the other parametric types)
- `#b85450` rust-red — Security elevation / break-glass / SoX-flagged
- `#5a7d9a` slate-blue — Quality / monitoring / observability gate
- `#7a8c47` olive-green — Approved / governance-cleared / publication-ready
- `#c9a23a` warm yellow — Working / sandbox / data-scientist zone
- `#8c6d3f` warm-brown — Archive / cold / DR
---
## 5. Focal rule
Exactly **one** focal cell per diagram (or zero). The focal cell:
- Uses focal styling (accent fill + accent stroke 1.4 + accent text bold)
- May carry a 2-line content: primary `value` at `y = row_y(k) + 18`, `sub` at `y = row_y(k) + 30`
- Calls out the diagram's central security claim — the *one* access rule that distinguishes this platform's posture from a generic permissions table
If zero or >1 `focal: true` cells are declared, halt and ask the user.
---
## 6. Dark mode
| Token | Light | Dark |
|---|---|---|
| Paper | `paper` | `ink` |
| Ink | `ink` | `paper` |
| Muted | `muted` | `soft` |
| Soft (no-access text) | `soft` | `muted` |
| Accent | `accent` | `accent` |
| Role-banner fill | `ink` | `ink` |
| Header / row stroke | `ink @ 0.12` | `paper @ 0.18` |
| Full / Admin fill | `ink @ 0.08` | `paper @ 0.10` |
| R/W fill | `#FFFFFF` | `paper @ 0.06` |
| Read fill | `muted @ 0.08` | `soft @ 0.12` |
| No-access fill | `paper` | `paper @ 0.02` |
| Focal fill | `accent @ 0.07` | `accent @ 0.12` |
| Focal stroke | `accent` | `accent` |
| Custom component colors | `C` | `C_light` (lighten ~15%) |
---
## 7. Reproducibility checklist (taste gate)
Before emitting SVG, verify **every** item:
1. `viewBox = "0 0 {viewBox_w} {viewBox_h}"` derived via §2 (4 roles × 8 components → 920 × 520).
2. Header row at `y=72 h=52`. Component header cell white-filled with two-line `Component / vs. AD group` label. Role banners filled `ink` with name + AD-group code in white.
3. Data rows start at `y=140`, stride 40, height 36. `rows_bottom = 140 + (n_components−1)·40 + 36`.
4. Component label cell `rx=4`, name left-aligned at `x=24`, optional `hint` right-aligned at `x = comp_col_x + comp_col_w − 12`.
5. Every value cell `rx=4`, stroke `ink @ 0.12` 0.6, fill + text matching §2.4 for its `level`.
6. Exactly **one** focal cell (or zero). Focal cell stroke `accent` width 1.4. Primary value at `y = row_y(k) + 18`; `sub` (if present) at `y = row_y(k) + 30`.
7. Cells omitted from `cells:` render as `level: "none"` with `none_label` text (default `"No access"`).
8. Custom-colored cells ≤ 2 (in addition to the focal cell).
9. No connector elements anywhere in the SVG.
10. Legend strip at `legend_y_top`, one swatch per `level` actually used, hairline separator above.
11. `viewBox_h` grows with `n_components`; `viewBox_w` grows with `n_roles`.
---
## 8. Anti-patterns
- **More than one focal cell** — focal exists to mark *the* critical access rule; >1 erases the signal.
- **Connectors anywhere** — matrix is value-driven; arrows belong in DP integration / process diagrams.
- **Freeform `level` values** — closed vocabulary is `full | rw | read | none`. Use `value` for free-form displayed text + `color` override for arbitrary tinting.
- **Per-row or per-column color tints** — apply `color` per cell only. Whole-row or whole-column highlighting tends to over-emphasize and collapses the matrix into a list.
- **Using `none_label` as a placeholder for "TBD"** — `none` means *no access*. If the permission is unknown, leave the cell empty in inputs but document it elsewhere; don't render an ambiguous state.
- **More than 6 roles** — split into two matrices (e.g., human roles vs service accounts) before exceeding 6 columns.
- **More than 14 components** — split by domain (storage / compute / observability / governance) before exceeding 14 rows.
- **Using the matrix to document *how* permissions are granted** — that belongs in a process or sequence diagram. The matrix shows *what* each role can do, not the grant flow.
---
## 9. Examples
- `assets/example-dp-security-matrix.html` — minimal light (NatStat canonical: 4 roles × 8 components, focal at Data Consumers × Trino aggregated). Gallery default.
- `assets/example-dp-security-matrix-dark.html` — same, dark skin.
- `assets/example-dp-security-matrix-full.html` — same, editorial-card frame with subtitle + summary cards.
---
## 10. Worked YAML — full inputs for `example-dp-security-matrix.html`
The complete inputs that map to the shipped canonical example. Every coordinate in that SVG is derivable from §2 applied to these inputs.
```yaml
title: "Platform Access Matrix"
subtitle: "Four canonical groups × platform components"
roles:
- { name: "Data Administrators", code: "DL-DataAdmins" }
- { name: "Data Engineers", code: "DL-DataEngineers" }
- { name: "Data Scientists", code: "DL-DataScientists" }
- { name: "Data Consumers", code: "DL-DataConsumers" }
components:
- { name: "Keycloak", hint: "SSO" }
- { name: "MinIO · raw bucket" }
- { name: "MinIO · anon · staging · agg" }
- { name: "Trino · raw catalog" }
- { name: "Trino · anon-staging" }
- { name: "Trino · aggregated" }
- { name: "JupyterHub" }
- { name: "NiFi" }
cells:
# Row 0 — Keycloak
- { row: 0, col: 0, value: "Admin", level: "full" }
- { row: 0, col: 1, value: "Login", level: "read" }
- { row: 0, col: 2, value: "Login", level: "read" }
- { row: 0, col: 3, value: "Login", level: "read" }
# Row 1 — MinIO raw
- { row: 1, col: 0, value: "Full", level: "full" }
- { row: 1, col: 1, value: "R/W", level: "rw" }
- { row: 1, col: 2, value: "No access", level: "none" }
- { row: 1, col: 3, value: "No access", level: "none" }
# Row 2 — MinIO anon/staging/agg
- { row: 2, col: 0, value: "Full", level: "full" }
- { row: 2, col: 1, value: "R/W", level: "rw" }
- { row: 2, col: 2, value: "Read", level: "read" }
- { row: 2, col: 3, value: "No access", level: "none" }
# Row 3 — Trino raw catalog
- { row: 3, col: 0, value: "Full", level: "full" }
- { row: 3, col: 1, value: "R/W", level: "rw" }
- { row: 3, col: 2, value: "No access", level: "none" }
- { row: 3, col: 3, value: "No access", level: "none" }
# Row 4 — Trino anon-staging
- { row: 4, col: 0, value: "Full", level: "full" }
- { row: 4, col: 1, value: "R/W", level: "rw" }
- { row: 4, col: 2, value: "SELECT", level: "read" }
- { row: 4, col: 3, value: "No access", level: "none" }
# Row 5 — Trino aggregated (focal cell at col 3)
- { row: 5, col: 0, value: "Full", level: "full" }
- { row: 5, col: 1, value: "R/W", level: "rw" }
- { row: 5, col: 2, value: "SELECT", level: "read" }
- { row: 5, col: 3, value: "SELECT only", sub: "sole consumer access", focal: true }
# Row 6 — JupyterHub
- { row: 6, col: 0, value: "Admin", level: "full" }
- { row: 6, col: 1, value: "R/W", level: "rw" }
- { row: 6, col: 2, value: "R/W", level: "rw" }
- { row: 6, col: 3, value: "No access", level: "none" }
# Row 7 — NiFi
- { row: 7, col: 0, value: "Admin", level: "full" }
- { row: 7, col: 1, value: "R/W", level: "rw" }
- { row: 7, col: 2, value: "Read", level: "read" }
- { row: 7, col: 3, value: "No access", level: "none" }
dark: false
```
### 10.1 What this YAML proves
Run §2 with these inputs:
- `n_roles = 4`, `n_components = 8`, no color overrides, one focal cell.
- `viewBox_w = 12 + 208 + 12 + 4·148 + 3·16 + 48 = 920` ✓
- `row_y(k)` produces `140, 180, 220, 260, 300, 340, 380, 420` ✓
- `rows_bottom = 420 + 36 = 456`; `legend_y_top = 476`; `viewBox_h = 520` ✓
- `role_col_x(j) = [232, 396, 560, 724]` ✓
- Focal cell at `(row=5, col=3)` → rect `(724, 340, 148, 36)` with accent stroke 1.4 ✓
A fresh generation from this YAML produces a diagram visually indistinguishable from the shipped `example-dp-security-matrix.html`.
## references/type-er.md
# ER / Data Model
**Best for:** conceptual and logical data models, API resource relationships, domain models — anything where the story is *entities and cardinality*.
**Not for the physical schema.** ER is entity-level: relationship lines join *boxes* and carry cardinality at each end. When the point is real tables with SQL types, constraint chips, indexes, and foreign keys that anchor **column to column**, use [`type-db-schema.md`](type-db-schema.md) instead.
## Layout conventions
- Each entity is a two-section box:
- **Header**: type tag (`ENTITY`) + entity name in Geist.
- **Body**: field list in Geist Mono, one per line. PK prefixed with `#`, FK prefixed with `→`.
- Relationships: lines between entities with cardinality at each end:
- `1`, `N`, `0..1`, `1..*` in Geist Mono, 8px, placed 10–12px from the entity edge.
- Optional relationship label ("has", "belongs to") centered on the line.
- Group related entities close; lay out so most relationships are straight lines, not tangles.
- Coral on the aggregate root or central entity of the model.
## Anti-patterns
- Drawing an arrow for every FK on a model with dozens — lay out by cluster instead.
- Inconsistent cardinality notation between ends of the same relationship.
- Fields padded to equal-height boxes — natural height by content is fine.
## Examples
- `assets/example-er.html` — minimal light
- `assets/example-er-dark.html` — minimal dark
- `assets/example-er-full.html` — full editorial
## references/type-fishbone.md
# Fishbone / Ishikawa (root-cause)
**Best for:** structured root-cause analysis. One observed effect, causes grouped by category, sub-causes hanging off each category. The standard artefact of an incident post-mortem — use it when a reader needs to see *what was investigated*, not just the conclusion.
## Layout conventions
- **Spine.** A horizontal line (`ink`, 1.2px) runs left→right at the vertical centre `CY`, terminating with an arrowhead into an **effect box** at the right head — the node-box pattern from SKILL.md §6, the observed-effect statement inside.
- **Bones.** Category lines are straight diagonals at a fixed **60°** to the spine, alternating above and below, evenly spaced along it. Each bone carries its category name at the outer end in a small tag-style box (`rx=4`, not a pill) — Geist sans 12px weight 600.
- **Sub-causes.** Short horizontal ticks (32px, `soft`) branch off each bone at fixed points along its length, each with a sub-cause label in Geist Mono 9px sitting past the open end of the tick.
- **Diagonal exemption.** SKILL.md §6 rule 1 (mandatory rounded right-angle elbows) does not apply to the 60° bones — they are this type's defining grammar. The exemption covers **bones and sub-cause ticks only**; any other connector in a fishbone diagram (e.g. a callout leader, a cross-reference arrow) still uses rounded right-angle elbows.
- **Focal rule.** Exactly one bone is the confirmed root cause: its line is `accent`, and its category tag uses `accent-tint` fill + `accent` stroke. The effect box is styled the same way (`accent-tint` fill, `accent` stroke) since it's the diagram's headline. That pair — root-cause bone and effect box — is the full 2-accent budget; every other bone, tag, and tick stays `ink` / `muted` / `soft`.
- **Drawing order:** background → spine → bones → sub-cause ticks → category tag boxes → effect box → legend. Lines before boxes, so box fills cap the line ends cleanly.
## Math
For a spine at `y = CY` with the effect box's left edge at `x = HEAD`, bone `k` (1-indexed, k = 1..6) attaches to the spine at:
```
attach_x(k) = HEAD - 160 - k * 160
```
Bones alternate above (`k` odd) and below (`k` even) the spine. A bone's far endpoint — where the category tag sits — is the integer-rounded 60° offset from its attach point:
```
dx = -96
dy = ∓168 (minus = above, plus = below)
far_x(k) = attach_x(k) + dx
far_y(k) = CY ∓ 168
```
### Pre-computed reference (5-bone layout, HEAD=1200, CY=320)
| Bone `k` | Category slot | Side | `attach_x` | `far_x, far_y` |
|---|---|---|---|---|
| 1 | first | above | 880 | 784, 152 |
| 2 | second | below | 720 | 624, 488 |
| 3 | third | above | 560 | 464, 152 |
| 4 | fourth | below | 400 | 304, 488 |
| 5 | fifth | above | 240 | 144, 152 |
A 6th bone (below) would attach at `x=80`, far endpoint `(-16, 488)`, and its category tag would run from `x=-76` to `x=44` against a viewBox that starts at `x=-40`. It clips. **Five is the ceiling at `HEAD=1200`**: to draw a 6th, widen `HEAD` *and* the viewBox width by at least 160 each, keeping the viewBox origin at `-40`. Both have to move together — widening `HEAD` alone pushes the 200px effect box to `1360..1560` past the `1440` right edge, trading a clipped tag on the left for a clipped effect on the right. Or drop a category.
**Sub-cause ticks** sit at fractions `m/6` along the bone (`m = 2, 4` for two ticks; `m = 3` for one), so their coordinates stay on the 4px grid:
```
tick_x(k, m) = attach_x(k) - 16 * m
tick_y(k, m) = CY ∓ 28 * m
```
The tick itself is a 32px horizontal line from `(tick_x, tick_y)` to `(tick_x - 32, tick_y)`; the label sits past its open end, `text-anchor="end"` at `x = tick_x - 36`, `y = tick_y - 4` (above-bones) or `tick_y + 12` (below-bones).
## Complexity budget
| Limit | Rule |
|---|---|
| Max categories (bones) | 5 at `HEAD=1200`. A 6th requires a widened canvas — see Geometry |
| Max sub-causes per bone | 3 |
| Max sub-causes total | 18 |
| Max accent elements | 2 (root-cause bone+tag, effect box) |
## Anti-patterns
- **More than 5 bones on the default canvas.** The 6th tag clips the viewBox. Widen `HEAD` and the viewBox width together and deliberately, or split by subsystem into two fishbones.
- **Sub-causes that restate the category.** A "Deploy" bone with a sub-cause labeled "deployment issue" adds a node without adding information.
- **A bone with zero sub-causes.** An empty category is a placeholder, not a finding — delete the bone or don't draw it until there's something under it.
- **Accenting more than one root cause.** If two categories are both confirmed, that's two diagrams (or a merged cause) — not two accent bones. The 2-accent budget is load-bearing for the "this is the answer" signal.
- **Using fishbone for a sequence of failures.** A chain of things that happened in order is a timeline or sequence diagram — fishbone is for causes of *one* effect, not a chronology.
- **Pasting in the classic 6M template (Man/Machine/Material/Method/Measurement/Environment) with empty categories.** Name categories from the actual investigation, not a generic checklist waiting to be filled in later.
- **Effect box phrased as a solution.** "Add a p99 alert" is a fix, not an observed effect. The box states what was seen — a symptom, a measurement, an incident — never the remedy.
## Examples
- `assets/example-fishbone.html` — minimal light. Checkout p99 latency incident, 5 categories, Data confirmed as root cause.
- `assets/example-fishbone-dark.html` — minimal dark, same data.
- `assets/example-fishbone-full.html` — full editorial: container framing + 3 summary cards of varied widths + footer.
## references/type-flowchart.md
# Flowchart
**Best for:** decision logic, algorithms, user-facing branching flows ("Should I…?"), onboarding routing, support-triage trees.
## Layout conventions
- Shape carries type, not color:
- **Oval** (`rx=20`) — start / end
- **Rectangle** (`rx=6`) — step / action
- **Diamond** — decision (≤3 exits)
- **Small filled ink dot** (`r=4`) — merge point where branches rejoin
- Flow runs top→down. From a diamond, conventional exits: Yes to the right, No below — but label every outgoing arrow regardless.
- Use coral on the happy path *or* on the single most consequential decision — never on every decision.
- If two arrows must cross, use a small arc jump on one so the crossing is readable.
## Anti-patterns
- Using fill color to signal node type (shape does that).
- Decision diamond with 4+ exits — refactor into nested diamonds.
- Unlabeled decision branches.
## Examples
- `assets/example-flowchart.html` — minimal light
- `assets/example-flowchart-dark.html` — minimal dark
- `assets/example-flowchart-full.html` — full editorial
## references/type-gantt.md
# Gantt Chart
**Best for:** project plans and roadmaps — tasks with explicit start and end dates, grouped into phases. Use when the reader needs to see temporal overlap, parallel tracks, and milestone sequencing at a glance.
## Layout conventions
- **Left label column:** x=20–200 (180px). Task names in Geist sans 11px 600. Phase labels as Geist Mono 7px eyebrows above each group.
- **Timeline area:** x=200–960 (760px). Time axis runs left→right.
- **Row height:** 40px per task. Each bar occupies h=24px centered in the row (8px top padding).
- **Time axis:** Geist Mono 8px week/month labels at x=200+i×pitch, y=56 (just above first task row). A hairline separator at y=64.
- **Phase grouping:** a subtle zone rect (same pattern as architecture zone) behind each phase's rows, with an eyebrow label in the top-left margin. Use `rgba(45,49,66,0.02)` fill, `rgba(45,49,66,0.10)` stroke.
- **Focal task bar:** 1 bar in accent fill/stroke (the key deliverable or critical path task). All others: muted fill @ 0.15, muted stroke.
- **Today / milestone marker:** optional vertical dashed line in `muted` at the current week x-position.
### Task bar pattern
```svg
Task name
Key task
```
Duration in pixels: `(end_week - start_week) × pitch`. Pitch = timeline_width / total_weeks.
## Anti-patterns
- More than 12 tasks (splits into sub-plans or collapses into phase-level view).
- More than 5 parallel tracks per phase (illegible overlap).
- Dependency arrows between tasks in v1 (add only when essential; use the annotation primitive for labels).
- Start/end dates in the bar label (put them in the x-axis or tooltip comment instead).
- Equal visual weight for all bars (the focal task must stand out).
## Examples
- `assets/example-gantt.html` — minimal light
- `assets/example-gantt-dark.html` — minimal dark
- `assets/example-gantt-full.html` — full editorial
## references/type-high-level.md
# High-Level
**Best for:** end-to-end data stack overviews — ingestion → storage → query → analytics → visualization — deployed on a container orchestrator (Kubernetes, ECS, Nomad). Combines a phase chevron banner, deployment boundary, orchestration bar, identity footer, and (optionally) a right-side vertical chevron strip for cross-cutting concerns (Orchestration, Security, Observability).
This type is **parametric**. The diagram is fully determined by a small list of inputs (chevrons, sources, components, connections). The formulas below tell you exactly where every shape lands given those inputs — two generations from the same inputs must produce visually identical SVG.
---
## 1. Inputs — the parameter contract
Before drawing, collect these from the user (or accept them as a YAML/JSON block). Everything in this reference is derived from these inputs. Don't invent geometry on the fly.
```yaml
chevrons: # ordered left → right; reserved names auto-promote to vertical
- { name: "Data sources", columns: 1 }
- { name: "Ingestion", columns: 1 }
- { name: "Storage", columns: 1 }
- { name: "Transformation", columns: 1 }
- { name: "Visualization", columns: 1 }
- { name: "Orchestration", vertical: true } # reserved → pairs with the bar
- { name: "Security", vertical: true, color: "#b85450" } # tinted to match the Identity bar below
- { name: "Observability", vertical: true } # reserved → pairs with crosscut #2
sources: # external; rendered in the dashed zone on the left
- { name: "PostgreSQL", type: "db", connects_to: ["NiFi"] }
- { name: "SFTP drop", type: "ftp", connects_to: ["NiFi"] }
- { name: "Web forms", type: "web", connects_to: ["NiFi"] }
- { name: "Legacy", type: "legacy", connects_to: ["NiFi"] }
components: # inside the cluster, plus bars and cross-cutting rows
- { name: "NiFi", chevron: "Ingestion", kind: node, icon: nifi, role: "COLL" }
- { name: "MinIO", chevron: "Storage", kind: node, icon: minio, role: "STORE", focal: true }
- { name: "Trino", chevron: "Storage", kind: node, icon: trino, role: "VIRT" }
- { name: "Notebooks", chevron: "Transformation", kind: node, icon: jupyter, role: "ANLZ" }
- { name: "Superset", chevron: "Visualization", kind: node, icon: superset, role: "DASH" }
- { name: "Airflow", chevron: "Orchestration", kind: bar, icon: airflow, subtitle: "Apache Airflow" }
- { name: "Identity", chevron: "Security", kind: cross-cutting, icon: keycloak, subtitle: "Keycloak · LDAP · OIDC", color: "#b85450" }
- { name: "Monitoring", chevron: "Observability", kind: cross-cutting, icon: prometheus, subtitle: "Prometheus · Grafana · Loki" }
connections: # explicit edges; focal-touching ones become accent automatically
- { from: "NiFi", to: "MinIO", style: "primary" }
- { from: "NiFi", to: "Trino", style: "secondary" }
- { from: "MinIO", to: "Notebooks", style: "primary" }
- { from: "Trino", to: "MinIO", style: "query" } # read-back (dashed)
- { from: "Notebooks", to: "Superset", style: "secondary" }
- { from: "Airflow", to: ["NiFi", "Trino", "Notebooks"], style: "trigger" }
focal: "MinIO" # exactly one; defaults to first kind=node under "Storage"
dark: false
```
**Reserved chevron names** (always vertical, even if `vertical: true` is omitted): `Orchestration`, `Security`, `Observability`, `Governance`, `Backup`.
**Reserved `kind` values:**
- `node` — a standard box inside the cluster (default).
- `bar` — a horizontal strip spanning the cluster top. Typically one (Orchestration); see §5 for the pairing rule.
- `cross-cutting` — a horizontal strip spanning the body width (stops at the strip margin), stacked below the cluster. **Zero or more allowed**; each stacks 44 px below the previous (§2.5) and pairs 1:1 with a vertical chevron (§5).
**Optional `color`** (per component, hex string): tints the component's container and content while leaving connectors untouched. See §3.4. Use sparingly — a custom color is a semantic flag (e.g., red = security concern), not decoration.
**Source `type` values** → icon mapping (use `references/primitive-icons.md`):
- `db` → `database`
- `ftp` → `bucket` or upload arrow
- `web` → `internet`
- `legacy` → `server`
- `api` → `api`
- Any explicit icon name in `primitive-icons.md` is also accepted.
---
## 2. Layout formulas — deterministic geometry
Every coordinate below is derived from the inputs. **No hardcoded numbers in examples that aren't justified here.**
### 2.1 Canvas
```
has_vertical = any(c.vertical or c.name in reserved_names for c in chevrons)
right_strip_w = 28 if has_vertical else 0
strip_margin = 8 if has_vertical else 0 # gap between body and right strip
effective_w = 1000 - right_strip_w - strip_margin # 1000 or 964
n_cross = count of components with kind == "cross-cutting"
strip_y_bot = max(428, 388 + n_cross * 44 - 4) # extends to last crosscut row
viewBox_h = max(540, strip_y_bot + 112) # 112 reserved for legend
viewBox = f"0 0 1000 {viewBox_h}"
```
Every horizontal element (chevron banner, cluster, orchestration bar, identity / cross-cutting bars) ends at `effective_w`. The right strip sits at `x = 1000 - right_strip_w` (= 972). The 8-px band between them is visual breathing room — never put content there.
`viewBox_h` grows when more than one cross-cutting bar is declared: 1 crosscut → 540, 2 → 600 (or 584 if you want it tight; the rule rounds to the next multiple of 20 for clean grids).
### 2.2 Horizontal chevron banner
```
y_banner = 4
h_banner = 28
horizontals = [c for c in chevrons if not c.vertical and c.name not in reserved_names]
sum_columns = sum(c.columns for c in horizontals)
base_unit = floor_to_4(effective_w / sum_columns) # multiple of 4
widths = [max(120, base_unit * c.columns) for c in horizontals]
widths[-1] += effective_w - sum(widths) # trailing absorbs remainder
x_boundaries = cumulative_sum([0] + widths) # length sum_columns+1
chevron_cx(C) = (x_boundaries[index(C)] + x_boundaries[index(C)+1]) / 2
```
**Polygon shapes:**
- First (leftmost): `(x0,4) (x1-12,4) (x1,18) (x1-12,32) (x0,32)`
- Middle: `(x0,4) (x1-12,4) (x1,18) (x1-12,32) (x0,32) (x0+12,18)`
- Last (rightmost): `(x0,4) (effective_w,4) (effective_w,32) (x0,32) (x0+12,18)`
Fills alternate `#2d3142` / `#3d4460` (light mode) or `#3d4460` / `#4a5270` (dark mode). Labels: paper-colored mono `font-size=7`, `letter-spacing=0.14em`, `text-anchor=middle`, centered at `chevron_cx, 21`.
**Color override** (per chevron, both horizontal and vertical): a chevron may declare an optional `color: "#hex"` that replaces the alternation fill for that one chevron. Use it to flag a phase that pairs with a custom-colored component (e.g., `Security` chevron in red when the Identity bar uses `color: "#b85450"`). Rules:
- Override applies to the polygon fill only. The label stays paper-colored — never recolor chevron labels.
- The alternation index doesn't shift; neighboring chevrons keep their natural fill, even if it produces two adjacent same-fill chevrons. Don't try to "fix" this — overrides should be rare (≤ 2 per diagram).
- In dark mode, use the same hex unless contrast against paper labels suffers; if it does, pick a darker shade for dark mode and document it as a `color_dark` field on that chevron.
- A chevron color override is independent of any paired component's color, but pairing them (same hex on chevron + bar) is the conventional way to make the column "read" as one concern.
### 2.3 Source zone (dashed, external)
```
sources_x = 4
sources_y = 40
sources_w = x_boundaries[1] - 8 # width of the first chevron, minus 4px gutter each side
sources_h = 336
```
Stroke: `rgba(45,49,66,0.20)`, `stroke-width=0.8`, `stroke-dasharray=6,3`, `rx=6`. Zone fill: `rgba(45,49,66,0.02)`.
### 2.4 Cluster boundary (solid)
```
cluster_x = x_boundaries[1] + 4 # starts at end of source zone + 4px gutter
cluster_y = 40
cluster_w = effective_w - cluster_x # extends to right strip / canvas edge
cluster_h = 336
```
Stroke: `rgba(45,49,66,0.18)`, `stroke-width=1.2`, `rx=8`. Fill: `rgba(45,49,66,0.02)`. K8s icon + label at `(cluster_x + 16, 352)` (icon) and `(cluster_x + 40, 362)` (text).
### 2.5 Cross-cutting bars (identity, observability, …)
Zero or more `kind: cross-cutting` components stack below the cluster. Each gets its own 40-px row with a 4-px gap.
```
crosscuts = [c for c in components if c.kind == "cross-cutting"] # ordered as declared
cross_x = 4
cross_y(k) = 388 + k * 44 # 388, 432, 476, …
cross_w = effective_w - 4 # spans body width, stops at the strip margin
cross_h = 40
```
Stroke: `rgba(45,49,66,0.20)`, `stroke-width=0.8`, `rx=6`. Fill: `rgba(45,49,66,0.05)`. Icon at `(16, cross_y(k) + 10)`, name centered at `(effective_w / 2, cross_y(k) + 22)`, subtitle at `(effective_w / 2, cross_y(k) + 34)`.
Reserved cross-cutting *concerns* (informational; user can name the actual bar whatever they want):
- **Identity / Security** — Keycloak, LDAP/AD, Okta, Auth0, OIDC providers
- **Observability** — Prometheus + Grafana, Datadog, OpenTelemetry, Loki
- **Backup / DR** — Velero, Restic, snapshot orchestrators
- **Governance / Lineage** — OpenMetadata, DataHub, Apache Atlas
- **Secrets / config** — Vault, Sealed Secrets, External Secrets
Each cross-cutting bar pairs 1:1 with a vertical chevron in the right strip (§5).
### 2.6 Orchestration bar component (inside cluster)
```
bar_x = cluster_x + 12
bar_y = 52
bar_w = cluster_w - 24
bar_h = 44
```
Stroke: `rgba(45,49,66,0.18)`, `stroke-width=0.8`, `rx=4`. Fill: `rgba(45,49,66,0.05)`. Tool icon at the far right (`bar_x + bar_w - 50, 58`); name centered at `(bar_x + bar_w/2, 71)`; subtitle at `(bar_x + bar_w/2, 84)`.
### 2.7 Component nodes (inside cluster)
```
node_w = 152
node_h = 80 # focal same height, accent border
node_cx(N) = chevron_cx(N.chevron) # ← non-negotiable
node_x(N) = node_cx(N) - node_w/2
```
If a chevron has K nodes assigned, stack them vertically:
```
first_top_y = 120 if any bar in this column else 64
gap = 16
row_top(k) = first_top_y + k * (node_h + gap) # k = 0..K-1
```
**Focal node:** `fill="rgba(235,108,54,0.08)"`, `stroke="#eb6c36"`, `stroke-width=1.2`. Title text in accent color. All other nodes: white fill, `stroke=rgba(45,49,66,0.25)`, `stroke-width=1`.
Role badge top-left at `(node_x+8, node_y+6)`, size 12 high. Icon top-right at `(node_x+node_w-32, node_y+6)`, 24×24, monochrome via `currentColor`. Name centered at `(node_cx, node_y+44)` size 11 sans semibold. Subtitle at `(node_cx, node_y+56)` size 8 mono muted.
### 2.8 Source nodes (inside dashed zone)
```
src_node_w = sources_w - 8
src_node_h = 64 # uniform; chosen to fit ≤ 4 sources
src_node_x = sources_x + 4
src_first_top_y = 60
src_gap = 16
src_row_top(k) = src_first_top_y + k * (src_node_h + src_gap)
```
Same role-badge / icon / name / subtitle pattern as cluster nodes (icon at `src_node_x+54, row_top(k)+6`; name centered at `src_node_x+src_node_w/2, row_top(k)+42`; subtitle one line below). Role badge text: `EXT`. Caps at 4 sources; for more, split into a separate diagram.
### 2.9 Right strip — vertical chevrons
```
strip_x = 1000 - right_strip_w # 972 when present
strip_w = 28
verticals = [c for c in chevrons if c.vertical or c.name in reserved_names]
strip_y_top = 40
strip_y_bot = max(428, 388 + n_cross * 44 - 4) # extends to last crosscut row (see §2.1)
strip_h_total = strip_y_bot - strip_y_top
heights = [floor_to_4(strip_h_total / len(verticals))] * len(verticals)
heights[-1] += strip_h_total - sum(heights) # last absorbs remainder
```
Examples:
- 2 verticals (Orchestration + Security), 1 crosscut → `heights = [192, 196]`, layout `[40..232, 232..428]`.
- 3 verticals (Orchestration + Security + Observability), 2 crosscuts → `strip_y_bot = 472`, `strip_h_total = 432`, `heights = [144, 144, 144]`, layout `[40..184, 184..328, 328..472]`.
Adjacent edges share the same y (no gap), like horizontal chevrons share x at their boundary.
**Polygon shapes** (top-to-bottom flow, mirrors horizontal §2.2):
- First (topmost): flat top, point at bottom — `(strip_x, y0) (strip_x+strip_w, y0) (strip_x+strip_w, y1-12) (strip_x+strip_w/2, y1) (strip_x, y1-12)`
- Middle: notch on top, point on bottom — `(strip_x, y0) (strip_x+strip_w/2, y0+12) (strip_x+strip_w, y0) (strip_x+strip_w, y1-12) (strip_x+strip_w/2, y1) (strip_x, y1-12)`
- Last (bottommost): notch on top, flat bottom — `(strip_x, y0) (strip_x+strip_w/2, y0+12) (strip_x+strip_w, y0) (strip_x+strip_w, y1) (strip_x, y1)`
Fills alternate `#2d3142` / `#3d4460` (same palette as horizontals). Labels: paper-colored mono `font-size=7`, `letter-spacing=0.14em`, **rotated −90°**, anchored at `(strip_x + strip_w/2, (y0+y1)/2)`.
Vertical chevrons honor the per-chevron `color` override documented in §2.2 — apply the hex to the polygon fill, leave the rotated label paper-colored. Pair the override with the same hex on the chevron's paired bar/crosscut to bind them visually as one concern.
---
## 3. Connector rules (mandatory)
These are non-negotiable. Pick the style **automatically** from the topology — do not let the user override style on focal-touching or bar-originating edges.
| `style` | Stroke | Width | Dash | Marker | When required |
|---|---|---|---|---|---|
| `primary` | `#eb6c36` | 1.2 | — | `arrow-accent` | Every edge whose endpoint is the `focal` node. |
| `secondary` | `#4f5d75` | 1.0 | — | `arrow` | Default for source→component and component→component when neither endpoint is focal. |
| `trigger` | `#4f5d75` | 1.0 | `4,3` | `arrow-sm` | Every edge originating from a `kind: bar` component. |
| `query` | `rgba(45,49,66,0.30)` | 1.0 | `4,3` | `arrow` | Read-back edges (e.g., focal ↔ Trino). |
**Defs block** (required, exactly these four markers):
```svg
```
### 3.1 Exit / entry sides (non-negotiable)
| Edge kind | Exit side of source | Entry side of target |
|---|---|---|
| Source → cluster node | **right** of source node | **left** of target |
| Component → component (within cluster) | **right** | **left** |
| Bar component → node | **bottom** of bar | **top** of node |
| Cross-cutting bar | — (emits no edges) | — |
| Vertical chevron | — (labels only; emits no edges) | — |
### 3.2 Routing
- Orthogonal elbows, **at most two bends** per path.
- Use a Q-bezier 8-px corner radius at every bend.
- Z-order: draw **all connectors before any node rectangle** (so node fills mask the line ends).
- Exactly one `marker-end` per `` / ``. Never both `marker-start` and `marker-end`.
- Labels: every `primary` and `secondary` connector gets a label (small mono, opaque paper-filled rect mask behind). `trigger` and `query` connectors are unlabelled.
### 3.3 Crossings
- Avoid. Re-route via the chevron divider trunk (§4) before accepting a crossing.
- If unavoidable, the path drawn second carries a 6-px arc hop over the first.
### 3.4 Component color override
A component may declare an optional `color: "#hex"` (CSS color string). The override **only** retints the component's container and content — connectors are never recolored. Edges keep their topology-driven style from §3.
**Where the color is applied** (given `C = color`):
| Element | Light mode | Dark mode |
|---|---|---|
| Container fill (`rect` body) | `rgba(C, 0.06)` | `rgba(C, 0.10)` |
| Container stroke | `rgba(C, 0.35)` (`stroke-width=1` for nodes, `0.8` for bars) | `rgba(C, 0.45)` |
| Role badge stroke (nodes) | `rgba(C, 0.40)` | `rgba(C, 0.55)` |
| Role badge text (nodes) | `rgba(C, 0.85)` | `rgba(C, 1.0)` |
| Icon fill / stroke | `C` | lighten `C` by ~15% (or use `C` if already light) |
| Name text | `C` | lighten `C` |
| Subtitle text | **unchanged** (`muted`) | **unchanged** (`muted`) |
| Connectors touching this component | **unchanged** (still topology-driven) | **unchanged** |
The subtitle stays muted because it's parenthetical metadata — only the primary identity (name + icon + border) carries the color signal.
**Rules**:
- **Never on the focal node.** The focal node is already colored with the accent (§2.7). A `color` on the focal node is ignored — accent wins.
- **Never on source nodes.** Sources live outside the cluster and stay neutral.
- **Cap at 2 custom-colored components** per diagram (in addition to the focal). Three or more colored things erases the signal — the same reason §1 limits accent to 1–2 elements.
- **No color on connectors.** If you find yourself wanting a colored edge, the right move is to pick a different `style` from §3, not to override.
**Semantic uses** (recommended):
- `#b85450` (rust-red) — Security / Identity (Keycloak, Vault)
- `#5a7d9a` (slate-blue) — Observability (Prometheus, Datadog)
- `#7a8c47` (olive-green) — Governance / Lineage (OpenMetadata)
- `#8c6d3f` (warm-brown) — Backup / DR
Stick to these unless the user's brand demands otherwise. Random hex per component is exactly the failure mode this skill avoids.
---
## 4. Block branching rules (fan-out)
The single biggest reproducibility hazard. Fix these rules and the diagram becomes predictable.
### 4.1 Source fan-out (one source → N components)
```
exit_x = source.right
trunk_x = cluster_x - 8 # 4-px gutter before cluster border
```
Path per target: `M exit_x,source_cy → H trunk_x → V target_cy → H target.left`. Use Q-bezier corners.
### 4.2 Component fan-out (one component → N components)
```
exit_x = node.right
trunk_x = x_boundaries[index(source.chevron) + 1] + 4 # 4 px past the chevron divider
```
Path per target: `M exit_x,source_cy → H trunk_x → V target_cy → H target.left`.
### 4.3 Fan-out cap
**Max 3 outgoing edges per node.** Above 3, introduce a hub (usually the `focal` node). The chevron banner is the legend; if a node is fanning out to four downstream targets, it's secretly the hub — make it explicit.
### 4.4 Bar drops (Airflow → N nodes)
```
drop_x(target) = target.cx
drop_y_start = bar.bottom
drop_y_end = target.top
```
Straight vertical line, `style: trigger`. One per target. No bends — bar drops never elbow.
### 4.5 Source vertical staggering
When multiple sources connect to the same single target (e.g. four sources → NiFi), stagger their entry y on the target:
```
entry_y(k) = target.top + 8 + k * (target_h - 16) / (N - 1) # k = 0..N-1, evenly spaced
```
This avoids overlapping arrowheads at the target's left edge.
---
## 5. Vertical chevrons — semantics
Reserved names `Orchestration`, `Security`, `Observability`, `Governance`, `Backup` always render in the right strip (§2.9). Any chevron with `vertical: true` is treated as a reserved-style vertical regardless of name. The rules:
- **Pairing rule (mandatory, 1:1):** every vertical chevron pairs with exactly one cross-spanning component, and every cross-spanning component pairs with exactly one vertical chevron. The two component kinds that pair:
- `kind: bar` — lives inside the cluster (top row). Conventionally paired with `Orchestration`.
- `kind: cross-cutting` — lives below the cluster, one row per component. Paired with `Security`, `Observability`, `Governance`, etc.
If the inputs declare a vertical chevron without a paired component (or vice versa), halt and ask the user — the diagram is incomplete.
- **Count constraint:** `len(verticals) == len(bars) + len(crosscuts)`. The right strip is split evenly among all verticals (§2.9), so visual alignment between a chevron and its bar/row is approximate — the *label* is what matters, not the y-pixel match.
- **Ordering convention:** declare verticals top-down in the order: bar-paired first (Orchestration), then crosscut-paired in the same order the crosscuts appear below the cluster. This keeps the visual reading order consistent.
- **No edges:** vertical chevrons emit no connectors themselves. They are *labels for a column of cross-cutting concern*.
- **No node placement:** no `kind: node` may be assigned to a vertical chevron. Nodes always belong to a horizontal phase.
- **Right strip presence:** if any vertical chevron exists, the right strip is reserved (`effective_w = 964`) and **all** horizontal chevron widths and cluster geometry shrink accordingly. Do not draw a vertical chevron on top of the cluster.
The visual contract: the vertical chevron's column visually "owns" the bar/cross-cutting row at its approximate y-band. Orchestration (top of strip) ↔ Airflow bar (top of cluster). Security ↔ Identity bar. Observability ↔ monitoring bar (below identity). And so on.
---
## 6. Dark mode
When `dark: true`, swap these tokens:
| Token | Light | Dark |
|---|---|---|
| Page paper | `#f5f5f5` | `#1c1f2e` |
| Ink | `#2d3142` | `#f5f5f5` |
| Muted text | `#4f5d75` | `rgba(245,245,245,0.65)` |
| Chevron dark fill | `#2d3142` | `#3d4460` |
| Chevron light fill | `#3d4460` | `#4a5270` |
| Chevron label | `#f5f5f5` | `#f5f5f5` (unchanged) |
| Dashed border | `rgba(45,49,66,0.20)` | `rgba(245,245,245,0.22)` |
| Cluster border | `rgba(45,49,66,0.18)` | `rgba(245,245,245,0.18)` |
| Node fill | white | `rgba(245,245,245,0.06)` |
| Node stroke | `rgba(45,49,66,0.25)` | `rgba(245,245,245,0.20)` |
| Focal fill | `rgba(235,108,54,0.08)` | `rgba(240,138,89,0.12)` |
| Focal stroke | `#eb6c36` | `#f08a59` |
| Accent connector | `#eb6c36` | `#f08a59` |
| Dot pattern | `rgba(45,49,66,0.10)` | `rgba(245,245,245,0.10)` |
---
## 7. Reproducibility checklist (the taste gate)
Before emitting SVG, verify **every** item. If any fails, fix it — don't ship.
1. Every cluster `node.cx` equals its chevron's `cx` (§2.2 + §2.7). This is what makes the chevron banner a real legend.
2. Every chevron `width` is a multiple of 4 and ≥ 120.
3. The reserved right strip (28 px) exists **iff** any vertical chevron is declared. If yes, `effective_w = 964`; if no, `effective_w = 1000`.
4. Exactly **one** `focal` node. If `focal` is unset in inputs, default to the first `kind: node` under chevron "Storage".
5. Every edge whose endpoint is the focal node uses `style: primary` (accent stroke + `arrow-accent` marker).
6. Every edge originating from a `kind: bar` component uses `style: trigger` (dashed + `arrow-sm`).
7. The cross-cutting bar (if any) emits **no** edges.
8. No node has > 3 outgoing edges, or if it does, it is the declared `focal` / hub.
9. All `` and `` connectors are emitted **before** any node `` (z-order).
10. Each vertical chevron pairs **1:1** with exactly one `bar` or `cross-cutting` component (§5 pairing rule). `len(verticals) == len(bars) + len(crosscuts)`.
11. `viewBox_h = max(540, strip_y_bot + 112)` — grow the canvas when multiple crosscuts are declared so the legend still fits.
12. Custom component colors (§3.4) apply only to container + icon + name; connectors stay topology-driven. Cap at 2 custom-colored components in addition to the focal.
13. The diagram passes SKILL.md §9 (4-px grid; ≤ 2 accent elements; mono only for technical content; hairlines; no shadows; no `rounded-2xl`).
---
## 8. Anti-patterns
- Chevron banner omitted — it's the key that maps visual columns to functional phases.
- Node x-center off-chevron (§7 #1) — breaks the "banner-as-legend" contract.
- Vertical chevron drawn on the cluster (overlay) instead of in a reserved right strip.
- More than one focal node — MinIO/S3 (or whichever storage hub) is *the* focal point.
- External zone with solid border — dashed border is the signal that these components are outside the cluster.
- Identity bar inside the cluster boundary — it applies to all components and must span the full canvas width.
- Vertical chevron without a paired bar/cross-cutting component — see §5 pairing rule.
- Bar-component edges drawn solid — orchestration triggers must be dashed.
- Source fanning out to >3 components without a hub.
---
## 9. Examples
- `assets/example-high-level.html` — horizontal-only, 5 phases, light skin.
- `assets/example-high-level-dark.html` — same, dark skin.
- `assets/example-high-level-full.html` — same, editorial-card frame.
- `assets/example-high-level-vertical.html` — adds vertical Orchestration + Security chevrons, Airflow bar, Keycloak cross-cutting. **Reference render of the full parametric pattern.**
- `assets/example-high-level-vertical-dark.html` — vertical pattern, dark skin.
- `assets/example-high-level-vertical-full.html` — vertical pattern, editorial-card frame.
- `assets/example-datalake.html` — unclustered five-phase data stack (Sources → Ingest → Data Lake → Query → Consume), zone-based flow without a container-orchestrator boundary. The MinIO lake is the focal node; vertical concerns are flattened into the horizontal chevron banner. Light skin.
- `assets/example-datalake-dark.html` — same, dark skin.
- `assets/example-datalake-full.html` — same, editorial-card frame.
## references/type-it-state.md
# IT current-state
**Best for:** documenting the *before* picture of a modernization proposal — the legacy IT landscape grouped by phase or department (Collection → Processing → Dissemination, or Frontend / Backend / Storage, or Survey → Analysts → Reports), with pain-points flagged, file-based hand-offs labelled (CSV / Excel / Email / Copy), and pre-platform tooling visible. The companion to `type-dp-integration.md`: this type shows the gap that a data-platform proposal is going to close.
Use when stakeholders need to see the friction in the current setup — siloed scripts, manual file shuffles, missing version control, single-points-of-failure — and the path from those to a target platform topology.
This type is **parametric** — the inputs schema in §1 drives every coordinate via the formulas in §2. The rule shape mirrors `type-dp-integration.md` (zones + cross-cutting footer bars), `type-process.md` (rounded right-angle connectors), and `type-medallion.md` (per-element `color` override) so the focal rule, color override, dark mode, and reproducibility checklist read identically across types.
---
## 1. Inputs — the parameter contract
```yaml
title: "Current IT Landscape"
subtitle: "Data pipeline before the platform"
eyebrow: "NatStat · Before the platform"
orientation: horizontal # horizontal (default, zones L→R) | vertical (zones T→B)
zones: # 2..4 zones, ordered along the orientation axis
- name: "COLLECTION"
components: # 1..5 components per zone
- id: survey-solutions
name: "Survey Solutions"
sub: "CAPI · PostgreSQL"
icon: postgres # any id from references/primitive-icons.md
kind: standard # standard | focal | external (external → dashed stroke)
- { id: aspnet, name: "ASP.NET Apps", sub: "migration · admin portals", icon: server }
- { id: civil-reg, name: "Civil Registry", sub: "external · CRVS data", icon: database, kind: external }
- name: "PROCESSING"
components:
- { id: shared-drive, name: "Shared Drive", sub: "No version control · Windows file share", icon: file, kind: focal }
- { id: analyst-mach, name: "Analyst Machines", sub: "SPSS · SAS · Stata · Excel", icon: desktop }
- { id: sql-server, name: "SQL Server", sub: "on-premises · core RDBMS", icon: sqlserver, color: "#7a8c47" } # custom olive
- name: "DISSEMINATION"
components:
- { id: legacy-portal, name: "LegacyPortal", sub: "manual bottleneck", icon: cloud, kind: focal }
- { id: natstat-website, name: "NatStat Website", sub: "public · static pages", icon: internet }
- { id: ministry, name: "Ministry Partners", sub: "~6 ministries", icon: users, kind: external }
connectors: # ordered list; each links two component ids
- { from: survey-solutions, to: shared-drive, label: "CSV", icon: csv, style: link }
- { from: aspnet, to: shared-drive, label: "EMAIL", icon: file, style: link } # `mail` MISSING in catalog → falls back to `file`
- { from: civil-reg, to: shared-drive, label: "EXCEL", icon: excel, style: link, dashed: true }
- { from: shared-drive, to: analyst-mach, label: "COPY", style: accent, dashed: true }
- { from: analyst-mach, to: sql-server, label: "LOAD", style: neutral }
- { from: analyst-mach, to: legacy-portal, label: "EXCEL", icon: excel, style: accent }
- { from: legacy-portal, to: natstat-website, label: "WEB", style: neutral }
- { from: natstat-website, to: ministry, label: "CSV DL", icon: csv, style: link, dashed: true }
footer: # 0..3 optional full-canvas-width bars (cross-cutting concerns)
- { name: "Identity Manager", sub: "Active Directory · LDAP · SSO", icon: active-directory }
- { name: "Observability", sub: "logs · metrics · alerts", icon: monitoring }
legend: # auto-generated from styles used; user can override labels
- { swatch: link, label: "data flow" }
- { swatch: accent, label: "pain-point" }
- { swatch: dashed, label: "external" }
- { swatch: focal, label: "bottleneck" }
dark: false
```
**Reserved field semantics:**
- `orientation` — `horizontal` (zones run L→R, components stack vertically inside each zone) or `vertical` (zones stack T→B, components run L→R inside each zone).
- `zones[i].name` — uppercase short label (≤ 14 chars). Rendered at the top-left of the zone box in the `eyebrow` role with letter-spacing 0.14em, on a paper-masked break in the zone border.
- `components[i][k].id` — globally unique slug; referenced by `connectors[].from/to`.
- `components[i][k].name` — `node-name` role (the human-readable label).
- `components[i][k].sub` — `sublabel` role at 10px in muted (the technical sub-label; up to 2 lines via auto-wrap when component height grows to 72).
- `components[i][k].icon` — any id from `references/primitive-icons.md`. If missing → no icon, the name shifts left. (Catalog has 41 icons; `mail` is currently missing — use `icon: file` as fallback for email hand-offs.)
- `components[i][k].kind` — `standard | focal | external`. `focal` triggers the accent palette (§5); `external` switches to a 4-2 dashed stroke and muted ink to signal "this is outside our scope."
- `components[i][k].color` — optional per-component color override (§4). Ignored on `kind: focal` (accent wins).
- `connectors[k].from` / `connectors[k].to` — refer to a component `id`. Cross-zone, cross-row, same-zone vertical, and same-zone horizontal all legal; routing chosen by §3.
- `connectors[k].label` — uppercase short text (≤ 8 chars). `arrow-label` role at 9px, weight 600.
- `connectors[k].icon` — optional inline icon to the left of the text. Same catalog as component icons.
- `connectors[k].style` — `neutral | link | accent`. Drives stroke color + marker.
- `connectors[k].dashed` — `true | false`.
- `footer[k]` — optional cross-cutting bar. Spans full canvas width minus margins. No connectors drawn from a footer.
- `legend[k].swatch` — `link | accent | dashed | focal | neutral`. Auto-curated based on what the diagram actually uses; user can re-order or rename.
---
## 2. Layout formulas — deterministic geometry
```
# Horizontal orientation (default)
left_pad = 16
right_pad = 16
zone_gap = 20
zone_y = 52
zone_h = 360
n_zones = len(zones)
# Zone widths: base 200 + 24 per component to give vertical room for icons + 2-line subs.
# In the canonical example (3 / 3 / 3 components) the replication used 256 / 360 / 272 —
# the formula approximates that with hand-picked widths in the worked YAML (§10).
zone_w(i) = base + n_components_i * comp_slack # base ≈ 200, slack ≈ 24
viewBox_w = left_pad + Σ zone_w(i) + (n_zones-1) * zone_gap + right_pad
# Component placement within zone i
comp_pad_x = 20 # x-inset from zone border
comp_h = 56 # 68 for focal (2-line sub), 72 if both sub lines present
comp_gap = 32
comp_y(i, k) = zone_y + 28 + k * (comp_h + comp_gap)
# Component centerlines (used for connector routing)
comp_x(i) = zone_x(i) + comp_pad_x
comp_w(i) = zone_w(i) - 2 * comp_pad_x
comp_cx(i) = comp_x(i) + comp_w(i)/2
comp_cy(i, k) = comp_y(i, k) + comp_h/2
# Footer bars (if present)
footer_bar_h = 56
footer_gap = 8
footer_top = zone_y + zone_h + 24
footer_y(k) = footer_top + k * (footer_bar_h + footer_gap)
footer_bottom = footer_top + N_footer * (footer_bar_h + footer_gap) - footer_gap
# Total canvas height
legend_block_h = 40
content_bottom = N_footer > 0 ? footer_bottom : zone_y + zone_h
viewBox_h = content_bottom + legend_block_h + 24
```
### 2.1 Background and zone frame
Solid paper fill across `viewBox`. No dot pattern. Each zone box:
```svg
{name}
```
### 2.2 Component box
Three visual kinds:
| `kind` | Fill | Stroke | Stroke width | Stroke dash | Name ink | Sub ink |
| --- | --- | --- | --- | --- | --- | --- |
| `standard` | `#FFFFFF` | `ink` | 1 | — | `ink` | `muted` |
| `focal` | `accent @ 0.07` | `accent` | 1.4 | — | `ink` | `accent` (line 1) + `muted` (line 2) |
| `external` | `#FFFFFF` | `muted` | 1 | `4,3` | `ink` | `muted` |
**Icon placement** (24×24, monochrome via `currentColor` — see `references/primitive-icons.md`):
```svg
```
Icon takes 24 × 24 → 36-px total horizontal footprint with the 12-px left pad. Name and sub-label baseline shifts right by 40 px.
**Name + sub baselines** (left-aligned, with icon to the left):
```
name_x = comp_x + 44
name_y = comp_y + (comp_h/2) - 2
sub_y = comp_y + (comp_h/2) + 14
```
### 2.3 Connector geometry (§3 holds the routing rules)
```
src_right = comp_x(i_src) + comp_w(i_src)
src_left = comp_x(i_src)
src_top = comp_y(i_src, k_src)
src_bot = src_top + comp_h_src
src_cy = src_top + comp_h_src/2
dst_left = comp_x(i_dst)
dst_right = comp_x(i_dst) + comp_w(i_dst)
dst_top = comp_y(i_dst, k_dst)
dst_bot = dst_top + comp_h_dst
dst_cx = comp_cx(i_dst)
dst_cy = dst_top + comp_h_dst/2
# Corridor x for cross-zone H+Q+V routing
corridor_x = dst_cx # land arrow on dst horizontal center, enter via top/bot
```
### 2.4 Footer bar
```svg
{name}
{sub}
```
Footer bars are layer-wide services. **No connectors emerge from them.** They sit visually below the zones and let the reader see the cross-cutting concerns at a glance.
### 2.5 Legend strip
Hairline divider at `y = content_bottom + 16`, then a row of swatches + labels at `y = content_bottom + 36`. Only the styles actually used by `connectors[]` (plus `focal` and `external` if those component kinds are present) appear in the legend.
---
## 3. Connector rules (mandatory)
### 3.1 Path shape — rounded right-angle Q-bezier, r = 8
Reused verbatim from `type-process.md` §3.1. No diagonals — ever.
```svg
```
### 3.5 Connector label = inline icon + text, placed at the START of the connector with a perpendicular margin
The label sits **near the source end** of the connector (not at the mid-segment) and is **offset perpendicular to the line** so it never overlaps the stroke. Icon (when `icon:` is set) sits inside the label's paper-fill mask, to the left of the text.
```svg
{label}
```
**Placement formulas** (label box is 18px tall × `w` wide; centered on `{label_cx, label_cy}`):
| Segment exiting source | `label_cx` | `label_cy` | Effect |
| --- | --- | --- | --- |
| Horizontal (right exit) | `src_right + 6 + w/2` | `src_cy − 14` | Label sits 6 px past the source, 5 px above the line |
| Horizontal (left exit, backward) | `src_left − 6 − w/2` | `src_cy − 14` | Label sits 6 px before the source, 5 px above the line |
| Vertical (bottom exit) | `src_cx + 6 + w/2` | `src_bot + 14` | Label sits 6 px right of the line, 5 px below the source edge |
| Vertical (top exit, backward) | `src_cx + 6 + w/2` | `src_top − 14` | Label sits 6 px right of the line, 5 px above the source edge |
For cross-zone H+Q+V routes the label binds to the **horizontal** segment, since that segment is anchored at the source. Place the label early on that horizontal run — never on the Q-bend or the vertical tail.
- `w = text_w + (icon ? 30 : 12)` — auto-fit.
- Mask `fill` resolves to `paper` in light mode and `ink` in dark mode. The mask is kept as a safety pad — even though the label no longer sits on the line, it can graze zone backgrounds and component fills, and the mask preserves contrast.
- `stroke_color` follows §3.4 (text + icon inherit the connector's accent / link / neutral color).
### 3.6 Z-order
All connectors (paths + lines + labels) emit BEFORE any component rect, so node fills mask the line ends. The connector label is the exception — it draws AFTER its line so the mask sits on top.
---
## 4. Component color override (per-component `color: "#hex"`)
Per-component, same shape as every other parametric type in this skill.
| Element | Light | Dark |
| --- | --- | --- |
| Container fill | `rgba(C, 0.06)` | `rgba(C_light, 0.10)` |
| Container stroke | `rgba(C, 0.45)` (width 1) | `rgba(C_light, 0.55)` |
| Component name text | `C` | `C_light` |
| Icon glyph | inherits ink via `currentColor` (unchanged) | inherits ink (unchanged) |
| Sub-label | muted (unchanged) | muted (unchanged) |
| Connectors touching this component | **unchanged** — topology-driven | **unchanged** |
`C_light` = the same hex lightened ~15 % for dark-mode contrast (e.g., `#7a8c47` → `#9aac67`, `#b85450` → `#d97a78`).
**Rules:**
- **Never on focal components.** `kind: focal` always renders accent; `color` is silently ignored.
- **Never on connectors.** Connector style is topology-driven; if you want a colored edge, pick `style: accent` / `link` / `neutral`, not a component color.
- **Cap: ≤ 3 custom-colored components per diagram** (in addition to focal components). Above 3 the visual signal fragments.
**Recommended cross-type palette** (same as `type-medallion.md` / `type-process.md` / `type-dp-integration.md` / `type-dp-security-matrix.md`):
- `#b85450` rust-red — security / governance / pain-point that isn't focal
- `#5a7d9a` slate-blue — observability / quality / monitoring gate
- `#7a8c47` olive-green — survivor system (the one tool the new platform keeps)
- `#c9a23a` warm yellow — sandbox / dev / scratch
- `#8c6d3f` warm-brown — archive / cold / DR
---
## 5. Focal rule
- `kind: focal` components: **≤ 2 per diagram** (zero is also valid for diagrams without a single dominant pain-point).
- Auto-styling: accent stroke 1.4, accent-tinted fill 7 %, ink-bold `node-name`, accent line-1 `sublabel`.
- Any connector with a focal endpoint automatically renders in `style: accent`; the YAML `style:` is ignored.
- Custom `color: "#hex"` on a focal component is silently ignored — accent always wins.
If your diagram needs more than 2 focal components, you've collapsed two narratives. Split: one "collection pain-points" diagram + one "dissemination pain-points" diagram.
---
## 6. Dark mode
| Role | Light | Dark |
| --- | --- | --- |
| paper | `paper` | `ink` |
| ink | `ink` | `paper` |
| muted | `muted` | `muted` |
| accent | `accent` | `accent` |
| link | `link` | `link` |
| zone background | `ink @ 0.02` | `paper @ 0.04` |
| zone border | `ink @ 0.10` | `paper @ 0.14` |
| standard component fill | `#FFFFFF` | `paper @ 0.04` |
| standard component stroke | `ink` | `paper @ 0.32` |
| focal fill | `accent @ 0.07` | `accent @ 0.12` |
| focal stroke | `accent` | `accent` |
| external stroke | `muted` (dashed) | `muted` (dashed) |
| footer fill | `ink @ 0.03` | `paper @ 0.05` |
| footer stroke | `ink @ 0.18` | `paper @ 0.20` |
| label mask fill | `paper` | `ink` |
| custom-color components | `C` | `C_light` (≈ +15 %) |
---
## 7. Reproducibility checklist (taste gate)
Before emitting SVG, verify **every** item:
1. Eyebrow + title + subtitle present at canonical y-positions (24 / 36 / 52); body padding 32 px.
2. 2..4 zones; each has its uppercase label at the top-left of its zone box, on a paper-masked break in the border.
3. Every component has `id`, `name`. `sub`, `icon`, `kind`, `color` are optional.
4. ≤ 2 components with `kind: focal`; focal styling auto-applied (accent fill 7 %, accent stroke 1.4, italic line-1 sub).
5. Every connector exits the right (or bottom) of source and enters the top (or left) of destination; rounded right-angle Q-bezier `r=8` at every bend; marker triangle visibly touches the destination rectangle edge.
6. Connector labels sit at the **start** of the connector (not mid-segment) and are offset **perpendicular** to the line (5 px gap above for horizontal segments, 6 px gap to the right for vertical segments) — never overlapping the stroke. Paper-fill mask kept behind text; icon (when `icon:` is set) sits left of text inside the same mask.
7. ≤ 3 custom-colored components; none on focal.
8. ≤ 3 footer bars; each spans `viewBox_w − 2*left_pad`; no connectors emerge from any footer.
9. Legend at bottom: hairline separator + one swatch per style actually used.
10. `arrow-label` for connector labels, `eyebrow` for the page eyebrow and zone labels, `title` for the page title, `node-name` for the subtitle and component names, and `sublabel` for technical sub-labels.
11. Markers `#arrow` / `#arrow-link` / `#arrow-accent` defined once in ``; no inline marker definitions.
12. Dark variant: resolve every semantic token through its dark-mode value; custom colors are lightened ~15 %.
---
## 8. Anti-patterns
- **Diagonal arrows.** The NatStat replication has one (analyst → LegacyPortal). The new type forbids it — always rounded right-angle Q-bezier.
- **Marker not touching the target.** Path ends at the centroid or stops short of the border.
- **Inline `text` connector labels without a mask rect.** The connector line can bleed through the text and it becomes unreadable.
- **Labels sitting on top of the connector line, mid-segment.** Labels belong at the *start* of the connector with a perpendicular margin (see §3.5) — burying them in the middle of the line hides the source-to-destination direction and forces the reader's eye to fight the mask.
- **Tiny text badges as icons.** The source uses 7-px `DB` / `APP` / `EXT` badges; this type uses real 24-px catalog icons. Text badges are only acceptable as the label text, not as the component "icon."
- **Custom color on a focal component.** Focal always wins; user-set `color` silently ignored on `kind: focal`.
- **Footer bar wired to one component.** Footer = cross-cutting layer-wide concern; a connector from a footer to a specific component is a category error (use `type-dp-integration.md`'s AUTH-line pattern only when the footer service truly authenticates *all* components, and even then the line lands at the zone bottom edge, not at a specific tool).
- **> 16 total components or > 5 per zone.** Density cap; split into two diagrams.
- **Mixing orientations within one diagram.** Pick one — `horizontal` or `vertical` — and apply it to every zone.
- **Using `kind: focal` to flag every painful thing.** Focal exists for ≤ 2 narrative pain-points; for "this is bad but not headline-bad", use `color: "#b85450"` rust-red instead.
---
## 9. Examples
- `assets/example-it-state.html` — minimal light (NatStat canonical: 3 zones, 9 components, 8 connectors, 0 footer bars, SQL Server tinted olive). Gallery default.
- `assets/example-it-state-dark.html` — same, dark skin.
- `assets/example-it-state-full.html` — same, editorial-card frame with summary cards.
- `assets/example-it-state-extended.html` — exercises §4 color override + footer bars: 2 footer bars (Identity Manager + Observability) below the zones, third custom color on Analyst Machines (slate-blue, data-quality concern).
- `assets/example-it-state-extended-dark.html` — extended pattern, dark skin.
---
## 10. Worked YAML — full inputs for `example-it-state.html`
The complete inputs that map to the shipped canonical example. Every coordinate in that SVG is derivable from §2 applied to these inputs.
```yaml
title: "Current IT Landscape"
subtitle: "Data pipeline before the platform"
eyebrow: "NatStat · Before the platform"
orientation: horizontal
zones:
- name: "COLLECTION"
components:
- { id: survey-solutions, name: "Survey Solutions", sub: "CAPI · PostgreSQL", icon: postgres }
- { id: aspnet, name: "ASP.NET Apps", sub: "migration · admin portals", icon: server }
- { id: civil-reg, name: "Civil Registry", sub: "external · CRVS data", icon: database, kind: external }
- name: "PROCESSING"
components:
- { id: shared-drive, name: "Shared Drive", sub: "No version control · Windows file share", icon: file, kind: focal }
- { id: analyst-mach, name: "Analyst Machines", sub: "SPSS · SAS · Stata · Excel", icon: desktop }
- { id: sql-server, name: "SQL Server", sub: "on-premises · core RDBMS", icon: sqlserver, color: "#7a8c47" }
- name: "DISSEMINATION"
components:
- { id: legacy-portal, name: "LegacyPortal", sub: "manual bottleneck", icon: cloud, kind: focal }
- { id: natstat-website, name: "NatStat Website", sub: "public · static pages", icon: internet }
- { id: ministry, name: "Ministry Partners", sub: "~6 ministries", icon: users, kind: external }
connectors:
- { from: survey-solutions, to: shared-drive, label: "CSV", icon: csv, style: link }
- { from: aspnet, to: shared-drive, label: "EMAIL", icon: file, style: link }
- { from: civil-reg, to: shared-drive, label: "EXCEL", icon: excel, style: link, dashed: true }
- { from: shared-drive, to: analyst-mach, label: "COPY", style: accent, dashed: true }
- { from: analyst-mach, to: sql-server, label: "LOAD", style: neutral }
- { from: analyst-mach, to: legacy-portal, label: "EXCEL", icon: excel, style: accent }
- { from: legacy-portal, to: natstat-website, label: "WEB", style: neutral }
- { from: natstat-website, to: ministry, label: "CSV DL", icon: csv, style: link, dashed: true }
dark: false
```
### 10.1 What this YAML proves
- `n_zones = 3`, components per zone `= [3, 3, 3]`, custom color count = 1 (SQL Server), focal count = 2 (Shared Drive, LegacyPortal), external count = 2 (Civil Registry, Ministry Partners).
- Zone widths in canonical: 256 / 360 / 272 ⇒ `viewBox_w = 16 + 256 + 20 + 360 + 20 + 272 + 16 = 960` ✓
- `viewBox_h = 52 + 360 + 40 + 24 = 500` (no footer bars) ✓
- Shared Drive (focal) at zone 2, row 0: `x = 340, y = 80, w = 264, h = 68` (focal stretches to 68 to fit 2-line sub) ✓
- LegacyPortal (focal) at zone 3, row 0: `x = 704, y = 80, w = 208, h = 60` ✓
- SQL Server (custom olive) at zone 2, row 2: container fill `rgba(122,140,71,0.06)`, stroke `rgba(122,140,71,0.45)`, name text `#7a8c47` ✓
- Connectors 4, 5 (within zone 2) and 7, 8 (within zone 3) are simple vertical `` elements. Cross-zone connectors take rule-compliant routes (see SKILL.md §6 rules 4 & 5):
- **All three Survey-side → Shared Drive connectors (C1 / C2 / C3) enter Shared Drive's LEFT edge.** A top-edge entry would push the marker body (7 px back along travel, given `refX = 7`) *inside* the destination box, where the box's paper-fill mask hides it — only a 1-pixel tip would peek above the stroke. Entering the left edge with a right-going path keeps the body outside the box and the arrow visible (~7 px shown to the left of the box edge). The three left-edge attach points are fanned at **y = 108 / 124 / 140** (16-px spacing, well above the 12 px rule-4 minimum).
- **C1** (Survey → Shared Drive) source y matches landing y: single horizontal `M 252,108 H 340`. No bends needed.
- **C2** (ASP.NET → Shared Drive) detours up through zone-2 background — vertical at `x = 316` (clear of Shared Drive's left edge at `x = 340`): `H 308 Q 316,196 316,188 V 132 Q 316,124 324,124 H 340`. Lands at `(340, 124)`.
- **C3** (Civil Registry → Shared Drive) detours up through zone-2 background — vertical at `x = 332` (clear of Analyst Machines, which starts at `x = 340`): `H 324 Q 332,284 332,276 V 148 Q 332,140 340,140`. Lands at `(340, 140)` via a final Q-bend (no trailing H needed).
- **C6** (Analyst Machines → LegacyPortal) cannot use a direct H+Q+V into LegacyPortal's left edge — Analyst Machines and LegacyPortal are in different rows, and the direct horizontal at `y = 268` would cross NatStat Website. It detours through the zone gap and **over** LegacyPortal: `H 654 Q 662,268 662,260 V 72 Q 662,64 670,64 H 800 Q 808,64 808,72 V 80` — vertical at `x = 662` (in zone gap), horizontal at `y = 64` (above LegacyPortal top), then down into LegacyPortal's top center. The path enters LegacyPortal from **above** going down, so the arrow body lives above the box (visible) and only the 1-px tip enters the box.
**Marker-visibility rule of thumb:** with the standard arrow marker (`markerWidth = 8`, `refX = 7`), the arrow body extends 7 px *backwards* along the path direction from the endpoint. For the arrow to remain visible, that 7-px tail must sit *outside* the destination box. Translation:
- Entering a **TOP edge going UP** (path direction up, box below) → body inside box, **only 1 px visible. Avoid this.**
- Entering a **TOP edge going DOWN** (path direction down, box below) → body above box, ~7 px visible. ✓
- Entering a **LEFT edge going RIGHT** → body to the left of box, ~7 px visible. ✓
- Entering a **RIGHT edge going LEFT** → body to the right of box, ~7 px visible. ✓
- Entering a **BOTTOM edge going DOWN** (box above) → body inside box, **only 1 px visible. Avoid this.**
- Entering a **BOTTOM edge going UP** (box above) → body below box, ~7 px visible. ✓
When the source row matches the destination row's y range (e.g., Survey at y=108 with Shared Drive at y=80–148), prefer **side-edge** entry — a single horizontal path with a fully visible arrow. When the source row is offset, detour through the destination's nearest zone background to enter a side edge rather than approaching a top/bottom edge from the wrong side.
The extended example (§9 line 4) demonstrates footer bars + a third custom color and proves `viewBox_h` grows correctly when `N_footer > 0`.
## references/type-journey.md
# User Journey Map
**Best for:** what a person does across the stages of an experience and how it *feels* at each one. The sentiment curve is the load-bearing element — without it this is just a process diagram with extra rows, so if you can't name a sentiment for every stage, use **Process** or **Timeline** instead.
## Layout conventions
Vertical stack, top to bottom, for one persona:
- **Stage headers** — 5 equal columns, 200px wide, 24px gutters (max 6 stages). Each column: a Geist Mono 8px uppercase tracked eyebrow (`STAGE 1` … `STAGE 5`) over the stage name in Geist sans 12px weight 600, both centered on the column.
- **Sentiment band (the differentiator)** — a 160px-tall plot area directly under the headers. 3 horizontal reference hairlines at `rule` 0.10 opacity mark the levels `HIGH` / `NEUTRAL` / `LOW` — Geist Mono 8px `muted`, anchored `end` in a 64px left margin. **Never emoji, never `writing-mode` vertical text for these labels.** A smooth `muted` 1.5px polyline runs through one `r=5` dot per stage, each value snapped to one of five ordinal levels (`HIGH`, `MED-HIGH`, `NEUTRAL`, `MED-LOW`, `LOW`) — only the three that are actually used need a labeled hairline. The trough stage's dot and its incoming segment are `accent`; everything else on the curve is `muted`.
- **Content rows** — up to 3 labelled bands below the sentiment band, each with a Geist Mono 8px uppercase row label sitting in the left margin (same column as the sentiment level labels, never rotated):
- `ACTIONS` — what the user does, Geist sans 12px, one short line per stage.
- `TOUCHPOINTS` — the surface the action happens on (email, app, docs…), Geist Mono 9px `muted`.
- An optional third row for a metric or owner, same treatment as touchpoints.
Rows are separated by hairlines that span the full plot width (from the left margin edge to the last stage's right edge).
- **Pain markers** — on stages where sentiment drops, a small dashed-stroke tag box (`rx=2`, `accent @ 0.50` stroke dashed `3,3`, no fill or a faint accent tint) sits under that stage's actions cell, with a Geist Mono 8px label naming the friction. Max 2 per diagram, and only on the trough — tagging every stage erases the signal.
- **Legend** — horizontal strip at the bottom per the global rule (hairline separator above, 160–180px between entries): three keys, in order — the sentiment line, the trough-stage highlight, and the pain-marker tag. The trough key is not optional: the dip is the finding, so the reader needs the highlight named.
## Connector note
The sentiment polyline is a **data curve**, not a connector between nodes — §6 rule 1 (mandatory orthogonal elbows) does not apply to it. This exemption covers the sentiment curve **only**; any other connector in a journey map (there normally are none) still follows the standard connector rules.
## Geometry
- Stage grid: left margin 64px, then 5 columns of 200px with 24px gutters (`col_left = 64 + i·224`).
- Sentiment band: 160px tall. Hairlines at the top (`HIGH`), middle (`NEUTRAL`), and bottom (`LOW`) of the band, 80px apart.
- Dot x = the horizontal center of its stage column. Dot y = the snapped level's hairline y (or the interpolated position for an unlabeled level).
- Row height: enough for one line of text plus, in the `ACTIONS` row only, up to two stacked 16px-tall pain-marker boxes.
## Focal rule
Exactly 2 accent elements: the trough dot + its incoming curve segment (counts as one), and its pain marker(s) (counts as the other). Nothing else on the map is `accent`.
## Complexity budget
Max 6 stages · max 3 content rows · 5 sentiment levels (ordinal, named — never numeric) · max 2 pain markers · max 2 accent elements.
## Anti-patterns
- **No sentiment curve.** If every stage feels the same, or you can't name a feeling, you're drawing a process — use **Process** or **Timeline**.
- **More than 6 stages.** Split into two journeys (e.g. acquisition and retention) rather than cramming a wide funnel into one map.
- **Numeric sentiment axis** (a 0–100 score). Sentiment here is ordinal — five named levels, not a chart of a continuous metric.
- **Emoji as sentiment markers.** Use the named levels and hairlines; emoji don't localize, print, or hold up at small sizes.
- **Multiple personas on one map.** Overlaying two sentiment curves erases both. One map per persona.
- **Pain markers on every stage.** If nothing is un-marked, nothing is focal.
- **`writing-mode` vertical row labels.** Horizontal only, in the left margin — same rule as every other type in this skill.
- **Using it for an internal system flow with no human in it.** No person, no sentiment, no journey map — that's an architecture or data-flow diagram.
## Examples
- `assets/example-journey.html` — minimal light. *Trial to paid: the first week*, 5 stages, trough at "Hit the limit".
- `assets/example-journey-dark.html` — minimal dark, same data.
- `assets/example-journey-full.html` — full editorial: container framing + 3 varied-width summary cards + footer.
## references/type-kanban.md
# Kanban Board
**Best for:** a snapshot of work-in-progress by state — what is queued, what is moving, what is stuck, and where the WIP limit is being breached. This is a *state census*, not a flow: a kanban board has **no connectors at all**. That is exactly what separates it from swimlane (lanes plus a flow crossing them, with handoffs as the load-bearing edges) and from process (ordered steps with directional handoffs). If the diagram needs an arrow anywhere, it isn't a kanban board anymore — reach for swimlane or process instead.
## Layout conventions
- **Up to 5 vertical columns of equal width (240px), 32px gutters.** Column background is `ink @ 0.02`; no column border.
- **Header band per column:** column name in Geist sans 12px weight 600, anchored left. A right-anchored **WIP chip** — a rectangular tag (`rx=2`, **never** a pill) holding `n/limit` in Geist Mono 8px — or bare `n` on a queue or terminal column, which carries no limit. Every in-process column states one. A hairline `rule` separator sits directly under the header band, full column width.
- **Cards:** the §6 node-box pattern at `rx=6`, column width minus 16px padding on each side, 56px tall, 12px vertical gap between cards. Content: title in Geist sans 12px weight 600, and a Geist Mono 9px `muted` sublabel line for `TICKET-ID · owner` (e.g. `AVA-214 · nadia`).
- **Drawing order:** background → column fills → header text + WIP chips → header rules → cards (each: box, then left accent bar if blocked, then title, then sublabel) → legend.
## Card states — the type's semantic vocabulary
Every card renders in exactly one of four states. Document and use all four when the board has enough cards to show them:
| State | Fill | Stroke | Extra |
|---|---|---|---|
| `default` | white | `ink` | — |
| `blocked` | `accent @ 0.05` | `accent` (full opacity) dashed `4,4` | 4px `accent` bar on the card's left edge |
| `waiting / external` | `ink @ 0.02` | `ink @ 0.20` dashed `4,3` | — |
| `done` | `ink @ 0.05` | `muted` | — |
These map directly onto the SKILL.md §5 node-treatment table (`security` → blocked, `optional` → waiting/external, `store` → done) — the board reuses the system's existing semantic fills rather than inventing new ones.
## Over-limit column
When a column's card count `n` exceeds its stated `limit`, the WIP chip's stroke and text go `accent`. That plus one blocked card is the full 2-accent budget for the diagram — don't spend the budget anywhere else.
## Complexity budget
- Max 5 columns, max 4 cards per column, max 12 cards total.
- Max 2 accent elements (the over-limit chip counts as one; a blocked card counts as one).
- Over budget on a single column → aggregate the backlog into one count card (`+14 more`) rather than listing every item.
## Anti-patterns
- **Drawing arrows between cards.** A board shows state, not flow — if the flow itself needs to be visible, use swimlane or process instead.
- **More than 4 cards in a column.** Aggregate into a count card; don't let a column scroll off the canvas.
- **One card per person.** That's an org chart wearing a kanban skin.
- **In-process columns without WIP limits.** The limit is half the point of the type — a column work flows *through* with no stated limit can't show that it's over budget. The entry queue and the terminal column are the exception: nothing is constrained by holding more done work, so they show a bare count.
- **Accenting every blocked card.** One or two blocked cards read as signal; a column full of accent reads as noise and erases the focal rule.
- **A "Done" column that grows without bound.** Cap it and note the archive point in the sublabel or a footnote — an unbounded Done column just becomes a second Backlog.
- **Pill-shaped WIP tags.** The chip is a rectangle at `rx=2`, matching the type-tag primitive in §6 — pills read as status badges from an unrelated design language.
## Examples
- `assets/example-kanban.html` — minimal light. Platform-team board: Backlog (3), In progress (4/3, over limit), Review (2/3), Done (2), one blocked card.
- `assets/example-kanban-dark.html` — minimal dark, same data.
- `assets/example-kanban-full.html` — full editorial: container framing + 3 summary cards of varied widths + footer.
## references/type-layers.md
# Layer Stack
**Best for:** OSI model, CSS cascade, context hierarchy, tech stack, abstraction layers, memory hierarchy.
## Layout conventions
- Horizontal bands stacked vertically. Each layer is a full-width rectangle (same x, same width). 4–6 layers total.
- Layer height 56–72px, width typically 800–880px inside a 1000px viewBox.
- Each row contains (left→right):
1. **Index tag** on the far left (`L3`, `07`, `APPLICATION`) — Geist Mono 8–9px eyebrow.
2. **Layer name** slightly right of center-left — Geist 14–16px 600.
3. **Sublabel / note** on the far right — Geist Mono 9–10px muted.
- Border between layers: 1px hairline `rgba(45,49,66,0.12)`. Outer silhouette 1px ink or muted.
- Fills: either alternating subtle shades (paper / paper-2) OR all paper with hairline dividers. Pick one and hold it.
- Direction indicator on the LEFT margin (outside the stack): small up/down arrow + Geist Mono label (`abstraction ↑`, `packets ↓`).
- Coral on **one** focal layer (stroke + subtle tint fill) — the bottleneck, the pay-rent layer, the one under discussion.
## Anti-patterns
- Layers that aren't actually hierarchical (use swimlane or architecture).
- Skipped numbering (missing L4 between L3 and L5 without explanation).
- Every layer a different color — hierarchy invisible.
- Inconsistent layer heights without reason.
## Examples
- `assets/example-layers.html` — minimal light
- `assets/example-layers-dark.html` — minimal dark
- `assets/example-layers-full.html` — full editorial
## references/type-line.md
# Line Chart
**Best for:** continuous trends over time or a sequential index — signups over weeks, revenue by month, latency over releases. Use when the direction and rate of change between points is the primary message.
## Layout conventions
- **Plot area margins:** left 80px, bottom 60px, top 40px, right 40px — inside `0 0 1000 500` viewBox.
- **Points:** 4–12 data points. Fewer → consider a summary stat; more → aggregate into periods.
- **X-axis:** evenly spaced time/index labels below the plot. Use Geist Mono 8px, centered on each point x.
- **Y-axis gridlines:** 4–6 horizontals at regular intervals. Same faint treatment as bar chart.
- **Lines:** `` with `fill="none"`. Focal series `stroke-width="1.8"`, others `"1.2"`.
- **Vertex dots:** only on the focal series (`r=4`, filled). Other series: line only.
- **Area fill (optional):** `` closing back to `y=420` (x-axis baseline) at 0.08 opacity. Use for the focal series only when the area meaning is important.
- **Multi-series:** up to 5 series. Focal = `accent`. Others = `series-1`, `series-2`, `series-3`, `series-4` from style-guide.md. Apply series palette in order — don't skip.
- **Legend:** horizontal strip at the bottom. Swatch = 16×8px rect with the series fill/stroke. One entry per series.
### Polyline pattern
```svg
BEFORE
AFTER
Recommender
238
431
Recommender
```
Non-focal series: `stroke="rgba(45,49,66,0.68)"` at `stroke-width="1.2"`, dots `r=3`, names at `font-weight="500"`.
What each binding buys, and what it costs to omit:
| Binding | Without it |
|---|---|
| `data-from` / `data-to` on the line | The checker would have to read the labels, and a series whose label went missing would drop silently out of the verified set — the exact hole that let a treemap cell ship 50% oversized. |
| `data-end` on a value label | A printed number could not be cross-checked against the value it claims to state. |
| `data-role="name"` on a name label | Two series names could be exchanged between rows, renaming both lines, with every number still correct in isolation. |
| `data-axis` on a state caption | The captions could be swapped, reversing the direction every slope is read in. |
| `data-state` on a state caption | Swapping just the two visible strings leaves both captions in place and reverses the figure anyway. |
`scripts/verify-slopegraph.py` requires all of them, cross-checks each visible string against its binding, and reports any label drawn nearer another series' endpoint than its own — a label on the wrong row renames the line.
**No `transform` on any of it.** The checker reads raw `x`/`y` attributes, so a `transform` on a series line, on a bound label, on an ancestor ``, or in a CSS rule moves the rendered mark away from the number that was verified — `transform="translate(0 80)"` on one line slid its endpoint 80px past every green check. Transforms are rejected rather than resolved: a partial implementation of the SVG transform stack looks like coverage without being it. Bake the offset into the coordinates. The rotated value-axis caption is fine — it is neither verified geometry nor a bound label.
**Print one complete number per value label.** A unit suffix is fine (`208ms`); a thousands separator that changes the value is not, and neither is a second number in the same label. Reading only the first numeric fragment let the label `512,000` agree with metadata that said `512`.
#### Anti-patterns
- Different scales, different units, or different origins on the two axes — the type's one unforgivable error.
- A value axis whose two halves disagree, or a tight domain the source line never states.
- Moving an endpoint to make room for its label.
- More than 10 series (labels collide) or fewer than 4 (a sentence is shorter).
- Three or more state columns — that is the parent line chart, or a bump chart, not this.
- One hue per series instead of the ink ramp plus a single accent.
- A value label in `accent`, or any text in `soft` (3.48:1 on paper).
- Gridlines, or a value axis that repeats numbers the endpoints already print.
- Annotating the crossing with a date, or reading any intermediate value off a slope.
- A `transform` on a series line, a bound label, an ancestor group, or in CSS — it moves the mark away from the checked coordinate.
- An unbound visible string: a name, a value or a state caption with no attribute stating the same thing.
- Curving the connector. There is nothing between the two points to curve through.
## Examples
- `assets/example-line.html` — minimal light
- `assets/example-line-dark.html` — minimal dark
- `assets/example-line-full.html` — full editorial
- `assets/example-slopegraph.html` — slopegraph, minimal light
- `assets/example-slopegraph-dark.html` — slopegraph, minimal dark
- `assets/example-slopegraph-full.html` — slopegraph, full editorial
## references/type-loop.md
# Loop
**Best for:** reinforcing cycles, flywheels, feedback loops, and operating loops — anything where the last step feeds the first and a shared hub accumulates state. Use Loop when the reader must see both motions at once: work advances clockwise around the ring, while each pass writes durable state back to one common center.
Prefer **Flowchart** when the path ends, branches toward an outcome, or never truly returns to its first step. Prefer **Cycle** when the center does not accumulate shared state. The dashed write-back spokes are the defining signal here: remove them and the figure is only a circular process.
This type is **parametric**. The inputs in §1 determine station count, angles, edge intersections, connector paths, and viewBox bounds. Identical inputs should produce identical geometry.
---
## 1. Inputs — the parameter contract
```yaml
title: "The self-improving loop"
subtitle: "Every pass improves the shared operating record"
hub: # exactly one
name: "Shared memory"
sublabel: "one record, every loop"
stations: # 5..8, clockwise from top
- { name: "Capture", sublabel: "signals in", spoke_label: "SIGNALS" }
- { name: "Research", sublabel: "evidence pulled" }
- { name: "Decide", sublabel: "human approves", focal: true }
- { name: "Act", sublabel: "work ships", spoke_label: "OUTCOMES" }
- { name: "Measure", sublabel: "outcomes logged" }
- { name: "Learn", sublabel: "playbook updated" }
station_w: 160
station_h: 64
hub_w: 200
hub_h: 104
radius: 240
margin: 64
dark: false
```
**Budget (hard):** **5–8 stations plus exactly one hub.** Above 8 stations, split the subject into an overview Loop and one or more detail diagrams. Exactly one hub — a loop with two hubs is two diagrams. At most one station may set `focal: true`; zero is allowed when no editorial gate deserves emphasis.
Station order is semantic. `stations[0]` is the top station, then entries proceed clockwise. The last station always connects back to station 0; if that return would be false, use a Flowchart instead.
---
## 2. Layout math — deterministic geometry
Use SVG coordinates, where positive y points downward. Let the hub center be `C = (cx, cy)`, station count be `N`, station ring radius be `R`, station half-size be `a = station_w/2`, `b = station_h/2`, and hub half-size be `A = hub_w/2`, `B = hub_h/2`.
### 2.1 Station centers
For zero-indexed station `k`:
```text
theta_k = -90deg + k * (360deg / N)
u_k = (cos(theta_k), sin(theta_k))
P_k = C + R * u_k
station_center_x(k) = cx + R * cos(theta_k)
station_center_y(k) = cy + R * sin(theta_k)
station_x(k) = station_center_x(k) - station_w/2
station_y(k) = station_center_y(k) - station_h/2
```
Thus station 1 sits at the top, and increasing `k` moves clockwise. Round station rectangles to the nearest 4px grid point after computing the ideal geometry; preserve symmetry when rounding paired stations. Keep ring-circle intersection points to three decimal places so every arc remains on the same circle.
### 2.2 Solid ring-flow endpoints
Ring connectors travel from station `k` to station `j = (k + 1) mod N` as circular SVG arcs on the station circle itself. Every segment uses the same center `C`, radius `R`, and clockwise sweep. The station boxes interrupt the circle; connectors begin at the circle's clockwise exit from the source box and end just before its counterclockwise entry into the destination box, so the marker tip lands on the destination stroke.
Find the circle/rectangle intersections against all four edges of station `k`. For vertical edge `x = x_e`:
```text
y = cy +/- sqrt(R^2 - (x_e - cx)^2)
```
Keep only candidates whose `y` lies within the edge. For horizontal edge `y = y_e`:
```text
x = cx +/- sqrt(R^2 - (y_e - cy)^2)
```
Keep only candidates whose `x` lies within the edge. The two surviving points are classified by their normalized polar angles around `C`:
```text
q_entry(k) = circle/box intersection immediately before theta_k clockwise
q_exit(k) = circle/box intersection immediately after theta_k clockwise
```
Compensate for the marker tip before emitting the destination endpoint. With the canonical marker (`refX=7`, polygon tip at `x=8`) and ring stroke width `1.2`, `marker_overhang = 1.2`:
```text
phi_entry = atan2(q_entry(j).y - cy, q_entry(j).x - cx)
phi_end = phi_entry - marker_overhang / R
q_end = C + R * (cos(phi_end), sin(phi_end))
M q_exit(k).x q_exit(k).y
A R R 0 0 1 q_end.x q_end.y
```
The large-arc flag is `0` because adjacent-station gaps are less than 180 degrees; the sweep flag is always `1` for clockwise motion in SVG coordinates. The arrowhead overhang completes the final 1.2px to `q_entry(j)`, landing on the box edge without crossing its stroke. The closing connector from station `N-1` to station 0 uses the identical formula.
Loop's circular ring arcs are a documented type-specific exception to SKILL.md §6 rule 1, following the same precedent as Medallion's promotion arcs. A Loop never mixes cubic, straight, or rounded-orthogonal segments into its ring: the six visible gaps must read as pieces of one continuous circle.
### 2.3 Dashed write-back spoke endpoints
Each spoke runs inward from the station edge toward the hub. Use the same ray/box intersection formula, now on the radial vector `u_k`:
```text
box_distance(v, half_w, half_h) = min(half_w / abs(v.x), half_h / abs(v.y))
# ignore a term whose denominator is zero
d_station = box_distance(u_k, a, b)
d_hub = box_distance(u_k, A, B)
marker_gap = 6 # 4..8px; 6px canonical
spoke_start(k) = P_k - d_station * u_k
hub_edge(k) = C + d_hub * u_k
spoke_end(k) = C + (d_hub + marker_gap) * u_k
```
Because the arrow travels from the station toward `C`, adding `marker_gap` leaves the endpoint just outside the hub boundary. The lighter arrowhead stops before the hub stroke instead of colliding with it. Radial spokes are the type-specific exception to the general ban on slanted straight connectors; they must remain true radii, must not cross one another, and may touch only their source station and the hub.
Labels are optional when the station sublabel already names the write-back. When used, they follow the `arrow-label` role, stay to one side of the spoke, and receive an opaque `paper` mask with a visible 6–10px gap from the stroke. Label a curated subset rather than forcing six labels into the hub halo.
### 2.4 ViewBox sizing
The viewBox must include the full station rectangles, outer ring curves, arrowheads, and at least `margin` breathing room:
```text
left <= cx - R - station_w/2 - margin
right >= cx + R + station_w/2 + margin
top <= cy - R - station_h/2 - margin
bottom >= cy + R + station_h/2 + margin
viewBox_w = right - left
viewBox_h = bottom - top
```
Include the full circle extrema `cx +/- R`, `cy +/- R` plus station bounds and marker clearance when checking these limits. Never shrink the canvas until a station stroke, marker, or ring arc clips. For the six-station canonical example, `viewBox="0 0 1040 680"`, `C=(520,340)`, `R=240`, station size `160×64`, and hub size `200×104` leave generous outer clearance.
---
## 3. Visual grammar
| Element | Treatment |
|---|---|
| Station | Standard node: `paper` fill, `ink` stroke, `radius-md`; name in `node-name`, sublabel in `sublabel` |
| Hub | The one dark element: `ink` fill, `paper` text; slightly larger than a station |
| Focal station | At most one: `accent-tint` fill, `accent` stroke; station name may use `accent` |
| Ring flow | Circular `A R R 0 0 1` arcs on the station circle, solid `muted` stroke, default arrowhead at the destination; clockwise only |
| Write-back spoke | Dashed `soft` stroke at reduced emphasis, `stroke-dasharray="5,4"`, with a `soft` arrowhead |
| Spoke label | `arrow-label` role, `soft`, uppercase, paper mask, 6–10px clear of the connector |
Draw in this order: paper or optional dot grid → ring arrows → dashed spokes → spoke-label masks and labels → station boxes → hub → text. The nodes mask microscopic connector overshoot, while every intended endpoint still lands on an edge.
The hub is not a seventh process step. It is accumulated state: memory, standards, evidence, policy, or a shared operating record. Keep its copy to one name plus one short sublabel.
---
## 4. Connector rules (mandatory)
SKILL.md §6 applies in full except for the two Loop-specific connector primitives: circular ring arcs (§2.2) and straight radial spokes (§2.3). Like Medallion's promotion arcs, these replace §6 rule 1 for this diagram type:
- Ring arrows are same-radius circular arcs, solid, and clockwise. Every path uses `A R R 0 0 1`; destination markers land on station edges and no connector ends at a center point.
- Spokes are dashed and point inward. A solid spoke destroys the visual distinction between operating flow and write-back.
- Labels use opaque masks and maintain a visible 6–10px connector gap. Never place text on the stroke.
- No ring connector or spoke may overlap another connector. Ring paths remain outside the hub; spokes occupy distinct radial routes.
- When two spokes must leave the same station edge, fan their attach points by the §6 formula with at least 12px separation. The normal Loop has one spoke per station; use a second only when the semantics cannot be merged.
- If a ring route would cross the hub, increase `R` or split the diagram. Do not thread flow through shared state or substitute an orthogonal route.
---
## 5. Dark variant — token swap
Apply the style-guide inversion rule; do not invent a second palette.
| Role | Light | Dark |
|---|---|---|
| Canvas and station fill | `paper` | dark `paper` |
| Primary text and station stroke | `ink` | inverted `ink` |
| Hub fill / hub text | `ink` / `paper` | inverted `ink` / dark `paper` |
| Ring flow | `muted` | dark `muted` |
| Write-back spokes and labels | `soft` | dark `soft` |
| Focal fill / stroke | `accent-tint` / `accent` | dark `accent-tint` / brighter dark `accent` |
| Rule and dot grid | `rule` | inverted `rule` at the same opacity |
The semantic relationship stays unchanged in dark mode: one `ink`-filled hub, one optional `accent` station, neutral solid ring arrows, and lighter dashed write-backs.
---
## 6. Reproducibility checklist
1. Station count is 5–8 and hub count is exactly one.
2. Station 0 is at `-90deg`; all others use equal `360/N` steps clockwise.
3. Every solid ring arrow connects adjacent stations with `A R R 0 0 1`, using the same `R`; the last returns to the first.
4. Every ring marker lands on a station edge, not its center.
5. Every dashed spoke begins on a station's inner edge and stops `marker_gap` before the hub stroke.
6. Ring connectors stay outside the hub; spokes do not cross or overlap.
7. At most one station uses `accent-tint` + `accent`; the hub alone uses the dark `ink` fill.
8. Spoke labels, if present, use `arrow-label`, an opaque mask, and a 6–10px gap.
9. The viewBox includes station boxes, strokes, curves, markers, and margins without clipping.
---
## 7. Anti-patterns
| Anti-pattern | Why it fails / correction |
|---|---|
| Two hubs | Two accumulated states create two systems. Draw two diagrams. |
| Solid spokes | They look like primary flow and kill the dashed return signal. Use dashed `soft` write-backs. |
| Stations at uneven angles without reason | The ring stops reading as one operating cadence. Use equal `360/N` spacing unless a documented phase grouping requires a deliberate gap. |
| Mixed arc + orthogonal ring segments | The ring becomes a rounded rectangle. Every segment must be a circular arc of the same radius so the ring reads as one continuous circle. |
| Connectors crossing the hub | Flow becomes confused with state. Route the ring outside or enlarge the radius. |
| Accent on multiple stations | The editorial gate disappears. Keep one focal station at most. |
| More than 8 stations | Labels and spokes crowd the hub. Split into overview + detail. |
| A cycle that never actually returns | That is a Flowchart arranged in a circle. Use Flowchart and show the real endpoint. |
---
## 8. Examples
- `assets/example-loop.html` — minimal light: six-station self-improving operating loop.
- `assets/example-loop-dark.html` — the same geometry under the dark token inversion.
- `assets/example-loop-full.html` — editorial page with the flagship loop, three summary cards, and colophon.
## references/type-medallion.md
# Medallion
**Best for:** documenting a multi-tier data-storage layout where each tier is a distinct *quality / access level* of the same dataset — typically raw landing zone, anonymised, staging/cleaned, aggregated business indicators, and cold archive. Used when the reader needs to see at a glance *what each bucket contains*, *who writes it*, *with what tool and format*, and *how data is promoted between tiers*.
Prefer **Process** if the subject is a workflow with role lanes. Prefer **High-Level** if the subject is the cluster architecture rather than the storage tier organisation.
This type is **parametric** — the inputs schema in §1 drives every coordinate via the formulas in §2. Two generations from the same inputs must produce visually identical SVG. The rule shapes mirror `type-process.md` and `type-data-flow.md` so color override, focal rule, and reproducibility checklist read identically across types.
---
## 1. Inputs — the parameter contract
```yaml
title: "Five-Tier Medallion Architecture"
subtitle: "Quarterly survey through Raw → Anonymized → Staging → Aggregated → Archive"
tiers: # 3..6 tier columns, ordered left → right
- { name: "Raw", bucket: "raw-bucket", style: "outer",
fields: { tool: "NiFi · raw write", format: "CSV · Parquet · JSON", writer: "Data Engineer",
example: ["Q1 dump · w/ PII", "verbatim CAPI export"] } }
- { name: "Anonymized", bucket: "anon-bucket", style: "default",
fields: { tool: "Trino INSERT", format: "Iceberg · partitioned", writer: "Data Engineer",
example: ["no name · address", "stable household ID"] } }
- { name: "Staging", bucket: "staging-bucket", style: "default", color: "#c9a23a", # warm yellow — analytical working zone
fields: { tool: "Trino · JupyterHub", format: "Iceberg · cleaned", writer: "Data Scientist",
example: ["weighted records", "harmonised codings"] } }
- { name: "Aggregated", bucket: "aggregated-bucket", style: "focal", focal: true,
fields: { tool: "Trino INSERT · SAS JDBC", format: "Iceberg · indicators", writer: "Data Scientist",
example: ["unemployment rate", "labour participation"] } }
- { name: "Archive", bucket: "archive-bucket", style: "cold",
fields: { tool: "MinIO lifecycle", format: "cold tier · immutable", writer: "Data Administrator",
example: ["historical Q1–Q4 sets", "5+ years retained"] } }
example_label: "Quarterly survey example" # bottom field label (varies per domain)
promotions: # adjacent-tier arrows; len = n_tiers - 1
- { from: 0, to: 1, label: "PII REMOVE", style: "normal" }
- { from: 1, to: 2, label: "CLEAN+WEIGHT", style: "normal" }
- { from: 2, to: 3, label: "AGGREGATE", style: "focal" } # auto-accent because target is focal
- { from: 3, to: 4, label: "LIFECYCLE", style: "lifecycle" } # dashed
paths: # 0..2 write-method cards at the bottom (optional)
- { tag: "SQL PATH", title: "Trino INSERT INTO … SELECT",
sub: "filter · reshape · join · aggregate — set-based transforms" }
- { tag: "NOTEBOOK PATH", title: "DuckDB + Python/R in JupyterHub",
sub: "stats · ML · interactive analysis — row-iterative work" }
dark: false
```
**Reserved field semantics:**
- `tiers[i].style` — one of `outer`, `default`, `focal`, `cold`. Drives the card's fill/stroke palette (§2.4).
- `tiers[i].focal: true` — exactly **one** tier may declare this. Overrides `style` to `focal` and switches the promotion arrow *into* this tier to `focal` automatically.
- `tiers[i].fields` — `{tool, format, writer, example}`. `example` is a 1- or 2-item list; the section heading uses `example_label`.
- `tiers[i].color` — optional `"#hex"` per-tier color override. See §4.
- `promotions[].style` — `normal` | `focal` | `lifecycle`. The connector rule (§3) binds each style to fixed stroke / dash / marker.
- `paths` — 0–2 entries. When 0 entries, the bottom row is omitted and `viewBox_h` shrinks accordingly.
---
## 2. Layout formulas — deterministic geometry
```
# Tier dimensions
tier_w = 172
tier_h = 380
tier_gap = 16
left_pad = 16
right_pad = 100
n_tiers = len(tiers)
# Canvas
viewBox_w = left_pad + n_tiers * tier_w + (n_tiers - 1) * tier_gap + right_pad
# 5 tiers → 16 + 860 + 64 + 100 = 1040
arc_band_h = 80 # space above tiers reserved for promotion arcs
path_h = 56
path_gap = 16 # gap between tier row and path row
bottom_pad = 16
viewBox_h = arc_band_h + tier_h + (path_gap + path_h if paths else 0) + bottom_pad
# with paths → 80+380+72+16 = 548
# without paths → 80+380+16 = 476
# Tier positions
tier_x(i) = left_pad + i * (tier_w + tier_gap) # 16, 204, 392, 580, 768
tier_y = arc_band_h # 80 — tier tops sit just below the arc band
tier_cx(i) = tier_x(i) + tier_w/2 # 102, 290, 478, 666, 854
# Promotion arcs (between adjacent tiers — over the top, anchored at tier top-centers)
arc_src_x(i) = tier_cx(i) # top-center of tier i (102, 290, 478, 666)
arc_dst_x(i) = tier_cx(i+1) # top-center of tier i+1 (290, 478, 666, 854)
arc_peak_x(i) = (arc_src_x(i) + arc_dst_x(i)) / 2 # midpoint (196, 384, 572, 760)
arc_label_y = 50 # label sits inside the arc, 30px below tier top
# Path row (bottom)
path_y = tier_y + tier_h + path_gap # 476
path_w = (viewBox_w - 2*left_pad - path_gap) / 2 if len(paths) == 2 else (viewBox_w - 2*left_pad)
# Canonical 5-tier shape uses path_w=460 explicitly (see §2.5)
```
### 2.1 Background
Solid paper fill across the full viewBox. No dot pattern.
### 2.2 Tier card (172 × 380)
Each tier renders as a rounded-rect card with a tinted header band, a centered bucket name, four labeled field rows, and a separated `example_label` section near the bottom.
```
tier_x(i), tier_y = card top-left (tier_y = 80, just below the arc band)
header_band_h = 40 # band from y=tier_y to y=tier_y+40 (i.e., 80..120)
header_band_extra = 10 # 10-px extension below band, same tint
# Inside the card (absolute y; tier_y = 80):
title_text at (tier_cx(i), 106) # node-name role, 13px, weight 700, ink
bucket_text at (tier_cx(i), 144) # sublabel role, muted (accent on focal tier)
field_x = tier_x(i) + 16 # 16-px left inset for field text
field_w = 140 # 172-px tier_w minus two 16-px insets
field rows (absolute y):
tool_label at 180, tool_value at 186 (foreignObject, height 24)
format_label at 220, format_value at 226 (foreignObject, height 24)
writer_label at 260, writer_value at 266 (foreignObject, height 24)
# gap (open whitespace below writer row, above the example section)
example_label_text at 360, example_line_0 at 374, example_line_1 at 388
```
**Field-value wrapping rule:** field values (tool / format / writer) render inside an SVG `` with an HTML `` so they auto-wrap when text exceeds 140 px. Each `foreignObject` is 140 wide × 24 tall (fits 2 lines in the `sublabel` role at 1.25 line-height). The 26-px gap to the next field's label absorbs the second line cleanly.
```svg
{field_value}
```
The HTML namespace declaration on the `` is required for SVG to render the inline content. Browsers and Playwright/Chromium render this faithfully; if your export target doesn't support `` (some older Inkscape builds), hand-split long values into two `` lines instead.
Field labels use the `node-name` role at 11px in ink. Field values use the `sublabel` role in muted. Bucket and field values can be retinted by `color` override (§4).
### 2.3 Tier styles
Four canonical styles, picked per tier via `tiers[i].style`. Default mapping if `style` is omitted: tier 0 → `outer`, last tier → `cold`, focal tier (if any) → `focal`, others → `default`.
| `style` | Card fill | Card stroke | Header band fill | Bucket text | Example value text |
|---|---|---|---|---|---|
| `outer` | `#FFFFFF` | `muted` 1.0 solid | `muted @ 0.10` | `muted` | `muted` |
| `default` | `#FFFFFF` | `ink` 1.0 solid | `ink @ 0.06` | `muted` | `muted` |
| `focal` | `accent @ 0.07` | `accent` 1.6 solid | `accent @ 0.14` | `accent` | `accent` |
| `cold` | `paper-2` | `muted` 1.0 dashed `5,3` | `muted @ 0.18` | `muted` | `muted` |
`rx = 6` on all card rects.
**Focal styling note:** the focal tier's accent treatment cascades — its bucket text and its example-value lines render in accent. Other field values (tool/format/writer) stay muted; only the bucket name and the example payload carry the focal signal so the tier card doesn't fully drown in coral.
### 2.4 Promotion arcs (over the top of the tiers)
Each promotion is a **cubic Bézier arc** anchored at the **top-center** of each adjacent tier — `(tier_cx(i), tier_y)` to `(tier_cx(i+1), tier_y)`. The arc rises into the 80-px `arc_band` above the cards, peaking at y ≈ 20. Both the connector and its label remain fully visible — no paper masks, no overlap with card content.
```svg
```
Add a new `` for each `color` override used in the diagram. Naming convention: `arrow-{semantic}` (e.g., `arrow-yellow`, `arrow-slate`, `arrow-red`) — matches the recommended palette so the marker id reads cleanly in source.
**Z-order:** promotion arcs draw **before** any tier card rect, so the cards layer on top and any arc overshoot is masked inside the cards.
**Arc shape rule:** medallion promotions are always **cubic arcs over the top** of the tier strip, anchored at the **top-center** of source and target tiers; control points directly above anchors at y=0. No horizontal "through the gap" lines — the arc-over-top is what makes connector + label both clearly visible.
---
## 4. Component color override
Any tier or path entry accepts an optional `color: "#hex"`. Mirrors `type-process.md` §4 / `type-data-flow.md` §4.
### 4.1 Per-tier `color`
Applied to:
| Element | Light | Dark |
|---|---|---|
| Card fill | `rgba(C, 0.07)` | `rgba(C_light, 0.10)` |
| Card stroke | `C` (width 1.4) | `C_light` (width 1.4) |
| Header band fill | `rgba(C, 0.14)` | `rgba(C_light, 0.18)` |
| Title text | ink (unchanged — title stays readable) | ink (unchanged) |
| Bucket text | `C` | `C_light` |
| Example values | `C` | `C_light` |
| Field labels / field values | **unchanged** (ink / muted) | **unchanged** |
| Connectors touching this tier | **unchanged** — topology-driven | **unchanged** |
`C_light` = the same hex lightened ~15% for dark-mode contrast.
### 4.2 Per-path `color`
Replaces the path card's stroke with `rgba(C, 0.45)` and the tag chip stroke with `rgba(C, 0.55)`. Tag text and title text use `C`. Sub stays muted.
### 4.3 Rules
- **Never on focal tiers.** The accent already carries that signal — a `color` on the focal tier is ignored.
- **Never on the `cold` tier in addition to its dashed treatment.** Pick either dashed-cold or a custom color, not both.
- **Cap at 2 custom-colored elements** per diagram (tier or path), in addition to the focal tier.
- **Promotion arrows inherit the target tier's color** (§3 auto-style rule). A `color: "#c9a23a"` on the Staging tier means the CLEAN+WEIGHT arc landing in Staging is also rendered in yellow — connector, label, and arrowhead match. This keeps visual coherence: the colored tier and its incoming flow read as a single "concern" group. Arrows do **not** inherit color from the source tier — only the target — so the arc *out of* a colored tier reverts to muted (or to the next target's color/style).
### 4.4 Semantic palette (recommended)
Same palette as the other parametric types so a reader scanning multiple diagrams sees the same colors meaning the same thing:
- `#b85450` rust-red — Security / Identity / Governance (PII-bearing tiers, audit tiers)
- `#5a7d9a` slate-blue — Observability / Quality (validated tiers, monitored zones)
- `#7a8c47` olive-green — Data Products / Publication (consumer-facing aggregates, public-release tiers)
- `#c9a23a` warm yellow / gold — Analytical / Working zones (staging tier, scientist sandbox, intermediate computation surface)
- `#8c6d3f` warm-brown — Backup / DR / Archive (alternative cold-tier styling)
---
## 5. Focal rule
Exactly **one** focal tier per diagram. Defaults to the tier marked `focal: true` in inputs; if none is marked, defaults to the analytical pivot tier (typically `Aggregated` or whichever tier downstream consumers query).
The focal tier:
- Uses `style: focal` (accent fill + stroke 1.6 + accent header band).
- Renders bucket text and example-value lines in accent.
- Has its **incoming** promotion arrow auto-promoted to `style: focal` (accent).
- Has its **outgoing** promotion arrow (if any) — typically into the cold archive — kept at the user-declared style (usually `lifecycle` dashed).
If zero or >1 tiers carry `focal: true`, halt and ask the user.
---
## 6. Dark mode
| Token | Light | Dark |
|---|---|---|
| Paper | `paper` | `ink` |
| Ink | `ink` | `paper` |
| Muted | `muted` | `soft` |
| Accent | `accent` | `accent` |
| Fog (cold tier fill) | `paper-2` | `paper @ 0.06` |
| White (default card fill) | `#FFFFFF` | `paper @ 0.04` |
| Card stroke ink (default style) | `ink` | `paper @ 0.30` |
| Header band ink-tint | `ink @ 0.06` | `paper @ 0.08` |
| Header band muted-tint | `muted @ 0.10` | `soft @ 0.16` |
| Header band cold-tint | `muted @ 0.18` | `soft @ 0.24` |
| Header band accent-tint | `accent @ 0.14` | `accent @ 0.20` |
| Custom component colors | `C` | `C_light` (lighten ~15%) |
---
## 7. Reproducibility checklist (taste gate)
Before emitting SVG, verify **every** item:
1. `viewBox = "0 0 {viewBox_w} {viewBox_h}"` derived via §2 (5 tiers + 2 paths → 1040 × 548).
2. Each tier card at `(tier_x(i), 80)` size `172 × 380`, `rx=6`.
3. Tier header band fills `(tier_x(i), 80, 172, 40)` plus a 10-px extension under the band.
4. Exactly **one** focal tier; its incoming arc auto-styled to `focal`.
5. Promotion arcs render as cubic Béziers over the top of adjacent tiers; anchors at `(tier_cx(i), 80)` → `(tier_cx(i+1), 80)`, controls at y=0. Label inside the arc at `(arc_peak_x, 50)`, no mask.
6. Bottom path row only present when `len(paths) > 0`. Cards at `y=476`, height 56.
7. Custom component colors ≤ 2 in addition to the focal tier. Never on arrows.
8. All promotion arrows + label masks emitted **before** any tier rect (z-order rule — cards mask the line ends inside the cards).
9. The focal tier's bucket text and example values render in accent; the rest stay muted.
10. `rx=6` on every tier and path card; `rx=2` on tag chips.
---
## 8. Anti-patterns
- **More than one focal tier** — focal exists to mark the central analytical surface; >1 erases the signal.
- **Cold styling on a non-archive tier** — the dashed fog look is reserved for retention/archive tiers.
- **Bidirectional promotion arrows** — promotions always flow left → right. Backflow (e.g., an aggregate writing back to raw) is wrong for this type; use a different diagram.
- **Custom-colored arrows** — connectors are topology-driven; color on a tier never spreads to its edges.
- **Path cards explaining tier semantics** — paths describe *write methods* (how data moves between tiers), not what each tier holds. If you find yourself writing "Raw stores …" in a path card, that content belongs in the Raw tier's fields.
- **Missing `example_label` content** — every tier should show a concrete example payload (quarterly survey rows, customer records, claims, …). Without it the diagram becomes abstract and stops earning its space.
- **Promotion arrow label longer than the tier-gap label mask** — keep labels to ≤ 14 chars in the uppercase `arrow-label` role. Long verbs ("CALCULATE & SUMMARIZE") break the rhythm; shorten to "AGGREGATE" or split into two diagrams.
---
## 9. Examples
- `assets/example-medallion.html` — minimal light (NatStat quarterly survey: 5 tiers, 2 path cards, Aggregated focal). Gallery default.
- `assets/example-medallion-dark.html` — same, dark skin.
- `assets/example-medallion-full.html` — same, editorial-card frame with subtitle + summary cards.
---
## 10. Worked YAML
The YAML in §1 is the **complete** inputs definition for the shipped `example-medallion.html`. Every coordinate in that file's SVG is derivable from §2 applied to those inputs. The same YAML is embedded as a top-of-file HTML comment inside `example-medallion.html` so source view shows the parametric inputs immediately above the SVG.
## references/type-nested.md
# Nested Containment
**Best for:** hierarchy through containment — scope boundaries, CLAUDE.md cascade, trust zones, folder nesting, blast radius. Outer = broader, inner = more specific.
## Layout conventions
- 3–5 rounded rectangles (`rx=8`), nested with consistent inset padding (24–32px horizontal, 32–36px vertical recommended).
- Each level labeled at the top-left in Geist Mono eyebrow style (7–8px, letter-spacing 0.14em). Labels sit on a paper-colored mask rect over the ring's top border.
- Stroke hierarchy: outer rings faint (`rgba(..,0.30–0.45)`), progressing to muted, to ink, to coral at the innermost focal.
- Fills step up in opacity from outer to inner: `rgba(..,0.015)` → `rgba(..,0.025)` → accent-tint on the innermost.
- Optional file-icon glyph (folded-corner rect) inside each level hints at scope content.
- Italic Instrument Serif callouts (see `references/primitive-annotation.md`) — 1–2 max.
## Anti-patterns
- More than 6 levels (information disappears inward).
- Irregular padding between levels — unaligned nesting looks accidental.
- Content inside rings that isn't part of the hierarchy — use a sibling diagram.
- Coral on multiple levels — hierarchy collapses.
## Examples
- `assets/example-nested.html` — minimal light
- `assets/example-nested-dark.html` — minimal dark
- `assets/example-nested-full.html` — full editorial
## references/type-org-chart.md
# Org Chart / Responsibility Map
**Best for:** human teams, agent teams, support escalation maps, role ownership, routing maps, and any hierarchy where the reader needs to know *who owns what* rather than just parent → child structure.
Use **Org Chart** instead of **Tree** when the nodes are people, agents, teams, roles, or accountable owners. A tree shows generic hierarchy. An org chart shows responsibility, invocation paths, and coverage gaps.
## Layout conventions
- Root owner or front door at top center. Use one coral focal node for the person/team/agent that receives ambiguous work.
- Tier 1 nodes are departments, pods, queues, or primary routing buckets. Keep them horizontally aligned.
- Tier 2 nodes are responsible owners or specialists. If there are more than 8 specialists, group them under pod nodes instead of making one giant row.
- Use orthogonal connectors: vertical drop from parent → horizontal bus → vertical drops to children. No diagonal lines.
- Each node should answer three questions when space allows:
1. **Name** — human-readable role/person/agent in Geist sans.
2. **How to invoke** — Slack handle, queue, issue prefix, or trigger in Geist Mono.
3. **Scope** — 2–4 terse ownership words, not a paragraph.
- Show non-Slack / not-yet-live owners with dashed optional styling rather than hiding them. Missing routes are operationally important.
- Put escalation / approval rules in a small side callout or footer strip, not as extra org nodes.
## Node treatments
- **Front door / command center:** focal treatment (`accent-tint` + `accent`).
- **Team / pod / department:** backend treatment (white + `ink`).
- **Individual agent / owner:** store or external treatment depending on whether it is active in the system.
- **Gap / needs setup:** optional dashed treatment.
- **Approval gate:** security treatment, separate from reporting hierarchy.
## Complexity budget
- Max visible org nodes: 12. If more, create an overview org chart plus separate detail charts per pod.
- Max depth: 4 tiers.
- Max direct reports under one parent: 5. If there are more, introduce grouping nodes.
- Max coral nodes: 1. The org chart's job is clarity, not highlighting everything.
- Max side callouts: 2.
## Anti-patterns
- Using a swimlane when the user's real question is "who does what?" Swimlanes explain process; org charts explain ownership.
- Drawing every person/agent as an identical box. It hides the front door, specialists, gaps, and escalation paths.
- Cramming full job descriptions into nodes. Keep scope phrases short and move detail to summary cards below.
- Showing unavailable / not-yet-wired agents as normal active owners. Use dashed optional styling so gaps are visible.
- Repeating Slack handles in body paragraphs when a node sublabel can carry the invocation path.
- Floating legends in the org area. Use the standard bottom legend strip.
## Examples
- `assets/example-org-chart.html` — minimal light
- `assets/example-org-chart-dark.html` — minimal dark
- `assets/example-org-chart-full.html` — full editorial
## references/type-polar.md
# Polar Chart
**Best for:** one quantitative series across 4–8 categories whose clockwise order is meaningful.
## Input contract
```yaml
title: "Request demand by UTC window"
unit: "% of daily peak"
scale:
min: 0
max: 100
categories:
- { label: "00–03", value: 32 }
- { label: "03–06", value: 18 }
- { label: "06–09", value: 24 }
- { label: "09–12", value: 58 }
- { label: "12–15", value: 100, focal: true }
- { label: "15–18", value: 82 }
- { label: "18–21", value: 76 }
- { label: "21–24", value: 45 }
start_angle: -90
clockwise: true
source_note: "Illustrative normalized workload profile"
```
Validation rules:
1. `scale.min` is exactly `0`; truncated radial scales are invalid.
2. `scale.max` is finite and greater than `0`.
3. Every value is finite and satisfies `0 <= value <= scale.max`.
4. Category labels are unique after trimming and category count is 4–8.
5. At most one category is focal.
6. Categories retain input order; sorting by value would destroy circular meaning.
Missing values are out of scope for the first version. The agent must stop and ask whether to omit the category or supply a value; it must not coerce missing data to zero.
## Quantitative encoding
For category `i` of `N`, value `v`, center `(cx, cy)`, and outer radius `R`:
```text
theta_i = start_angle + clockwise_sign * 2π * i / N
radius_i = R * v / scale.max
x_i = cx + radius_i * cos(theta_i)
y_i = cy + radius_i * sin(theta_i)
```
Angles are expressed in radians for calculation; `start_angle` is supplied in degrees and defaults to `-90`, placing the first category at twelve o'clock. `clockwise_sign` is `+1` for the default clockwise order and `-1` otherwise.
The value ray is the line segment from `(cx, cy)` to `(x_i, y_i)`. Its visible length is exactly proportional to `v`. Endpoint circles have constant radius and encode no additional quantity. No filled sector may sit behind or beneath a value ray, because its area would compete with the declared radius encoding.
The element carrying `data-polar-chart` must be the chart's root `