geneseed 4.28.0 → 4.30.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +58 -0
- package/README.md +4 -2
- package/SHIPPED.md +2 -2
- package/adapters/bob/README.md +1 -1
- package/adapters/claude-code/README.md +4 -2
- package/adapters/opencode/HOW-OPENCODE-LOADS.md +2 -2
- package/adapters/opencode/README.md +18 -2
- package/adapters/opencode/plugins/geneseed-activity.js +22 -20
- package/adapters/opencode/plugins/geneseed-context.js +155 -18
- package/adapters/opencode/plugins/geneseed-guard.js +59 -8
- package/adapters/opencode/plugins/geneseed-workflow.js +18 -1
- package/adapters/opencode/workflows/_runtime.js +14 -3
- package/docs/concepts/enforcement-table.md +5 -4
- package/docs/concepts/exclusions.md +3 -3
- package/docs/concepts/hooks.md +12 -4
- package/docs/concepts/ownership.md +9 -8
- package/docs/concepts/skills.md +1 -0
- package/docs/guides/set-up-ownership.md +22 -6
- package/docs/reference/environment.md +1 -0
- package/docs/reference/plugin-activity.md +1 -1
- package/docs/reference/plugin-context.md +3 -1
- package/docs/reference/plugin-guard.md +1 -1
- package/docs/understand/enforced-vs-asked.md +3 -3
- package/docs/understand/machine-bob.md +1 -1
- package/docs/understand/machine-claude.md +1 -1
- package/docs/understand/machine-opencode.md +1 -1
- package/harness.config.json +1 -1
- package/js/README.md +3 -1
- package/js/build/driver.mjs +29 -9
- package/js/build/emit-opencode.mjs +12 -10
- package/js/build/render.mjs +9 -0
- package/js/hosts/done-checks.mjs +134 -0
- package/js/hosts/geneseed-dir.mjs +116 -0
- package/js/hosts/hooks-context.mjs +19 -0
- package/js/hosts/hooks-done.mjs +82 -38
- package/js/hosts/hooks-learn.mjs +9 -2
- package/js/hosts/hooks-prims.mjs +4 -0
- package/js/hosts/hooks.mjs +139 -6
- package/js/hosts/hosts.mjs +6 -0
- package/js/hosts/native.mjs +1 -1
- package/js/hosts/owned.mjs +19 -0
- package/js/hosts/ownership-gate.mjs +64 -10
- package/js/hosts/settings.mjs +115 -74
- package/js/inspect/checks-constitution.mjs +5 -1
- package/js/inspect/cost.mjs +1 -1
- package/js/inspect/doctor.mjs +2 -1
- package/js/inspect/inventory.mjs +1 -1
- package/js/inspect/status.mjs +2 -1
- package/js/inspect/validate.mjs +2 -1
- package/js/lib/json.mjs +70 -0
- package/js/maintain/uninstall.mjs +18 -5
- package/js/web/gates-api.mjs +2 -2
- package/package.json +1 -1
- package/registry.json +14 -0
- package/src/AGENT.md.tmpl +2 -2
- package/src/licenses/i-have-adhd.txt +21 -0
- package/src/skills/_checkpoints.md +28 -5
- package/src/skills/adhd.md +40 -0
- package/src/skills/diagram-design/LICENSE +21 -0
- package/src/skills/diagram-design/SKILL.md +392 -0
- package/src/skills/diagram-design/THIRD_PARTY_LICENSES.md +134 -0
- package/src/skills/diagram-design/VENDOR.md +81 -0
- package/src/skills/diagram-design/assets/example-architecture.html +183 -0
- package/src/skills/diagram-design/assets/example-venn.html +110 -0
- package/src/skills/diagram-design/assets/template-dark.html +99 -0
- package/src/skills/diagram-design/assets/template-full.html +421 -0
- package/src/skills/diagram-design/assets/template-motion.html +448 -0
- package/src/skills/diagram-design/assets/template-terminal.html +188 -0
- package/src/skills/diagram-design/assets/template.html +100 -0
- package/src/skills/diagram-design/references/animation.md +135 -0
- package/src/skills/diagram-design/references/layout-budget.md +97 -0
- package/src/skills/diagram-design/references/onboarding.md +368 -0
- package/src/skills/diagram-design/references/output-spec.md +277 -0
- package/src/skills/diagram-design/references/primitive-annotation.md +36 -0
- package/src/skills/diagram-design/references/primitive-icons.md +782 -0
- package/src/skills/diagram-design/references/primitive-sketchy.md +43 -0
- package/src/skills/diagram-design/references/primitive-terminal.md +76 -0
- package/src/skills/diagram-design/references/primitives-core.md +144 -0
- package/src/skills/diagram-design/references/profiles.md +183 -0
- package/src/skills/diagram-design/references/semantic-patterns.md +154 -0
- package/src/skills/diagram-design/references/style-guide.md +232 -0
- package/src/skills/diagram-design/references/type-architecture-delta.md +143 -0
- package/src/skills/diagram-design/references/type-architecture.md +117 -0
- package/src/skills/diagram-design/references/type-axonometric-plan.md +83 -0
- package/src/skills/diagram-design/references/type-bar.md +108 -0
- package/src/skills/diagram-design/references/type-data-flow.md +371 -0
- package/src/skills/diagram-design/references/type-db-schema.md +48 -0
- package/src/skills/diagram-design/references/type-dependency.md +44 -0
- package/src/skills/diagram-design/references/type-deployment.md +45 -0
- package/src/skills/diagram-design/references/type-dp-integration.md +407 -0
- package/src/skills/diagram-design/references/type-dp-security-matrix.md +379 -0
- package/src/skills/diagram-design/references/type-er.md +25 -0
- package/src/skills/diagram-design/references/type-exploded.md +115 -0
- package/src/skills/diagram-design/references/type-fishbone.md +75 -0
- package/src/skills/diagram-design/references/type-flowchart.md +23 -0
- package/src/skills/diagram-design/references/type-gantt.md +45 -0
- package/src/skills/diagram-design/references/type-heatmap.md +80 -0
- package/src/skills/diagram-design/references/type-high-level.md +470 -0
- package/src/skills/diagram-design/references/type-it-state.md +468 -0
- package/src/skills/diagram-design/references/type-journey.md +55 -0
- package/src/skills/diagram-design/references/type-kanban.md +49 -0
- package/src/skills/diagram-design/references/type-layers.md +26 -0
- package/src/skills/diagram-design/references/type-line.md +337 -0
- package/src/skills/diagram-design/references/type-loop.md +223 -0
- package/src/skills/diagram-design/references/type-medallion.md +356 -0
- package/src/skills/diagram-design/references/type-nested.md +22 -0
- package/src/skills/diagram-design/references/type-org-chart.md +44 -0
- package/src/skills/diagram-design/references/type-polar.md +136 -0
- package/src/skills/diagram-design/references/type-process.md +490 -0
- package/src/skills/diagram-design/references/type-pyramid.md +33 -0
- package/src/skills/diagram-design/references/type-quadrant.md +81 -0
- package/src/skills/diagram-design/references/type-radar.md +82 -0
- package/src/skills/diagram-design/references/type-sankey.md +75 -0
- package/src/skills/diagram-design/references/type-scatter.md +276 -0
- package/src/skills/diagram-design/references/type-sequence.md +130 -0
- package/src/skills/diagram-design/references/type-service-blueprint.md +103 -0
- package/src/skills/diagram-design/references/type-state.md +30 -0
- package/src/skills/diagram-design/references/type-story-map.md +46 -0
- package/src/skills/diagram-design/references/type-swimlane.md +22 -0
- package/src/skills/diagram-design/references/type-timeline.md +20 -0
- package/src/skills/diagram-design/references/type-tree.md +24 -0
- package/src/skills/diagram-design/references/type-treemap.md +137 -0
- package/src/skills/diagram-design/references/type-uml-class.md +65 -0
- package/src/skills/diagram-design/references/type-venn.md +26 -0
- package/src/skills/diagram-design/references/type-wardley.md +39 -0
- package/src/skills/diagram-design/references/type-waterfall.md +75 -0
- package/src/skills/document-project.md +4 -1
- package/src/skills/learn-mode.md +11 -11
- package/src/skills/ownership.md +41 -18
- package/src/upstreams.json +14 -0
- package/themes/_TEMPLATE.json +1 -0
- package/themes/biker.json +1 -0
- package/themes/commentator.json +1 -0
- package/themes/cyberpunk.json +1 -0
- package/themes/gamer.json +1 -0
- package/themes/imperial.json +1 -0
- package/themes/joker.json +1 -0
- package/themes/marvin.json +1 -0
- package/themes/mean.json +1 -0
- package/themes/military.json +1 -0
- package/themes/neutral.json +1 -0
- package/themes/pirate.json +1 -0
- package/themes/sports.json +1 -0
- package/themes/verstappen.json +1 -0
- package/themes/wizard.json +1 -0
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Bar / Column Chart
|
|
2
|
+
|
|
3
|
+
**Best for:** comparing discrete quantities across categories or time intervals — sprint velocity, monthly revenue, feature adoption, cohort counts. Use when each category has a single numeric value and the comparison between bars is the primary message — or, in the dumbbell variant below, exactly two values whose difference is the message.
|
|
4
|
+
|
|
5
|
+
## Layout conventions
|
|
6
|
+
|
|
7
|
+
- **Orientation:** Vertical bars (columns) are default. Horizontal bars are appropriate when category labels are long or you have more than 8 categories.
|
|
8
|
+
- **Plot area margins:** left 80px (y-axis labels), bottom 60px (x-axis labels), top 40px, right 40px — inside a `0 0 1000 500` viewBox.
|
|
9
|
+
- **Bar count cap:** 4–8 bars. More than 8 → group into periods or split into two charts.
|
|
10
|
+
- **Bar width:** ≥ 50% of the column pitch (the gap should never exceed the bar). Typical: pitch=110px, bar=72px.
|
|
11
|
+
- **Y-axis gridlines:** 4–6 horizontal lines at regular intervals. Stroke `ink @ 0.08` (very faint), 0.8px. X-axis baseline at `ink @ 0.25`, 1px.
|
|
12
|
+
- **Y-axis labels:** right-aligned `arrow-label` role 8px in `muted`, at x=72 (8px left of the plot area).
|
|
13
|
+
- **X-axis labels:** centered below each bar, `node-name` role 11px 600 for category names.
|
|
14
|
+
- **Value labels:** `arrow-label` role 8px above each bar. Focal bar label in `accent`; others in `muted`.
|
|
15
|
+
- **Focal bar:** 1 bar max in accent fill/stroke. All others in `muted @ 0.15` fill + `muted` stroke.
|
|
16
|
+
- **Y-axis line:** thin vertical `<line>` at x=80 from y=40 to y=420.
|
|
17
|
+
|
|
18
|
+
### Bar element pattern
|
|
19
|
+
|
|
20
|
+
```svg
|
|
21
|
+
<!-- Opaque paper mask prevents bleed from background -->
|
|
22
|
+
<rect x="X" y="Y" width="W" height="H" fill="{paper}"/>
|
|
23
|
+
<!-- Bar body -->
|
|
24
|
+
<rect x="X" y="Y" width="W" height="H" fill="{muted @ 0.15}" stroke="{muted}" stroke-width="1"/>
|
|
25
|
+
<!-- Value label above bar -->
|
|
26
|
+
<text x="X+W/2" y="Y-8" fill="{muted}" font-size="8" font-family="{arrow-label}" text-anchor="middle">VALUE</text>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Focal bar: replace fill with `accent @ 0.12`, stroke with `accent`, label fill with `accent`.
|
|
30
|
+
|
|
31
|
+
## Anti-patterns
|
|
32
|
+
|
|
33
|
+
- More than 8 bars without grouping (illegible at normal scale).
|
|
34
|
+
- Truncated y-axis (not starting at 0) — distorts the magnitude comparison.
|
|
35
|
+
- Accent on more than 1 bar ("everything is important" = nothing is).
|
|
36
|
+
- 3-D bar extrusion — no shadows, no depth.
|
|
37
|
+
- Category labels rotated more than 45°; prefer short labels or horizontal chart instead.
|
|
38
|
+
|
|
39
|
+
## Variants
|
|
40
|
+
|
|
41
|
+
- **Grouped bars:** two bars per category, side by side. Use `accent` for the primary series and `series-1` for the secondary. Max 2 groups.
|
|
42
|
+
- **Stacked bars:** segments stacked to total. Use `accent` for the focal segment; muted tints for others. Document the total at the top of each stack.
|
|
43
|
+
- **Dumbbell:** one row per category, two dots on a single shared horizontal scale joined by a hairline. Use it for a two-state comparison where the *distance* between the ends is the message — before/after, two cohorts, target vs actual. Two series only; a third dot makes the connector meaningless and the figure is a dot plot.
|
|
44
|
+
|
|
45
|
+
### Dumbbell layout
|
|
46
|
+
|
|
47
|
+
- **Orientation:** horizontal only. Rows stack downward and the value axis runs left → right; a vertical dumbbell forces rotated category labels.
|
|
48
|
+
- **Plot area:** left margin 200px for row labels — this replaces the 80px margin above — so `x` 200→960, `y` 40→420 inside `0 0 1000 500`. Row labels right-aligned at x=188, `node-name` role 11px 600 `ink` (the category-label size this type already uses).
|
|
49
|
+
- **Rows:** the 4–8 bar count cap applies. Pitch and origin are fixed per row count so the block stays inside the plot band — a 64px pitch from y=96 overflows y=420 at seven rows:
|
|
50
|
+
|
|
51
|
+
| rows | pitch | first row `y` | last row `y` |
|
|
52
|
+
| --- | --- | --- | --- |
|
|
53
|
+
| 4 | 88 | 96 | 360 |
|
|
54
|
+
| 5 | 64 | 96 | 352 |
|
|
55
|
+
| 6 | 64 | 76 | 396 |
|
|
56
|
+
| 7 | 52 | 72 | 384 |
|
|
57
|
+
| 8 | 48 | 68 | 404 |
|
|
58
|
+
|
|
59
|
+
- **Gridlines:** vertical at each tick, `ink @ 0.08` 0.8px, spanning y 56→408. At the domain floor the axis line replaces the gridline rather than doubling it: `ink @ 0.25` 1px, y 40→420.
|
|
60
|
+
- **Tick labels:** centered under each gridline at y=440, `arrow-label` role 8px `muted`.
|
|
61
|
+
- **Axis title:** the value axis carries the family's axis label — `eyebrow` role 7px `muted`, `letter-spacing="0.14em"`, centered at x=580, y=456, below the tick labels and clear of the legend rule. A horizontal axis takes the un-rotated form the scatter x-axis uses, not the `rotate(-90 24 230)` form the column charts apply to their y-axis. The category axis needs no title: the row labels name themselves.
|
|
62
|
+
- **Dots:** r=6, positioned by value. Style by *series*: the reference end hollow (paper fill, `muted` stroke 1.5px), the focal end solid `accent` with a 1px `ink` stroke. Both marks therefore have a boundary above 3:1 even though the accent fill is not — see below. Fill weight, not hue, carries the pairing.
|
|
63
|
+
- **Accent marks the series, not a focal row.** The solid dot repeats on every row — the one place this variant departs from the one-accent rule above, because the two ends must be told apart in each pair. Do not additionally accent a "most changed" row; the sort order already carries rank.
|
|
64
|
+
- **Connector:** `ink @ 0.55` 1px (`rgba(45,49,66,0.55)` under the default light skin, the value `scripts/verify-dumbbell.py` checks), declared before both dots so the dots cap it. It is not the axis hairline: the connector is what says *these two dots are one row*, so it has to clear 3:1 (0.55 gives 3.19:1; the 0.25 the axis uses gives 1.60:1).
|
|
65
|
+
- **Endpoint positions round, they never snap.** `x = 200 + (v − floor) ÷ (ceil − floor) × 760`, with `floor` and `ceil` set by the axis rule below, rounded to the nearest integer pixel — at most 0.5px, below one rendered pixel. Data coordinates are exempt from the 4px grid; snapping them moves the data.
|
|
66
|
+
- **Value labels sit outside the pair, placed by geometry rather than by series.** A focal value *below* its reference reverses the dots, so derive `x_left = min(x_ref, x_focal)` and `x_right = max(x_ref, x_focal)`: left label right-anchored at `x_left − 12`, right label left-anchored at `x_right + 12`, both baseline `y + 4`, `arrow-label` role 8px `muted`, each still carrying its own series' value. Keying the offsets to start/end instead puts both labels *inside* the pair on every decreasing row.
|
|
67
|
+
- **Floor exception.** A value sitting on the domain floor lands its label at x=188, right-anchored on baseline `y + 4` — exactly the category label's anchor and baseline, so the two texts overlap. When `x_left − 12 < 200`, centre that label above its dot at baseline `y − 10` instead.
|
|
68
|
+
- **Legend:** two keys on the legend row — hollow dot, then solid dot, each with its series name. Circular keys centre at `cy=493`, the centre of the bar legend's 10px key rect at y=488, so both sit on the 497 text baseline. The row order goes in the legend or the source line, right-aligned on the same row.
|
|
69
|
+
|
|
70
|
+
**Why the dots differ by fill, not hue.** The focal bar pattern above (12% tint + accent stroke) does not transfer to a 6px dot: the 12% tint across a 6px-radius disc contributes roughly 14 square pixels of colour, so the mark reads as its stroke alone and the pair separates by hue only. A solid accent dot against a hollow one separates by shape, survives greyscale and colour-vision deficiency, and leaves hue as redundant encoding.
|
|
71
|
+
|
|
72
|
+
**Non-text contrast: the boundary carries it, not the fill.** The default accent clears the 3:1 WCAG 1.4.11 asks of a graphical object (4.71:1 on light paper, 5.21:1 on dark), but an onboarded accent may not, and shape redundancy does not waive that floor, because the reader still has to see the mark's edge and the line joining the pair. So neither is left to the accent: the solid endpoint takes a 1px `ink` stroke (11.82:1 against paper) and the connector takes 55% ink on light, 40% on dark (3.19:1 and 3.24:1). The hollow end already cleared it via its `muted` stroke at 6.11:1 light and 7.07:1 dark. `scripts/verify-dumbbell.py` asserts all four, so a later tint change cannot quietly drop one under the line. The hollow/solid shape difference stays as redundant encoding for greyscale and colour-vision deficiency — do not collapse the two dots to a single fill.
|
|
73
|
+
|
|
74
|
+
**Minimum drawn gap — never clamp it.** Both dots carry `r="6"`; the hollow one paints out to 6.75 because its 1.5px stroke straddles the path, so the marks touch at 12.75px of centre separation and below about 16px the pair reads as one blob — on a 0–100 domain across 760px, a data gap of 2.1 units. Do **not** widen the separation to clear it: moving a dot off its scaled position breaks the shared-scale rule below. Keep the true positions and shrink both marks (r=4 touches at 8.75px), or print the two values and mark the row as too close to resolve.
|
|
75
|
+
|
|
76
|
+
### Dumbbell element pattern
|
|
77
|
+
|
|
78
|
+
```svg
|
|
79
|
+
<!-- One row. Connector first so the dots cap it; labels outside the pair. -->
|
|
80
|
+
<line x1="458" y1="96" x2="740" y2="96" stroke="{ink @ 0.55}" stroke-width="1"/>
|
|
81
|
+
<circle cx="458" cy="96" r="6" fill="{paper}" stroke="{muted}" stroke-width="1.5"/>
|
|
82
|
+
<circle cx="740" cy="96" r="6" fill="{accent}" stroke="{ink}" stroke-width="1"/>
|
|
83
|
+
<text x="446" y="100" fill="{muted}" font-size="8" font-family="{arrow-label}" text-anchor="end">34</text>
|
|
84
|
+
<text x="752" y="100" fill="{muted}" font-size="8" font-family="{arrow-label}">71</text>
|
|
85
|
+
<text x="188" y="100" fill="{ink}" font-size="11" font-weight="600" font-family="{node-name}" text-anchor="end">Platform</text>
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Values 34 and 71 on a 0–100 domain compute to 458.4 and 739.6, rounded to 458 and 740. Had this row fallen instead, the accent dot would sit on the left; the two anchors stay tied to left and right, and each label carries its own series' value.
|
|
89
|
+
|
|
90
|
+
**Dark theme.** Dots and labels keep their roles and take the dark column of [`style-guide.md`](style-guide.md): hollow `paper` fill with a `muted` stroke, solid `accent` with an `ink` stroke, labels `muted`. **The hairline opacities change too:** gridlines `ink @ 0.08`, axis `ink @ 0.20`, connector `ink @ 0.40` (`rgba(245,245,245,0.40)` under the default dark skin). The connector stays heavier than the axis, for the same 3:1 reason. Resolve `ink` against the dark column, never the light one: in the default skin light `ink` *is* dark `paper`, so a connector, gridline, or axis carried over from light composites to exactly 1.000:1 and the gap encoding and the scale both vanish.
|
|
91
|
+
|
|
92
|
+
### Dumbbell honesty rules
|
|
93
|
+
|
|
94
|
+
- **Never truncate the value axis.** `floor` and `ceil` follow the data's range, never its observed extremes — taking `min` and `max` as the bounds *is* the truncation. With `lo` and `hi` the smallest and largest values, the four cases are exhaustive: `lo >= 0` anchors `floor = 0` and rounds `ceil` up past `hi` (including fractional data smaller than a fixed absolute tolerance); `hi <= 0` anchors `ceil = 0` and rounds `floor` down past `lo`; `lo < 0 < hi` brackets both sides, and zero then falls inside the plot — give it a line at its scaled position in the axis-line weight, since it is what every gap is read against. The fourth case is the one a sign-based rule drops: **when every value is zero**, `lo == hi == 0` would make `ceil - floor` zero and the position formula divide by zero, so take a finite fallback span (`floor = 0`, `ceil = 1` in the data's unit) and let every dot sit on the floor, which is the truth. Data that merely *touches* zero is covered by the first two cases, not a special one. `scripts/verify-dumbbell.py` implements this and proves finite coordinates for all four. The plot width is fixed, so narrowing the domain raises px-per-unit and draws every gap wider: across the same 760px, an 8-point gap is 61px on a 0–100 axis and 152px on a 40–80 axis. Ratios *between* rows survive the zoom — what inflates is each gap's size against the frame, which is how a reader judges whether a gap is large. The gap is the entire claim, which makes this the most common way a dumbbell lies.
|
|
95
|
+
- **Both dots share one scale and one unit.** Label both endpoints with their real values. Labelling only the focal end asks the reader to take the geometry on trust.
|
|
96
|
+
- **The connector is a gap, not a trajectory.** It encodes the distance between two values and nothing about what lies between them — no intermediate points, no rate, no guarantee the change was monotonic. Do not narrate it as movement.
|
|
97
|
+
- **State the row order** in the legend or source line: by one endpoint, by signed change, by absolute change, or by an order the subject supplies (chronological, geographic, ordinal). "By gap" alone is ambiguous — say signed or absolute. What is not allowed is an unstated order, which reads as arbitrary.
|
|
98
|
+
- **A row missing an endpoint is disclosed, never imputed and never silently dropped.** Removing incomplete categories without saying so changes the population being compared. Either draw the known end and name the missing value, or drop the row *and* record which rows went and why — a lone dot is otherwise indistinguishable from two coincident dots, which is to say from a genuine zero gap.
|
|
99
|
+
|
|
100
|
+
Two of these rules live in a formula rather than a drawing, so they are executable: `scripts/verify-dumbbell.py` resolves the domain over every sign case and asserts finite coordinates and 3:1 marks, and `scripts/test-verify-dumbbell.py` exercises both polarities — including all-zero and zero-touching data, and the sub-3:1 treatments this replaced. The checker reads the tokens out of this file, so prose and thresholds cannot drift apart. A shipped dumbbell example would additionally owe a check of drawn positions against the values printed at them.
|
|
101
|
+
|
|
102
|
+
## Examples
|
|
103
|
+
|
|
104
|
+
- `assets/example-bar.html` — minimal light
|
|
105
|
+
- `assets/example-bar-dark.html` — minimal dark
|
|
106
|
+
- `assets/example-bar-full.html` — full editorial
|
|
107
|
+
|
|
108
|
+
Dumbbell domain resolution retains finite bounds for representable subnormal and extreme values. If the next nice ladder step would overflow, the finite extreme is used; opposite-sign extreme domains are scaled without overflowing their span.
|
|
@@ -0,0 +1,371 @@
|
|
|
1
|
+
# Data Flow
|
|
2
|
+
|
|
3
|
+
**Best for:** visualising how data moves through a pipeline *across organisational roles* — who initiates, who processes, who publishes, and who consumes. The canonical use case is a multi-role data platform (Admin → Engineers → Scientists → Consumers) with 4–6 process steps. Use when the reader needs to understand **who does what at each stage**, not just the technical components.
|
|
4
|
+
|
|
5
|
+
Prefer standard **Swimlane** for cross-functional business processes (HR approvals, support tickets). Use **Data flow** when the subject is a data pipeline with typed payloads (raw files, tables, reports) and role-scoped access boundaries.
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 1. Inputs — the parameter contract
|
|
12
|
+
|
|
13
|
+
```yaml
|
|
14
|
+
lanes: # 1..4 horizontal swimlanes (top to bottom)
|
|
15
|
+
- { name: ["DATA", "ADMINS"], key: "ADM" }
|
|
16
|
+
- { name: ["DATA", "ENGINEERS"], key: "ENG" }
|
|
17
|
+
- { name: ["DATA", "SCIENTISTS"], key: "SCI" }
|
|
18
|
+
- { name: ["DATA", "CONSUMERS"], key: "CON" }
|
|
19
|
+
|
|
20
|
+
steps: # 1..6 columns (left to right)
|
|
21
|
+
- { number: "01", label: "COLLECT" }
|
|
22
|
+
- { number: "02", label: "STORE" }
|
|
23
|
+
- { number: "03", label: "TRANSFORM" }
|
|
24
|
+
- { number: "04", label: "ANALYZE", focal: true } # focal step header chip — accent fill
|
|
25
|
+
- { number: "05", label: "PUBLISH" }
|
|
26
|
+
|
|
27
|
+
nodes: # explicit per-cell entries; empty cells render nothing
|
|
28
|
+
- { lane: "ADM", step: 0, title: "Project Setup", sub: "create · assign roles", tool: "Platform console" }
|
|
29
|
+
- { lane: "ADM", step: 1, title: "Access Control", sub: "bucket policies · LDAP", tool: "MinIO · LDAP console",
|
|
30
|
+
color: "#b85450" } # tinted rust-red to flag governance/identity concern
|
|
31
|
+
- { lane: "ENG", step: 0, title: "Source Ingest", sub: "ext. sources → raw", tool: "NiFi · API · SFTP",
|
|
32
|
+
chips: {in: "WB", out: "DB"} } # web payload in, dataset out
|
|
33
|
+
- { lane: "ENG", step: 1, title: "Raw Store", sub: "raw landing zones", tool: "MinIO raw",
|
|
34
|
+
chips: {in: "DB", out: "DB"} } # raw stays raw inside the landing zone
|
|
35
|
+
- { lane: "ENG", step: 2, title: "Clean & Stage", sub: "raw → staging → anon", tool: "NiFi · Trino",
|
|
36
|
+
chips: {in: "DB", out: "TB"} } # raw dataset → analysis-ready table
|
|
37
|
+
- { lane: "SCI", step: 3, title: "Explore & Model", sub: "anon data → insights", tool: "JupyterHub · Trino",
|
|
38
|
+
chips: {in: "TB", out: "FL"}, focal: true } # focal — table in, file/report out
|
|
39
|
+
- { lane: "SCI", step: 4, title: "Publish Findings", sub: "models → dashboards", tool: "Superset · Reports",
|
|
40
|
+
chips: {in: "FL", out: "FL"} } # report in, report out (pass-through to publish)
|
|
41
|
+
- { lane: "CON", step: 4, title: "Query Insights", sub: "aggregated views", tool: "Trino (read-only)",
|
|
42
|
+
chips: {in: "TB", out: "TB"} } # consumers read tables, hand off tables
|
|
43
|
+
|
|
44
|
+
arrows: # explicit edges; styles bind to topology (see §3)
|
|
45
|
+
- { from: {lane: "ADM", step: 0}, to: {lane: "ADM", step: 1}, style: "muted" }
|
|
46
|
+
- { from: {lane: "ADM", step: 0}, to: {lane: "ENG", step: 0}, style: "trigger" } # dashed governance
|
|
47
|
+
- { from: {lane: "ADM", step: 1}, to: {lane: "ENG", step: 1}, style: "trigger" }
|
|
48
|
+
- { from: {lane: "ENG", step: 0}, to: {lane: "ENG", step: 1}, style: "muted" }
|
|
49
|
+
- { from: {lane: "ENG", step: 1}, to: {lane: "ENG", step: 2}, style: "muted" }
|
|
50
|
+
- { from: {lane: "ENG", step: 2}, to: {lane: "SCI", step: 3}, style: "accent", # focal cross-role
|
|
51
|
+
label: "anon data" }
|
|
52
|
+
- { from: {lane: "SCI", step: 3}, to: {lane: "SCI", step: 4}, style: "muted" }
|
|
53
|
+
- { from: {lane: "SCI", step: 4}, to: {lane: "CON", step: 4}, style: "link" } # teal: published
|
|
54
|
+
|
|
55
|
+
dark: false
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**Reserved field semantics:**
|
|
59
|
+
- `lanes[k].key` — the 3-letter role chip text (e.g., `ADM`, `ENG`, `SCI`, `CON`). Used inside every node in that lane.
|
|
60
|
+
- `lanes[k].name` — two-line lane label; both lines use the uppercase `eyebrow` role.
|
|
61
|
+
- `steps[j].focal: true` — exactly **one** step may declare this. Header chip renders in accent.
|
|
62
|
+
- `nodes[i].focal: true` — exactly **one** node may declare this. Renders with accent border (§5).
|
|
63
|
+
- `nodes[i].chips` — data-type chips for the node. Either form accepted:
|
|
64
|
+
- **Object form (preferred):** `{in: "<CODE>", out: "<CODE>"}` — explicit input/output semantic. Either side optional.
|
|
65
|
+
- **Array form:** `["<INPUT_CODE>", "<OUTPUT_CODE>"]` — first item is input, second is output.
|
|
66
|
+
- 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**.
|
|
67
|
+
- `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.
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## 2. Layout formulas — deterministic geometry
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
label_col_w = 140
|
|
75
|
+
step_slot_w = 112
|
|
76
|
+
right_pad = 28
|
|
77
|
+
n_steps = len(steps)
|
|
78
|
+
n_lanes = len(lanes)
|
|
79
|
+
|
|
80
|
+
# Canvas
|
|
81
|
+
viewBox_w = label_col_w + n_steps * step_slot_w + right_pad # 5 steps → 728
|
|
82
|
+
header_h = 36
|
|
83
|
+
lane_h = 80
|
|
84
|
+
has_color_row = any(node.color or step.color or lane.color in inputs)
|
|
85
|
+
legend_h = 100 if has_color_row else 80 # 4 rows when colors are present
|
|
86
|
+
viewBox_h = header_h + n_lanes * lane_h + legend_h # 4 lanes, no colors → 436; with colors → 456
|
|
87
|
+
|
|
88
|
+
# Header strip (top)
|
|
89
|
+
header_y = 0 # ends at header_h = 36
|
|
90
|
+
step_chip_y = 6 # 16-px chip at y=6..22
|
|
91
|
+
step_label_y = 29 # text line below chip
|
|
92
|
+
|
|
93
|
+
# Lane positions
|
|
94
|
+
lane_y_top(k) = header_h + k * lane_h # 36, 116, 196, 276
|
|
95
|
+
lane_y_mid(k) = lane_y_top(k) + lane_h/2 # 76, 156, 236, 316
|
|
96
|
+
lane_label_x = label_col_w / 2 # 70
|
|
97
|
+
|
|
98
|
+
# Step / node center x
|
|
99
|
+
step_cx(j) = label_col_w + j * step_slot_w + step_slot_w/2 # 196, 308, 420, 532, 644
|
|
100
|
+
|
|
101
|
+
# Nodes
|
|
102
|
+
node_w = 100
|
|
103
|
+
node_h = 64
|
|
104
|
+
node_x(j) = step_cx(j) - node_w/2 # 146, 258, 370, 482, 594
|
|
105
|
+
node_y(k) = lane_y_top(k) + 8 # 44, 124, 204, 284
|
|
106
|
+
|
|
107
|
+
# Legend strip (bottom)
|
|
108
|
+
legend_y_top = header_h + n_lanes * lane_h # 356
|
|
109
|
+
legend_row_y = [legend_y_top + 16, legend_y_top + 37, legend_y_top + 59]
|
|
110
|
+
# 372, 393, 415
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### 2.1 Background structure
|
|
114
|
+
|
|
115
|
+
- Paper fill across full viewBox.
|
|
116
|
+
- Dot pattern: 22×22 grid, `circle r=0.8`, `fill ink @ 0.10`.
|
|
117
|
+
- Alternating lane tints: odd-indexed lanes (0, 2, …) receive `ink @ 0.018` fill.
|
|
118
|
+
- Lane dividers: horizontal hairlines at every `lane_y_top(k)` and at `legend_y_top`, stroke `ink @ 0.12` width 0.8.
|
|
119
|
+
- Label column right border: vertical hairline at `x = label_col_w`, from `y = header_h` to `y = legend_y_top`.
|
|
120
|
+
|
|
121
|
+
### 2.2 Step header chip
|
|
122
|
+
|
|
123
|
+
Per step `j`:
|
|
124
|
+
|
|
125
|
+
```
|
|
126
|
+
chip_x(j) = step_cx(j) - 16 # 16×16 chip
|
|
127
|
+
chip_y = 6
|
|
128
|
+
chip_w = 32
|
|
129
|
+
chip_h = 16
|
|
130
|
+
chip_rx = 8 # pill-shaped
|
|
131
|
+
number_anchor = (step_cx(j), 14)
|
|
132
|
+
label_anchor = (step_cx(j), 29)
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Default fill: `ink @ 0.12`, number text ink, label text muted.
|
|
136
|
+
Focal fill: `accent @ 0.20`, number + label text accent.
|
|
137
|
+
Per-step `color` override (§4): replaces the fill with `rgba(C, 0.20)` and the text fill with `C`.
|
|
138
|
+
|
|
139
|
+
### 2.3 Lane labels
|
|
140
|
+
|
|
141
|
+
Two-line `eyebrow` role label, both lines uppercase, fill muted:
|
|
142
|
+
- Line 1 at `(lane_label_x, lane_y_mid(k) - 4)`
|
|
143
|
+
- Line 2 at `(lane_label_x, lane_y_mid(k) + 8)`
|
|
144
|
+
|
|
145
|
+
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`).
|
|
146
|
+
|
|
147
|
+
### 2.4 Node content layout (inside the 100×64 rect)
|
|
148
|
+
|
|
149
|
+
```
|
|
150
|
+
role_chip rect 18×10 at (node_x+4, node_y+4), rx=3
|
|
151
|
+
role_chip_text centered at (node_x+13, node_y+9), eyebrow role, font-size=6, weight=600
|
|
152
|
+
title centered at (step_cx(j), node_y+23), node-name role, font-size=9
|
|
153
|
+
sub centered at (step_cx(j), node_y+35), sublabel role, font-size=6.5, muted
|
|
154
|
+
tool centered at (step_cx(j), node_y+47), sublabel role, font-size=6.5, soft
|
|
155
|
+
data chip IN rect 16×8 at (node_x+4, node_y+54), rx=3 # payload type entering the node
|
|
156
|
+
data chip OUT rect 16×8 at (node_x+80, node_y+54), rx=3 # payload type leaving the node
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Empty cells (no node entry) render **nothing**. No placeholder rect, no role chip, no label — the cell is invisible.
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## 3. Arrow rules (mandatory)
|
|
164
|
+
|
|
165
|
+
Four styles, bound to topology. Connectors are drawn **before** all node rects (z-order rule).
|
|
166
|
+
|
|
167
|
+
| `style` | Stroke | Width | Dash | Marker | When required |
|
|
168
|
+
|---|---|---|---|---|---|
|
|
169
|
+
| `muted` | `muted` | 1.0 | — | `arr-muted` | Standard data hand-off between steps or within a lane. |
|
|
170
|
+
| `trigger` | `muted` | 1.0 | `4,3` | `arr-muted` | Governance trigger — an admin action enables downstream work. Unlabelled. |
|
|
171
|
+
| `accent` | `accent` | 1.2 | — | `arr-accent` | Focal cross-role handoff. **Exactly one per diagram**, labeled. |
|
|
172
|
+
| `link` | `link` | 1.0 | — | `arr-link` | Published / externally-consumed output. |
|
|
173
|
+
|
|
174
|
+
**Defs block** (required, three markers):
|
|
175
|
+
|
|
176
|
+
```svg
|
|
177
|
+
<defs>
|
|
178
|
+
<pattern id="dots" width="22" height="22" patternUnits="userSpaceOnUse">
|
|
179
|
+
<circle cx="11" cy="11" r="0.8" fill="{ink @ 0.10}"/>
|
|
180
|
+
</pattern>
|
|
181
|
+
<marker id="arr-muted" markerWidth="6" markerHeight="6" refX="5" refY="3" orient="auto"><path d="M0,0 L6,3 L0,6 Z" fill="{muted}"/></marker>
|
|
182
|
+
<marker id="arr-accent" markerWidth="6" markerHeight="6" refX="5" refY="3" orient="auto"><path d="M0,0 L6,3 L0,6 Z" fill="{accent}"/></marker>
|
|
183
|
+
<marker id="arr-link" markerWidth="6" markerHeight="6" refX="5" refY="3" orient="auto"><path d="M0,0 L6,3 L0,6 Z" fill="{link}"/></marker>
|
|
184
|
+
</defs>
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### 3.1 Routing rules (non-negotiable)
|
|
188
|
+
|
|
189
|
+
- **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).
|
|
190
|
+
- **No diagonals.** Bends use an 8-px Q-bezier corner.
|
|
191
|
+
- **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.
|
|
192
|
+
- **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.
|
|
193
|
+
- **Labels:** only the `accent` arrow gets a label. Use a paper-filled rect mask (opaque) 6 px behind the text. Other arrows are unlabelled.
|
|
194
|
+
- **Z-order:** all arrows emitted before any node rect (the rect fills mask the line ends inside the node).
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
198
|
+
## 4. Component color override
|
|
199
|
+
|
|
200
|
+
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.
|
|
201
|
+
|
|
202
|
+
### 4.1 Per-node `color`
|
|
203
|
+
|
|
204
|
+
Applied to:
|
|
205
|
+
|
|
206
|
+
| Element | Light | Dark |
|
|
207
|
+
|---|---|---|
|
|
208
|
+
| Container fill (`rect`) | `rgba(C, 0.06)` | `rgba(C_light, 0.10)` |
|
|
209
|
+
| Container stroke | `rgba(C, 0.35)` (stroke-width 1) | `rgba(C_light, 0.45)` |
|
|
210
|
+
| Role chip fill | `rgba(C, 0.18)` | `rgba(C_light, 0.22)` |
|
|
211
|
+
| Role chip text | `C` | `C_light` |
|
|
212
|
+
| Title text | `C` | `C_light` |
|
|
213
|
+
| Sub-label | **unchanged** (muted) | **unchanged** (muted) |
|
|
214
|
+
| Tool label | **unchanged** (soft) | **unchanged** (soft) |
|
|
215
|
+
| Data-type chips | **unchanged** | **unchanged** |
|
|
216
|
+
| Arrows touching this node | **unchanged** — topology-driven | **unchanged** |
|
|
217
|
+
|
|
218
|
+
`C_light` = the same hex lightened ~15% for dark-mode contrast (e.g., `#b85450` → `#d97a78`).
|
|
219
|
+
|
|
220
|
+
### 4.2 Per-step `color`
|
|
221
|
+
|
|
222
|
+
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.
|
|
223
|
+
|
|
224
|
+
### 4.3 Per-lane `color`
|
|
225
|
+
|
|
226
|
+
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.
|
|
227
|
+
|
|
228
|
+
### 4.4 Rules
|
|
229
|
+
|
|
230
|
+
- **Never on focal nodes / focal steps.** The accent already carries that signal. A `color` on a focal element is ignored.
|
|
231
|
+
- **Never on arrows.** Arrows are topology-driven. If you want a colored edge, pick a different `style` from §3, not a color override.
|
|
232
|
+
- **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.
|
|
233
|
+
- **Subtitles and tool labels stay muted.** Only the primary identity (border + role chip + title + icon) carries the color signal.
|
|
234
|
+
|
|
235
|
+
### 4.5 Semantic palette (recommended)
|
|
236
|
+
|
|
237
|
+
Same palette as high-level / dp-integration so a reader scanning multiple diagrams sees the same colors meaning the same thing:
|
|
238
|
+
|
|
239
|
+
- `#b85450` rust-red — Security / Identity / Governance (admin nodes, LDAP, access control)
|
|
240
|
+
- `#5a7d9a` slate-blue — Observability / Quality (monitoring, data-quality gates, lineage)
|
|
241
|
+
- `#7a8c47` olive-green — Governance / Lineage (catalog, metadata)
|
|
242
|
+
- `#8c6d3f` warm-brown — Backup / DR / Archive
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## 5. Focal rule
|
|
247
|
+
|
|
248
|
+
The data-flow diagram is built around **one cross-role handoff** that defines its central claim. Three focal slots, exactly one entry each:
|
|
249
|
+
|
|
250
|
+
- **One focal step** (`steps[j].focal: true`) — typically the analytical pivot (Analyze, Model, …). Header chip and legend chip both render in accent.
|
|
251
|
+
- **One focal node** (`nodes[i].focal: true`) — the node that *receives* the focal handoff. Accent border + accent role chip + ink title.
|
|
252
|
+
- **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`).
|
|
253
|
+
|
|
254
|
+
If zero or >1 of any focal slot are declared, halt and ask the user.
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
## 6. Dark mode
|
|
259
|
+
|
|
260
|
+
| Token | Light | Dark |
|
|
261
|
+
|---|---|---|
|
|
262
|
+
| Paper | `paper` | `ink` |
|
|
263
|
+
| Ink | `ink` | `paper` |
|
|
264
|
+
| Muted | `muted` | `soft` |
|
|
265
|
+
| Soft | `soft` | `rule-solid` |
|
|
266
|
+
| Accent | `accent` | `accent` |
|
|
267
|
+
| Link | `link` | `link` |
|
|
268
|
+
| Dot pattern | `ink @ 0.10` | `paper @ 0.10` |
|
|
269
|
+
| Lane tint | `ink @ 0.018` | `paper @ 0.025` |
|
|
270
|
+
| Dividers | `ink @ 0.12` | `paper @ 0.12` |
|
|
271
|
+
| Default chip fill | `ink @ 0.12` | `paper @ 0.12` |
|
|
272
|
+
| Focal chip fill | `accent @ 0.20` | `accent @ 0.22` |
|
|
273
|
+
| Default node fill | `paper` | `paper @ 0.04` |
|
|
274
|
+
| Default node stroke | `ink @ 0.25` | `paper @ 0.20` |
|
|
275
|
+
| Focal node fill | `accent @ 0.07` | `accent @ 0.12` |
|
|
276
|
+
| Focal node stroke | `accent` | `accent` |
|
|
277
|
+
| Custom component colors | `C` | `C_light` (lighten ~15%) |
|
|
278
|
+
|
|
279
|
+
---
|
|
280
|
+
|
|
281
|
+
## 7. Reproducibility checklist (taste gate)
|
|
282
|
+
|
|
283
|
+
Before emitting SVG, verify **every** item:
|
|
284
|
+
|
|
285
|
+
1. `viewBox = "0 0 {viewBox_w} {viewBox_h}"` derived from `n_steps` and `n_lanes` via §2.
|
|
286
|
+
2. Header strip at `y=0..36`; legend strip at `y=legend_y_top..viewBox_h` (`legend_y_top = 36 + n_lanes * 80`).
|
|
287
|
+
3. Every node at `(step_cx(j) - 50, lane_y_top(k) + 8)` size `100×64`.
|
|
288
|
+
4. Empty cells render nothing — no placeholder rect, no text.
|
|
289
|
+
5. Exactly **one** focal step (`steps[j].focal: true`).
|
|
290
|
+
6. Exactly **one** focal node (`nodes[i].focal: true`).
|
|
291
|
+
7. Exactly **one** focal arrow (`style: accent`). Labeled, with a paper-masked rect behind the label.
|
|
292
|
+
8. All other arrows unlabelled.
|
|
293
|
+
9. All arrows emitted before any node rect (z-order rule).
|
|
294
|
+
10. Single-bend routing only — no diagonals. Q-bezier `r=8` at each bend.
|
|
295
|
+
11. Custom component colors ≤ 3 (in addition to the focal pair). Arrows never recolored by component `color`.
|
|
296
|
+
12. Subtitle and tool labels stay muted regardless of any component `color`.
|
|
297
|
+
|
|
298
|
+
---
|
|
299
|
+
|
|
300
|
+
## 8. Data-type chips reference (input + output)
|
|
301
|
+
|
|
302
|
+
Small `16×8 rx=3` badges at the bottom of each node, one for input and one for output. Position is **non-negotiable**:
|
|
303
|
+
|
|
304
|
+
- **Input chip** at `(node_x+4, node_y+54)` — bottom-**left** of the node. Represents the payload format *entering* the node from upstream.
|
|
305
|
+
- **Output chip** at `(node_x+80, node_y+54)` — bottom-**right** of the node. Represents the payload format *leaving* the node toward downstream.
|
|
306
|
+
|
|
307
|
+
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.
|
|
308
|
+
|
|
309
|
+
### Chip codes
|
|
310
|
+
|
|
311
|
+
| Code | Color | Meaning |
|
|
312
|
+
|------|-------|---------|
|
|
313
|
+
| `WB` | `#6e6479` (mauve) | Web / Public data |
|
|
314
|
+
| `DB` | `#5e7a9b` (steel-blue) | Dataset / Raw file |
|
|
315
|
+
| `TB` | `#b8915a` (amber) | Table / Analysis-ready |
|
|
316
|
+
| `FL` | `#9c6b50` (sienna) | File / Report / Export |
|
|
317
|
+
| `LS` | `#4a7c59` (forest) | Live stream / Event |
|
|
318
|
+
|
|
319
|
+
Text inside chip: white, `eyebrow` role at 5px, weight 700.
|
|
320
|
+
|
|
321
|
+
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.
|
|
322
|
+
|
|
323
|
+
---
|
|
324
|
+
|
|
325
|
+
## 9. Legend (3- or 4-row strip)
|
|
326
|
+
|
|
327
|
+
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`).
|
|
328
|
+
|
|
329
|
+
- **Row 1 — `STEPS`** at `y = legend_y_top + 16`: repeat the header chips with their labels. Focal step keeps accent fill.
|
|
330
|
+
- **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.
|
|
331
|
+
- **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.
|
|
332
|
+
- **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.
|
|
333
|
+
|
|
334
|
+
All legend items align on a single horizontal strip per row. Do not stack vertically inside a box.
|
|
335
|
+
|
|
336
|
+
---
|
|
337
|
+
|
|
338
|
+
## 10. Complexity budget
|
|
339
|
+
|
|
340
|
+
| Dimension | Max |
|
|
341
|
+
|---|---|
|
|
342
|
+
| Lanes (roles) | 4 |
|
|
343
|
+
| Steps | 6 |
|
|
344
|
+
| Nodes per lane | Nodes = active steps only — empty cells are invisible (no placeholder box) |
|
|
345
|
+
| Labelled arrows | 1 (focal accent only) |
|
|
346
|
+
| Data-type chips per node | 2 |
|
|
347
|
+
| Custom-colored elements (§4) | 3 (in addition to focal node + focal step) |
|
|
348
|
+
|
|
349
|
+
Above 4 lanes or 6 steps: split into two diagrams (e.g., ingestion pipeline / analytics pipeline).
|
|
350
|
+
|
|
351
|
+
---
|
|
352
|
+
|
|
353
|
+
## 11. Anti-patterns
|
|
354
|
+
|
|
355
|
+
- **Placeholder empty cells** — if a role doesn't participate in a step, leave the cell empty (no box, no text).
|
|
356
|
+
- **More than one labelled arrow** — only the focal cross-role handoff gets a label.
|
|
357
|
+
- **Diagonal arrows** — always horizontal-first, then vertical; single right-angle bend.
|
|
358
|
+
- **`title` role for node titles** — node titles use the `node-name` role (technical context). Only the page `<h1>` uses `title`.
|
|
359
|
+
- **Accent on more than one node, one step, one arrow** — focal = one node + one step + one arrow, max.
|
|
360
|
+
- **`node-name` role for role labels** — lane labels always use the uppercase `eyebrow` role (they are identifiers, not prose).
|
|
361
|
+
- **`color` override on a focal element** — ignored. Accent always wins.
|
|
362
|
+
- **Custom-colored arrows** — arrows are topology-driven. Color on a node never spreads to its edges.
|
|
363
|
+
- **Lane tints over-applied** — a tint on every lane reads as decoration, not signal. Apply to ≤1 lane.
|
|
364
|
+
|
|
365
|
+
---
|
|
366
|
+
|
|
367
|
+
## 12. Examples
|
|
368
|
+
|
|
369
|
+
- `assets/example-data-flow.html` — minimal light (the platform, 4-role × 5-step: Admin, Engineers, Scientists, Consumers). Gallery default.
|
|
370
|
+
- `assets/example-data-flow-dark.html` — same, dark skin.
|
|
371
|
+
- `assets/example-data-flow-full.html` — same, editorial-card frame.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Database Schema
|
|
2
|
+
|
|
3
|
+
**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.
|
|
4
|
+
|
|
5
|
+
**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.
|
|
6
|
+
|
|
7
|
+
## Layout conventions
|
|
8
|
+
|
|
9
|
+
### Table box
|
|
10
|
+
|
|
11
|
+
- **Header band** — `schema.table` (e.g. `public.orders`) in the `node-name` role, 12px, weight 600, with a rectangular type tag (`rx=2`, NOT a pill) reading `TABLE`. A hairline separates it from the body.
|
|
12
|
+
- **Column rows** — fixed 24px row height so connectors can anchor predictably. Each row: column name in the `node-name` family at 12px anchored left, SQL type in the `sublabel` role 9px `muted` anchored right (`uuid`, `text`, `numeric(12,2)`, `timestamptz`), and constraint chips between them as small `rx=2` tags in the `eyebrow` role at 8px: `PK`, `FK`, `UQ`, `NN`. Alternate row background `ink @ 0.02` on even rows for scannability.
|
|
13
|
+
- **Overflow row** — when a table has more columns than the budget allows, the last row is a `sublabel`-role 9px `muted` line: `+ N more columns`. Never silently truncate a table without saying so.
|
|
14
|
+
- **Index compartment** — an optional final compartment separated by a hairline, labelled with an `eyebrow`-role 8px uppercase `INDEXES` eyebrow, listing index names in the `sublabel` role at 9px (`idx_orders_customer_id`, `uq_products_sku`). List only the indexes that matter to the story, not every index on the table.
|
|
15
|
+
|
|
16
|
+
### Foreign-key connectors — the defining rule
|
|
17
|
+
|
|
18
|
+
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 the `arrow-label` role at 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.
|
|
19
|
+
|
|
20
|
+
### Schema grouping
|
|
21
|
+
|
|
22
|
+
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 an `eyebrow`-role 8px uppercase tracked schema label in its top-left corner. Draw the group rect first so tables paint over it.
|
|
23
|
+
|
|
24
|
+
### Focal rule
|
|
25
|
+
|
|
26
|
+
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`.
|
|
27
|
+
|
|
28
|
+
If a schema has no destructive FK, it has no focal element. Leave it unaccented rather than promoting an arbitrary table.
|
|
29
|
+
|
|
30
|
+
## Complexity budget
|
|
31
|
+
|
|
32
|
+
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.
|
|
33
|
+
|
|
34
|
+
## Anti-patterns
|
|
35
|
+
|
|
36
|
+
- Drawing every column of every table — a schema diagram is an argument about a subsystem, not a `\d+` dump.
|
|
37
|
+
- FK lines that connect box to box instead of column to column — that's ER, use ER instead.
|
|
38
|
+
- Missing SQL types — the type is half the content.
|
|
39
|
+
- Unlabelled FK edges — the `ON DELETE` behavior is what a reviewer is looking for.
|
|
40
|
+
- Constraint chips on every row until the chips are the noise.
|
|
41
|
+
- Index compartments listing every index rather than the ones that matter to the story.
|
|
42
|
+
- Mixing conceptual entity names with physical table names in one diagram.
|
|
43
|
+
|
|
44
|
+
## Examples
|
|
45
|
+
|
|
46
|
+
- `assets/example-db-schema.html` — minimal light
|
|
47
|
+
- `assets/example-db-schema-dark.html` — minimal dark
|
|
48
|
+
- `assets/example-db-schema-full.html` — full editorial
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Dependency Graph
|
|
2
|
+
|
|
3
|
+
**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.
|
|
4
|
+
|
|
5
|
+
## Layout conventions
|
|
6
|
+
|
|
7
|
+
- **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.
|
|
8
|
+
- Nodes are the standard node-box pattern (§6, [primitives-core.md](primitives-core.md#node-box--full-pattern)): `rx=6`, 160px wide, 56px tall.
|
|
9
|
+
- **Fan-in badge.** Every node carries an `eyebrow`-role 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.
|
|
10
|
+
- **Node treatments** ([style-guide.md § Node type → treatment](style-guide.md#node-type--treatment)):
|
|
11
|
+
- Internal package/service → white fill + `ink` stroke.
|
|
12
|
+
- External / third-party → `ink @ 0.03` fill + `ink @ 0.30` stroke (the External/Cloud treatment).
|
|
13
|
+
- Leaf with no outgoing edges → `ink @ 0.05` fill + `muted` stroke.
|
|
14
|
+
- **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 `arrow-label`-role 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.
|
|
15
|
+
- **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.
|
|
16
|
+
- 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.
|
|
17
|
+
|
|
18
|
+
## Complexity budget
|
|
19
|
+
|
|
20
|
+
| Limit | Rule |
|
|
21
|
+
|---|---|
|
|
22
|
+
| Max nodes | 9 |
|
|
23
|
+
| Max edges | 14 |
|
|
24
|
+
| Max rank layers | 4 |
|
|
25
|
+
| Max highlighted cycles | 1 |
|
|
26
|
+
| Max accent elements | 2 |
|
|
27
|
+
|
|
28
|
+
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.
|
|
29
|
+
|
|
30
|
+
## Anti-patterns
|
|
31
|
+
|
|
32
|
+
- Drawing a dependency graph when the data is actually a tree (single parent everywhere, no cycles) — use Tree instead.
|
|
33
|
+
- Forward edges that point upward without being the one marked cycle.
|
|
34
|
+
- A hairball layout with no rank ordering — rank first, always; ranking is what makes the graph readable, not an optional polish pass.
|
|
35
|
+
- One node per file instead of per package/module/service — the graph is about dependency structure, not the filesystem.
|
|
36
|
+
- Unlabelled external dependencies — version or registry belongs in the `sublabel` (`v3.23 · npm`), not left implicit.
|
|
37
|
+
- Highlighting more than one cycle in a single diagram — pick the one that matters editorially; a second cycle competes with the first and neither reads.
|
|
38
|
+
- Omitting the fan-in badges — without them the reader can't see at a glance where dependencies concentrate, which is the entire reason this type exists over a plain tree.
|
|
39
|
+
|
|
40
|
+
## Examples
|
|
41
|
+
|
|
42
|
+
- `assets/example-dependency.html` — minimal light
|
|
43
|
+
- `assets/example-dependency-dark.html` — minimal dark
|
|
44
|
+
- `assets/example-dependency-full.html` — full editorial
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Deployment
|
|
2
|
+
|
|
3
|
+
**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.
|
|
4
|
+
|
|
5
|
+
## Layout conventions
|
|
6
|
+
|
|
7
|
+
Three nesting levels, outermost to innermost — reuses the containment grammar from `type-nested.md`, specialized for infrastructure:
|
|
8
|
+
|
|
9
|
+
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`. An `eyebrow`-role 8px (or 7px for tight layouts) uppercase tracked 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).
|
|
10
|
+
2. **Infrastructure node** — a host, VM, pod, or managed service inside a zone. The §6 node-box pattern (SKILL.md; markup in [primitives-core.md](primitives-core.md#node-box--full-pattern)) at `rx=6`, with a rectangular type tag (`rx=2`, **not** a pill) carrying `POD` / `VM` / `MANAGED` / `CDN` in the top-left corner.
|
|
11
|
+
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 the `node-name` family at 12px (left-aligned) plus a `sublabel`-role 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).
|
|
12
|
+
|
|
13
|
+
**Replica badge.** A node running N copies carries a right-aligned `eyebrow`-role 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.
|
|
14
|
+
|
|
15
|
+
**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 the `arrow-label` role at 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`.
|
|
16
|
+
|
|
17
|
+
**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).
|
|
18
|
+
|
|
19
|
+
## Complexity budget
|
|
20
|
+
|
|
21
|
+
| Limit | Rule |
|
|
22
|
+
|---|---|
|
|
23
|
+
| Max zones | 3 |
|
|
24
|
+
| Max infrastructure nodes | 6 |
|
|
25
|
+
| Max artifact chips | 9 |
|
|
26
|
+
| Max network paths | 8 |
|
|
27
|
+
| Max accent elements | 2 |
|
|
28
|
+
|
|
29
|
+
Over budget → split into one deployment diagram per environment.
|
|
30
|
+
|
|
31
|
+
## Anti-patterns
|
|
32
|
+
|
|
33
|
+
- 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.
|
|
34
|
+
- Zones that are just visual grouping with no boundary meaning — a zone must be a real environment or network boundary, not a layout convenience.
|
|
35
|
+
- Artifact chips without a version tag. The version is why the diagram exists; an unversioned chip is a wasted box.
|
|
36
|
+
- One node drawn per replica instead of a single node with a replica badge.
|
|
37
|
+
- Cloud-vendor icon soup standing in for named nodes — name the host or service, don't decorate it.
|
|
38
|
+
- Unlabelled network paths. Protocol and port are the content of a deployment diagram, not decoration.
|
|
39
|
+
- Mixing two environments in one diagram (e.g. staging and production nodes side by side without a zone boundary that actually separates them).
|
|
40
|
+
|
|
41
|
+
## Examples
|
|
42
|
+
|
|
43
|
+
- `assets/example-deployment.html` — minimal light
|
|
44
|
+
- `assets/example-deployment-dark.html` — minimal dark
|
|
45
|
+
- `assets/example-deployment-full.html` — full editorial
|