Merge curated fork work: 12 new diagram types, icons, export, onboarding v2
Imports the substantive work from the aristide/diagram-design fork (PR #9) as a curated set: - 12 new diagram types with reference docs: radar, bar, line, gantt, scatter, it-state, high-level, process, medallion, data-flow, dp-integration, dp-security-matrix (26 types total) - 86-icon monochrome IT/cloud primitive, build script, and gallery - /diagram-design:export command with PNG/SVG export reference - Onboarding v2: URL, skill, and folder design-token sources - Mandatory connector rules (orthogonal elbows, label gaps, fanned attach points, bridge crossings) + architecture/ER connector upgrades - Series palette tokens for multi-series chart types - THIRD_PARTY_LICENSES.md covering Tabler, Simple Icons, log-z, Devicon Not taken from the fork: plugin-manifest identity changes, the client-brand takeover of style-guide.md, and client-branded example files. The six affected type examples were regenerated in the neutral editorial skin with generic content, and their README screenshots recaptured. Reference docs for those types were rewritten to semantic tokens and typography roles. Version: 1.0.0 -> 2.0.0. Co-authored-by: Aristide <mendoo.aristide@gmail.com>
This commit is contained in:
Cathryn Lavery
co-authored by
Aristide
Aristide
parent
0ab077f229
commit
2e9cefb9f3
@@ -0,0 +1,107 @@
|
||||
# Export to PNG / SVG
|
||||
|
||||
Convert a generated diagram HTML file into a portable `.svg` and/or `.png` next to it. **Manual only — never run unprompted.**
|
||||
|
||||
## Trigger
|
||||
|
||||
Load this file when:
|
||||
|
||||
- The user invokes `/diagram-design:export <html-file>` (the plugin's slash command — defined in `commands/export.md` at the repo root).
|
||||
- The user asks in natural language to export, save, rasterize, convert, or download a diagram in `.svg` or `.png` form. Typical phrasings:
|
||||
- "export this as PNG"
|
||||
- "save as SVG"
|
||||
- "give me a PNG of that diagram"
|
||||
- "rasterize it"
|
||||
- "convert to png and svg"
|
||||
|
||||
The slash command is a thin wrapper that delegates here — both paths run the same procedure below.
|
||||
|
||||
## Scope
|
||||
|
||||
Both formats are **diagram-only** — just the `<svg>` node. Editorial wrappers (header, summary cards, footer in `-full` variants) are intentionally dropped: the export deliverable is the diagram itself, suitable for Figma, slides, social cards, or blog images.
|
||||
|
||||
If the user explicitly asks for "a screenshot of the whole page including the cards", that's a different request — fall back to a normal full-page screenshot via the user's OS or browser.
|
||||
|
||||
## SVG export procedure
|
||||
|
||||
1. Read the source HTML file.
|
||||
2. Extract the **first** `<svg ...>...</svg>` block. Use a multiline regex anchored on `<svg` and `</svg>`. Most generated diagrams have only one SVG; if there are multiple, the first is the diagram (gallery files are an exception — see *Edge cases*).
|
||||
3. Make it standalone:
|
||||
- Ensure the opening tag has `xmlns="http://www.w3.org/2000/svg"`. Add it if missing.
|
||||
- Ensure a `viewBox` is present. The skill's templates always include one; warn the user if absent rather than guessing.
|
||||
- Inject Google Fonts `@import` so the SVG renders with correct typography in a browser:
|
||||
```svg
|
||||
<defs>
|
||||
<style>@import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Geist:wght@400;500;600&family=Geist+Mono:wght@400;500;600&display=swap');</style>
|
||||
</defs>
|
||||
```
|
||||
If the SVG already contains a `<defs>` block, **merge** the `<style>` into it (don't add a second `<defs>`).
|
||||
4. Prepend `<?xml version="1.0" encoding="UTF-8"?>\n` so the file is well-formed XML.
|
||||
5. Write to `<basename>.svg` next to the source (e.g. `example-architecture.html` → `example-architecture.svg`). Honour an explicit output path if the user provides one.
|
||||
|
||||
### Caveat to surface to the user
|
||||
|
||||
Tools that don't fetch remote fonts at import time (offline Illustrator, some Figma import paths, older SVG viewers) will substitute typography. The SVG renders correctly in any modern browser. For pixel-perfect portability, recommend the PNG export.
|
||||
|
||||
## PNG export procedure
|
||||
|
||||
Render **the original HTML** (not the extracted SVG) and screenshot only the `<svg>` element's bounding box. This keeps font loading reliable (already wired in the source HTML) while satisfying the "diagram only" rule. The PNG always has a **transparent background** (`omit_background=True`) so it can be placed on any slide or doc colour without a white halo.
|
||||
|
||||
### Detection
|
||||
|
||||
Before running anything, verify Playwright is installed:
|
||||
|
||||
```
|
||||
python -c "import playwright" 2>NUL || python -c "import playwright"
|
||||
```
|
||||
|
||||
If the import fails, surface this exact instruction to the user and stop:
|
||||
|
||||
> Playwright isn't installed. To enable PNG export, run:
|
||||
> ```
|
||||
> pip install playwright
|
||||
> playwright install chromium
|
||||
> ```
|
||||
> Then ask me to export again.
|
||||
|
||||
Don't auto-install. The user asked for one feature, not a system change.
|
||||
|
||||
### Rasterize
|
||||
|
||||
Write the snippet below to a temp file and run it with `python <tmp.py> <src.html> <out.png>`:
|
||||
|
||||
```python
|
||||
from playwright.sync_api import sync_playwright
|
||||
import sys, pathlib
|
||||
|
||||
src, out = sys.argv[1], sys.argv[2]
|
||||
scale = int(sys.argv[3]) if len(sys.argv) > 3 else 2
|
||||
|
||||
with sync_playwright() as p:
|
||||
browser = p.chromium.launch()
|
||||
page = browser.new_page(device_scale_factor=scale)
|
||||
page.goto(f"file://{pathlib.Path(src).resolve()}")
|
||||
page.wait_for_load_state("networkidle")
|
||||
page.locator("svg").first.screenshot(path=out, omit_background=True)
|
||||
browser.close()
|
||||
```
|
||||
|
||||
Default `device_scale_factor=2` for crisp output. Accept `1` for compact assets or `3` for print/retina hero use, passed as a third CLI arg.
|
||||
|
||||
### Output naming
|
||||
|
||||
`example-architecture.html` → `example-architecture.png`, written next to the source. Honour explicit user-provided paths.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Source is `assets/index.html`** (the gallery, multiple SVGs in one file): refuse the export and ask the user which specific diagram file they meant. Don't guess.
|
||||
- **No `<svg>` block found**: the source isn't a diagram file. Tell the user; don't write anything.
|
||||
- **Surrounding HTML matters to the user**: they want cards/header in the image. Tell them this skill exports diagrams only, and recommend a browser-based full-page screenshot (or a separate PDF print).
|
||||
- **Source is missing fonts at runtime**: Playwright will substitute, the screenshot will look off. Check that the source HTML has the `<link href="...fonts.googleapis.com...">` tag in `<head>`. If absent, the file isn't from a current template — fix the source rather than working around it in export.
|
||||
|
||||
## What this command never does
|
||||
|
||||
- Modifies the source HTML.
|
||||
- Adds export buttons or `<script>` tags to generated diagrams (the "no JS in deliverables" rule in §11 still stands).
|
||||
- Auto-emits `.svg` or `.png` alongside HTML generation. Manual on every call.
|
||||
- Embeds an HTML wrapper (cards, headers) into the SVG via `foreignObject`. Too fragile across renderers.
|
||||
@@ -1,17 +1,23 @@
|
||||
# Onboarding — generate your skin from a website
|
||||
# Onboarding — generate your skin from a design source
|
||||
|
||||
**Goal:** point the skill at a site you like (your own, a competitor, a reference), and have it extract the palette + typography, then rewrite `style-guide.md` so every future diagram inherits that skin.
|
||||
**Goal:** point the skill at a design source — a website, an installed skill, or a local folder — and have it extract the palette + typography, then rewrite `style-guide.md` so every future diagram inherits that skin.
|
||||
|
||||
Takes about 60 seconds.
|
||||
|
||||
Three source methods are supported. Jump to the relevant section:
|
||||
|
||||
- [§ URL](#url) — fetch a live website
|
||||
- [§ Skill](#skill) — read an installed Claude Code skill that carries design tokens
|
||||
- [§ Folder](#folder) — read a local design-system directory (CSS, JSON, Markdown)
|
||||
|
||||
---
|
||||
|
||||
## The flow
|
||||
## The flow (all methods)
|
||||
|
||||
```
|
||||
URL you provide
|
||||
Source you provide (URL / skill name / folder path)
|
||||
↓
|
||||
[1] fetch homepage (headless browser or HTTP)
|
||||
[1] read / fetch the source
|
||||
↓
|
||||
[2] extract dominant colors + fonts
|
||||
↓
|
||||
@@ -26,17 +32,17 @@ future diagrams use your tokens
|
||||
|
||||
---
|
||||
|
||||
## Invocation
|
||||
---
|
||||
|
||||
Ask the skill:
|
||||
## § URL
|
||||
|
||||
### Invocation
|
||||
|
||||
> *"Onboard Schematic to my site — `https://example.com`"*
|
||||
|
||||
Or run it with an explicit URL and the skill reads this file and executes the steps below.
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — fetch the page
|
||||
### Step 1 — fetch the page
|
||||
|
||||
Use `agent-browser` (preferred) or a plain `fetch`. If the site has multiple pages worth sampling (landing + blog + product), fetch 2–3 and merge the palette signals.
|
||||
|
||||
@@ -64,6 +70,7 @@ Prefer CSS custom properties when the site exposes them (`:root { --accent: …;
|
||||
### Fonts
|
||||
|
||||
Read the rendered `font-family` stack of:
|
||||
|
||||
- `<h1>` → `title` family
|
||||
- `<body>` → `node-name` family
|
||||
- `<code>`, `<pre>`, or any mono-styled element → `sublabel` family
|
||||
@@ -120,12 +127,13 @@ Also regenerate the dark variant via the inversion rule (`rgba(11,13,11, X)` →
|
||||
Write the new tokens to `style-guide.md`. Suggest running the `/regenerate-examples` flow (if it exists) or rebuilding one example to verify the new skin reads cleanly.
|
||||
|
||||
After onboarding, the user should:
|
||||
1. Open `assets/index.html` (gallery) and confirm the new palette feels coherent across all 14 types.
|
||||
|
||||
1. Open `assets/index.html` (gallery) and confirm the new palette feels coherent across all 26 types.
|
||||
2. If any type looks off, they usually need to tune `muted` (often too dark or too light against the new `paper`).
|
||||
|
||||
---
|
||||
|
||||
## When onboarding fails
|
||||
## When URL onboarding fails
|
||||
|
||||
- **Site uses webfonts you can't replicate** (custom-hosted, paid): keep the schematic defaults for typography and skin only the colors.
|
||||
- **Brand has 6+ colors** and you can't identify a clear hierarchy: pick one as `accent`, demote the rest to `muted` variants or ignore them. The schematic grammar only uses 5–7 roles.
|
||||
@@ -134,6 +142,127 @@ After onboarding, the user should:
|
||||
|
||||
---
|
||||
|
||||
## § Skill
|
||||
|
||||
Extract tokens from an installed Claude Code skill that carries its own design system (e.g. a `brand-design` or `ui-kit` skill).
|
||||
|
||||
### Invocation
|
||||
|
||||
> *"Onboard Schematic from my `acme-design` skill"*
|
||||
|
||||
Or the gate offers this as option (b) and the user names the skill.
|
||||
|
||||
### Step 1 — locate the skill
|
||||
|
||||
Search for the skill in order:
|
||||
|
||||
1. `~/.claude/skills/<skill-name>/` (user install)
|
||||
2. `.claude/skills/<skill-name>/` (project install)
|
||||
3. Any path the user provides explicitly
|
||||
|
||||
If not found, ask the user to confirm the skill name or provide the path.
|
||||
|
||||
### Step 2 — read token sources
|
||||
|
||||
Glob the skill directory for any of these files and read them all:
|
||||
|
||||
| Priority | Pattern | What to look for |
|
||||
|---|---|---|
|
||||
| 1 | `*.css`, `colors*.css`, `tokens.css` | CSS custom properties in `:root { --color-*: …; }` |
|
||||
| 2 | `tokens.json`, `design-tokens.json`, `*.tokens.json` | Style Dictionary / Figma token JSON |
|
||||
| 3 | `SKILL.md`, `README.md` | Markdown tables listing colors, fonts, hex values |
|
||||
| 4 | `style-guide.md`, `*design*.md` | Any narrative design documentation |
|
||||
| 5 | `*.html` (preview/example files) | Inline `<style>` blocks — scan `:root` and `body` rules |
|
||||
|
||||
Read all matches and merge — CSS custom properties take priority over inferred values from HTML.
|
||||
|
||||
### Step 3 — extract colors and fonts
|
||||
|
||||
**From CSS custom properties:**
|
||||
Map variable names to semantic roles using name-heuristics:
|
||||
|
||||
| If the variable name contains… | Map to role |
|
||||
|---|---|
|
||||
| `background`, `bg`, `paper`, `surface`, `canvas` | `paper` |
|
||||
| `foreground`, `text`, `body`, `ink`, `on-surface` | `ink` |
|
||||
| `muted`, `subtle`, `secondary`, `caption` | `muted` |
|
||||
| `accent`, `brand`, `primary`, `cta`, `highlight` | `accent` |
|
||||
| `border`, `rule`, `divider`, `outline` | `rule` |
|
||||
| `mono`, `code`, `pre` | `sublabel` font |
|
||||
|
||||
**From JSON tokens:** follow the same heuristics on key names. If the JSON follows Style Dictionary format (`{ "color": { "brand": { "value": "#…" } } }`), flatten the path and apply heuristics to the leaf key.
|
||||
|
||||
**From Markdown tables:** look for rows with hex values (`#rrggbb`) adjacent to role-like words. A row like `| accent | #eb6c36 |` maps directly.
|
||||
|
||||
**Fonts:** look for `font-family` rules, `@import` or `@font-face` declarations, and Markdown mentions of font names alongside size/weight.
|
||||
|
||||
### Step 4 — map, validate, propose diff
|
||||
|
||||
Same as the URL method: fill the role table, run contrast checks, show the diff, ask for approval before writing.
|
||||
|
||||
### When skill extraction is ambiguous
|
||||
|
||||
- **Skill has no CSS or token files**: fall back to reading all `.md` files and look for hex values mentioned in prose. Surface what you found and ask the user to confirm mappings before applying.
|
||||
- **Multiple accent candidates**: list them and ask the user to pick one. Don't guess.
|
||||
- **Skill is dark-mode first**: ask whether to treat the dark values as the `paper`/`ink` defaults or to invert.
|
||||
|
||||
---
|
||||
|
||||
## § Folder
|
||||
|
||||
Extract tokens from a local directory — a checked-out design system repo, a Figma export, or any folder the user points you at.
|
||||
|
||||
### Invocation
|
||||
|
||||
> *"Onboard Schematic from my design system at `~/projects/brand/design-tokens/`"*
|
||||
|
||||
Or the gate offers this as option (c) and the user provides the path.
|
||||
|
||||
### Step 1 — discover files
|
||||
|
||||
Glob the folder (recursively, up to 3 levels deep) for:
|
||||
|
||||
```
|
||||
**/*.css
|
||||
**/*.scss (read @forward / $variable declarations)
|
||||
**/tokens.json
|
||||
**/*.tokens.json
|
||||
**/design-tokens.json
|
||||
**/colors.json
|
||||
**/*style-guide*.md
|
||||
**/*design-system*.md
|
||||
**/README.md
|
||||
**/*.html (scan <style> blocks only)
|
||||
```
|
||||
|
||||
If the result set is large (>20 files), prefer files in the root and files whose names contain `color`, `token`, `brand`, `palette`, `style`, or `theme`.
|
||||
|
||||
### Step 2 — read and merge
|
||||
|
||||
Read every discovered file. Apply the same extraction logic as the Skill method (§ Skill → Step 3). CSS custom properties and JSON tokens take priority over inferred values from prose.
|
||||
|
||||
**SCSS variables:** treat `$variable-name: value;` the same as a CSS custom property — apply name heuristics to `$variable-name`.
|
||||
|
||||
**Figma token JSON** (Figma Tokens Plugin format):
|
||||
|
||||
```json
|
||||
{ "colors": { "brand": { "primary": { "value": "#eb6c36", "type": "color" } } } }
|
||||
```
|
||||
|
||||
Walk the tree; the leaf `value` fields are the colors, the path segments supply the role heuristic.
|
||||
|
||||
### Step 3 — map, validate, propose diff
|
||||
|
||||
Same as the URL method: run contrast checks, show the full diff against current `style-guide.md`, and write only after the user approves.
|
||||
|
||||
### When folder extraction is ambiguous
|
||||
|
||||
- **No structured token files, only prose docs**: read every `.md` in the root and extract hex values found near role-like words. Show the user a table of what you inferred — don't silently apply uncertain mappings.
|
||||
- **Multiple themes / color schemes found**: list them, ask the user which one to use as the diagram skin.
|
||||
- **Folder has zero readable files**: tell the user and ask for a more specific path or switch to manual token entry.
|
||||
|
||||
---
|
||||
|
||||
## Future: per-project skins
|
||||
|
||||
If the user wants multiple skins (one per project), duplicate `style-guide.md` as `style-guides/<project>.md` and add a header comment pointing the build to the active one. That's a v5.2 feature — for now, one skin per skill install.
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -35,6 +35,20 @@ Every token is referred to by **semantic role**, not by its hex value. Type refe
|
||||
|
||||
Any `rgba(28,25,23, X)` in light becomes `rgba(250,247,242, X)` in dark. Same opacities, RGB flipped. The accent gets a slight hue-shift brighter to read on dark paper.
|
||||
|
||||
### Series palette (multi-series chart types only)
|
||||
|
||||
A small set of desaturated, editorial-tone colors for chart types that genuinely need to distinguish multiple overlapping entities (currently: **radar**). The "1-focal" rule still holds — `accent` is reserved for the focal series; the palette below covers the rest.
|
||||
|
||||
| Token | Light | Dark | Notes |
|
||||
|---|---|---|---|
|
||||
| `series-1` | `#7c8f6f` (sage) | `#9caf8f` | Non-focal series |
|
||||
| `series-2` | `#5e7a9b` (dusty-blue) | `#82a0c0` | Non-focal series |
|
||||
| `series-3` | `#b8915a` (mustard) | `#d3ad7a` | Non-focal series |
|
||||
| `series-4` | `#9c6b50` (rust-brown) | `#b88670` | Non-focal series |
|
||||
| `series-5` | `#6e6479` (slate) | `#8d8298` | Non-focal series |
|
||||
|
||||
Fills sit at `0.18` opacity light, `0.22` dark; strokes use the full color. **Don't backfill these tokens to non-chart types** — architecture, swimlane, etc. continue to use muted-ink variants. The series palette is opt-in for diagrams where overlapping shapes demand distinguishable color, not a license to add color elsewhere.
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
@@ -9,6 +9,64 @@
|
||||
- 1–2 coral focal nodes: the primary integration point, the primary data store, or the key decision node.
|
||||
- Dashed boundary rectangles mark regions (VPC, security group, trust zone); labels sit on a paper-colored mask over the boundary line.
|
||||
|
||||
## Connector style
|
||||
|
||||
**Rounded right-angle (orthogonal) connectors are MANDATORY** for all non-horizontal/vertical connections — diagonal `<line>` between off-axis nodes is a hard fail (see SKILL.md §6 Mandatory connector rules). Two-bend elbow path with `r=8`:
|
||||
|
||||
```svg
|
||||
<!-- right+down: from (x1,y1) to (x2,y2), mid = (x1+x2)/2 -->
|
||||
<path d="M x1,y1 H mid-8 Q mid,y1 mid,y1+8 V y2-8 Q mid,y2 mid+8,y2 H x2"
|
||||
fill="none" stroke="…" stroke-width="1.2" marker-end="url(#arrow)"/>
|
||||
```
|
||||
|
||||
Flip the vertical signs for right+up. Use a plain `<line>` only when endpoints share the same x or y. Arrow labels sit on the vertical segment, centered horizontally on `mid` and vertically between the two corners.
|
||||
|
||||
**Port selection — use top/bottom for vertical connectors.** When the destination is noticeably above or below the source, exit the source's top/bottom edge and enter the destination's top/bottom edge. Use a single-bend L-path (horizontal → corner → vertical into the node), not a left/right side port:
|
||||
|
||||
```svg
|
||||
<!-- entering a node from its bottom (destination above source) -->
|
||||
<path d="M x1,y_src H x2-8 Q x2,y_src x2,y_src-8 V y_dst"
|
||||
fill="none" stroke="…" stroke-width="1.2" marker-end="url(#arrow)"/>
|
||||
```
|
||||
|
||||
Reserve left/right ports for connections that travel primarily horizontally. Entering a node from the side on a mainly-vertical path looks like the arrow punctures the node face rather than arriving from above or below.
|
||||
|
||||
**Dashed paths — same routing rules.** Optional, return, async, and passive flows use `stroke-dasharray="4,3"` and a lighter stroke weight (`stroke-width="1"`). Apply the **same orthogonal routing, port-selection, and bridge/hop rules** as solid paths — the dash pattern only communicates semantic weight, not a different routing grammar. When a dashed path and a solid path must cross, bridge the dashed one (it is by definition the less important connection).
|
||||
|
||||
**Zone label margin.** Leave ≥16px between the bottom of the zone eyebrow label and the top of the first enclosed node. Size the zone rect tall enough to contain this header gap (zone `y` = node_top − 32; label mask `y` = zone_y + 4).
|
||||
|
||||
## Crossing arrows — bridge / hop
|
||||
|
||||
When two orthogonal arrows must cross, add a small arc (hop/bridge) on the **less important** arrow at the crossing point. The more important arrow is drawn uninterrupted.
|
||||
|
||||
```svg
|
||||
<!-- Horizontal hop over a vertical crossing at x=cx, on a line at y -->
|
||||
<path d="M x1,y H cx-8 a 8,8 0 0,1 16,0 H x2"
|
||||
fill="none" stroke="…" stroke-width="1.2" marker-end="url(#arrow)"/>
|
||||
```
|
||||
|
||||
`a 8,8 0 0,1 16,0` is an SVG arc: rx=ry=8, large-arc=0, sweep=1 (curves visually upward), advancing 16px right — creating an 8px-radius semicircular bump over the crossing. For a vertical hop over a horizontal, use `a 8,8 0 0,0 0,16` on the vertical path.
|
||||
|
||||
Decide which arrow to bridge: bridge the one that is less semantically important (passive, secondary, write-back), or the one with lighter stroke weight (dashed, muted). Never bridge both.
|
||||
|
||||
## Zone grouping
|
||||
|
||||
Group 2+ nodes that serve the same tier or trust boundary with a zone rect — drawn **before** arrows and nodes (z-order: bg → zones → arrows → nodes):
|
||||
|
||||
```svg
|
||||
<rect x="{x}" y="{y}" width="{w}" height="{h}" rx="8"
|
||||
fill="rgba(45,49,66,0.02)" stroke="rgba(45,49,66,0.10)" stroke-width="0.8"/>
|
||||
<rect x="{label_x}" y="{y+4}" width="{label_w}" height="12" rx="2" fill="{paper}"/>
|
||||
<text x="{label_cx}" y="{y+13}" fill="rgba(45,49,66,0.40)" font-size="7"
|
||||
font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.14em">LAYER</text>
|
||||
```
|
||||
|
||||
Rules:
|
||||
- Leave 12–16px above the first enclosed node — the eyebrow label sits in this margin.
|
||||
- Zone fill: `rgba(45,49,66,0.02)` (2% ink wash). Any stronger competes with node fills.
|
||||
- Max 3 zones per diagram. More and it reads like a swimlane (use that type instead).
|
||||
- Dark mode: swap `rgba(45,49,66,…)` → `rgba(245,245,245,…)` same opacities; label mask fill = `paper` (dark).
|
||||
|
||||
## Anti-patterns
|
||||
- Every box in coral ("this is important too") — hierarchy collapses.
|
||||
- Bidirectional arrow when one direction is obvious from context.
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
# Bar / Column Chart
|
||||
|
||||
**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.
|
||||
|
||||
## Layout conventions
|
||||
|
||||
- **Orientation:** Vertical bars (columns) are default. Horizontal bars are appropriate when category labels are long or you have more than 8 categories.
|
||||
- **Plot area margins:** left 80px (y-axis labels), bottom 60px (x-axis labels), top 40px, right 40px — inside a `0 0 1000 500` viewBox.
|
||||
- **Bar count cap:** 4–8 bars. More than 8 → group into periods or split into two charts.
|
||||
- **Bar width:** ≥ 50% of the column pitch (the gap should never exceed the bar). Typical: pitch=110px, bar=72px.
|
||||
- **Y-axis gridlines:** 4–6 horizontal lines at regular intervals. Stroke `rgba(45,49,66,0.08)` (very faint), 0.8px. X-axis baseline at `rgba(45,49,66,0.25)`, 1px.
|
||||
- **Y-axis labels:** right-aligned Geist Mono 8px muted, at x=72 (8px left of the plot area).
|
||||
- **X-axis labels:** centered below each bar, Geist sans 11px 600 for category names.
|
||||
- **Value labels:** Geist Mono 8px above each bar. Focal bar label in accent; others in muted.
|
||||
- **Focal bar:** 1 bar max in accent fill/stroke. All others in `muted @ 0.15` fill + `muted` stroke.
|
||||
- **Y-axis line:** thin vertical `<line>` at x=80 from y=40 to y=420.
|
||||
|
||||
### Bar element pattern
|
||||
|
||||
```svg
|
||||
<!-- Opaque paper mask prevents bleed from background -->
|
||||
<rect x="X" y="Y" width="W" height="H" fill="#f5f5f5"/>
|
||||
<!-- Bar body -->
|
||||
<rect x="X" y="Y" width="W" height="H" fill="rgba(79,93,117,0.15)" stroke="#4f5d75" stroke-width="1"/>
|
||||
<!-- Value label above bar -->
|
||||
<text x="X+W/2" y="Y-8" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">VALUE</text>
|
||||
```
|
||||
|
||||
Focal bar: replace fill with `rgba(235,108,54,0.12)`, stroke with `#eb6c36`, label fill with `#eb6c36`.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- More than 8 bars without grouping (illegible at normal scale).
|
||||
- Truncated y-axis (not starting at 0) — distorts the magnitude comparison.
|
||||
- Accent on more than 1 bar ("everything is important" = nothing is).
|
||||
- 3-D bar extrusion — no shadows, no depth.
|
||||
- Category labels rotated more than 45°; prefer short labels or horizontal chart instead.
|
||||
|
||||
## Variants
|
||||
|
||||
- **Grouped bars:** two bars per category, side by side. Use `accent` for the primary series and `series-1` for the secondary. Max 2 groups.
|
||||
- **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.
|
||||
|
||||
## Examples
|
||||
|
||||
- `assets/example-bar.html` — minimal light
|
||||
- `assets/example-bar-dark.html` — minimal dark
|
||||
- `assets/example-bar-full.html` — full editorial
|
||||
@@ -0,0 +1,374 @@
|
||||
# Data Flow
|
||||
|
||||
**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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 1. Inputs — the parameter contract
|
||||
|
||||
```yaml
|
||||
lanes: # 1..4 horizontal swimlanes (top to bottom)
|
||||
- { name: ["DATA", "ADMINS"], key: "ADM" }
|
||||
- { name: ["DATA", "ENGINEERS"], key: "ENG" }
|
||||
- { name: ["DATA", "SCIENTISTS"], key: "SCI" }
|
||||
- { name: ["DATA", "CONSUMERS"], key: "CON" }
|
||||
|
||||
steps: # 1..6 columns (left to right)
|
||||
- { number: "01", label: "COLLECT" }
|
||||
- { number: "02", label: "STORE" }
|
||||
- { number: "03", label: "TRANSFORM" }
|
||||
- { number: "04", label: "ANALYZE", focal: true } # focal step header chip — accent fill
|
||||
- { number: "05", label: "PUBLISH" }
|
||||
|
||||
nodes: # explicit per-cell entries; empty cells render nothing
|
||||
- { lane: "ADM", step: 0, title: "Project Setup", sub: "create · assign roles", tool: "Platform console" }
|
||||
- { lane: "ADM", step: 1, title: "Access Control", sub: "bucket policies · LDAP", tool: "MinIO · LDAP console",
|
||||
color: "#b85450" } # tinted rust-red to flag governance/identity concern
|
||||
- { lane: "ENG", step: 0, title: "Source Ingest", sub: "ext. sources → raw", tool: "NiFi · API · SFTP",
|
||||
chips: {in: "WB", out: "DB"} } # web payload in, dataset out
|
||||
- { lane: "ENG", step: 1, title: "Raw Store", sub: "raw landing zones", tool: "MinIO raw",
|
||||
chips: {in: "DB", out: "DB"} } # raw stays raw inside the landing zone
|
||||
- { lane: "ENG", step: 2, title: "Clean & Stage", sub: "raw → staging → anon", tool: "NiFi · Trino",
|
||||
chips: {in: "DB", out: "TB"} } # raw dataset → analysis-ready table
|
||||
- { lane: "SCI", step: 3, title: "Explore & Model", sub: "anon data → insights", tool: "JupyterHub · Trino",
|
||||
chips: {in: "TB", out: "FL"}, focal: true } # focal — table in, file/report out
|
||||
- { lane: "SCI", step: 4, title: "Publish Findings", sub: "models → dashboards", tool: "Superset · Reports",
|
||||
chips: {in: "FL", out: "FL"} } # report in, report out (pass-through to publish)
|
||||
- { lane: "CON", step: 4, title: "Query Insights", sub: "aggregated views", tool: "Trino (read-only)",
|
||||
chips: {in: "TB", out: "TB"} } # consumers read tables, hand off tables
|
||||
|
||||
arrows: # explicit edges; styles bind to topology (see §3)
|
||||
- { from: {lane: "ADM", step: 0}, to: {lane: "ADM", step: 1}, style: "muted" }
|
||||
- { from: {lane: "ADM", step: 0}, to: {lane: "ENG", step: 0}, style: "trigger" } # dashed governance
|
||||
- { from: {lane: "ADM", step: 1}, to: {lane: "ENG", step: 1}, style: "trigger" }
|
||||
- { from: {lane: "ENG", step: 0}, to: {lane: "ENG", step: 1}, style: "muted" }
|
||||
- { from: {lane: "ENG", step: 1}, to: {lane: "ENG", step: 2}, style: "muted" }
|
||||
- { from: {lane: "ENG", step: 2}, to: {lane: "SCI", step: 3}, style: "accent", # focal cross-role
|
||||
label: "anon data" }
|
||||
- { from: {lane: "SCI", step: 3}, to: {lane: "SCI", step: 4}, style: "muted" }
|
||||
- { from: {lane: "SCI", step: 4}, to: {lane: "CON", step: 4}, style: "link" } # teal: published
|
||||
|
||||
dark: false
|
||||
```
|
||||
|
||||
**Reserved field semantics:**
|
||||
- `lanes[k].key` — the 3-letter role chip text (e.g., `ADM`, `ENG`, `SCI`, `CON`). Used inside every node in that lane.
|
||||
- `lanes[k].name` — two-line lane label; both lines use the uppercase `eyebrow` role.
|
||||
- `steps[j].focal: true` — exactly **one** step may declare this. Header chip renders in accent.
|
||||
- `nodes[i].focal: true` — exactly **one** node may declare this. Renders with accent border (§5).
|
||||
- `nodes[i].chips` — data-type chips for the node. Either form accepted:
|
||||
- **Object form (preferred):** `{in: "<CODE>", out: "<CODE>"}` — explicit input/output semantic. Either side optional.
|
||||
- **Array form:** `["<INPUT_CODE>", "<OUTPUT_CODE>"]` — 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
|
||||
<defs>
|
||||
<pattern id="dots" width="22" height="22" patternUnits="userSpaceOnUse">
|
||||
<circle cx="11" cy="11" r="0.8" fill="{ink @ 0.10}"/>
|
||||
</pattern>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
</defs>
|
||||
```
|
||||
|
||||
### 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 `<h1>` 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.
|
||||
@@ -0,0 +1,410 @@
|
||||
# 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
|
||||
<defs>
|
||||
<marker id="arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="#4f5d75"/></marker>
|
||||
<marker id="arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="#eb6c36"/></marker>
|
||||
<marker id="arrow-link" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="#2e5aa8"/></marker>
|
||||
<marker id="arrow-sm" markerWidth="6" markerHeight="5" refX="5" refY="2.5" orient="auto"><polygon points="0 0, 6 2.5, 0 5" fill="#4f5d75"/></marker>
|
||||
<marker id="arrow-dim" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="rgba(45,49,66,0.45)"/></marker>
|
||||
</defs>
|
||||
```
|
||||
|
||||
### 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 `<line>` / `<path>`. 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 `<g id="ico-…">` in `<defs>`, 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 `<symbol>` 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.
|
||||
@@ -0,0 +1,379 @@
|
||||
# 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`.
|
||||
@@ -0,0 +1,45 @@
|
||||
# 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
|
||||
<!-- Non-focal task -->
|
||||
<rect x="X_start" y="ROW_Y+8" width="DURATION_PX" height="24" rx="4"
|
||||
fill="rgba(79,93,117,0.15)" stroke="#4f5d75" stroke-width="1"/>
|
||||
<text x="X_start+8" y="ROW_Y+25" fill="#2d3142" font-size="10" font-weight="600"
|
||||
font-family="'Geist', sans-serif">Task name</text>
|
||||
|
||||
<!-- Focal task -->
|
||||
<rect x="X_start" y="ROW_Y+8" width="DURATION_PX" height="24" rx="4"
|
||||
fill="rgba(235,108,54,0.12)" stroke="#eb6c36" stroke-width="1"/>
|
||||
<text x="X_start+8" y="ROW_Y+25" fill="#eb6c36" font-size="10" font-weight="600"
|
||||
font-family="'Geist', sans-serif">Key task</text>
|
||||
```
|
||||
|
||||
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
|
||||
@@ -0,0 +1,458 @@
|
||||
# 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
|
||||
<defs>
|
||||
<marker id="arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="#4f5d75"/></marker>
|
||||
<marker id="arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="#eb6c36"/></marker>
|
||||
<marker id="arrow-sm" markerWidth="6" markerHeight="5" refX="5" refY="2.5" orient="auto"><polygon points="0 0, 6 2.5, 0 5" fill="#4f5d75"/></marker>
|
||||
<marker id="arrow-dim" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="rgba(45,49,66,0.45)"/></marker>
|
||||
</defs>
|
||||
```
|
||||
|
||||
### 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 `<path>` / `<line>`. 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 = 972`; 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 `<path>` and `<line>` connectors are emitted **before** any node `<rect>` (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.
|
||||
11. 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.
|
||||
@@ -0,0 +1,470 @@
|
||||
# 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
|
||||
<rect x="zone_x(i)" y="zone_y" width="zone_w(i)" height="zone_h"
|
||||
fill="{ink @ 0.02}" stroke="{ink @ 0.10}" stroke-width="0.8" rx="8"/>
|
||||
<!-- paper-masked break for the zone label -->
|
||||
<rect x="zone_x(i)+20" y="zone_y-8" width="{label_w}" height="16" fill="{paper}"/>
|
||||
<text x="zone_x(i)+24" y="zone_y+4" fill="{ink @ 0.40}"
|
||||
font-family="{eyebrow}" letter-spacing="0.14em">{name}</text>
|
||||
```
|
||||
|
||||
### 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
|
||||
<g transform="translate(comp_x + 12, comp_y + (comp_h - 24)/2)" color="{ink_for_kind}">
|
||||
<use href="#icon-{name}"/> <!-- or inline the SVG path from the catalog -->
|
||||
</g>
|
||||
```
|
||||
|
||||
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
|
||||
<rect x="left_pad" y="footer_y(k)" width="viewBox_w - 2*left_pad" height="footer_bar_h"
|
||||
fill="{ink @ 0.03}" stroke="{ink @ 0.18}" stroke-width="0.8" rx="8"/>
|
||||
<g transform="translate(left_pad + 20, footer_y(k) + (footer_bar_h - 24)/2)" color="{ink}">
|
||||
<use href="#icon-{name}"/>
|
||||
</g>
|
||||
<text x="left_pad + 56" y="footer_y(k) + 24" font-family="{node-name}" font-size="14" fill="{ink}">{name}</text>
|
||||
<text x="left_pad + 56" y="footer_y(k) + 40" font-family="{sublabel}" font-size="12" fill="{muted}">{sub}</text>
|
||||
```
|
||||
|
||||
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
|
||||
<!-- Same zone, adjacent component (same vertical column): single vertical line -->
|
||||
<line x1="{src_cx}" y1="{src_bot}" x2="{dst_cx}" y2="{dst_top}"
|
||||
stroke="…" stroke-width="…" marker-end="…"/>
|
||||
|
||||
<!-- Cross-zone or cross-row: exit right → H → Q-bend → V → enter top (or bottom) -->
|
||||
<path d="M {src_right},{src_cy} H {dst_cx - 8} Q {dst_cx},{src_cy} {dst_cx},{src_cy ± 8} V {dst_top_or_bottom}"
|
||||
fill="none" stroke="…" stroke-width="…" marker-end="…"/>
|
||||
```
|
||||
|
||||
- Use `{src_cy + 8}` and `V {dst_top}` when destination lies BELOW source.
|
||||
- Use `{src_cy − 8}` and `V {dst_bottom}` when destination lies ABOVE source.
|
||||
|
||||
### 3.2 Exit / entry sides (configurable; defaults below)
|
||||
|
||||
| Topology | Default exit side of source | Default entry side of destination |
|
||||
| --- | --- | --- |
|
||||
| Same zone, dst below | bottom | top |
|
||||
| Same zone, dst above | top | bottom |
|
||||
| Cross-zone, horizontal flow | right | top (or bottom, whichever is closer to src_cy) |
|
||||
| Vertical-orientation diagram | bottom | top |
|
||||
|
||||
A connector can override via `connectors[k].from_side` / `connectors[k].to_side` (`top | right | bottom | left`). **Backward references** (right→left in horizontal orientation, up in vertical orientation) are permitted only when at least one endpoint has `kind: external`, and must be `dashed: true`.
|
||||
|
||||
### 3.3 Markers MUST touch the destination rectangle
|
||||
|
||||
The path's last command ends at the destination's rectangle edge (`V {dst_top}` or `H {dst_left}`), **not** at the centroid. After applying `refX=7` on the marker, the triangle sits flush against the border. Stopping the line short of the edge — or sending it to the centroid and burying the arrowhead inside the rect — is a hard fail.
|
||||
|
||||
### 3.4 Style → stroke + marker
|
||||
|
||||
| `style` | Stroke color | Stroke width | Marker |
|
||||
| --- | --- | --- | --- |
|
||||
| `neutral` | `muted` | 1.0 | `url(#arrow)` |
|
||||
| `link` | `link` | 1.2 | `url(#arrow-link)` |
|
||||
| `accent` | `accent` | 1.4 | `url(#arrow-accent)` |
|
||||
|
||||
Add `stroke-dasharray="4 3"` when `dashed: true`.
|
||||
|
||||
**Defs block** (always emit all three):
|
||||
|
||||
```svg
|
||||
<defs>
|
||||
<marker id="arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="{muted}"/></marker>
|
||||
<marker id="arrow-link" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="{link}"/></marker>
|
||||
<marker id="arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="{accent}"/></marker>
|
||||
</defs>
|
||||
```
|
||||
|
||||
### 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
|
||||
<g transform="translate({label_cx}, {label_cy})">
|
||||
<rect x="-{w/2}" y="-9" width="{w}" height="18" rx="3" fill="{paper}" stroke="none"/>
|
||||
<use href="#icon-{icon}" x="-{w/2 + 4}" y="-6" width="12" height="12" color="{stroke_color}"/> <!-- if icon set -->
|
||||
<text x="{icon ? (-(w/2) + 22) : 0}" y="3" text-anchor="{icon ? 'start' : 'middle'}"
|
||||
font-family="{arrow-label}" font-size="9" font-weight="600"
|
||||
letter-spacing="0.08em" fill="{stroke_color}">{label}</text>
|
||||
</g>
|
||||
```
|
||||
|
||||
**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 `<defs>`; 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 `<line>` 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`.
|
||||
@@ -0,0 +1,44 @@
|
||||
# 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:** `<polyline>` 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):** `<polygon>` 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
|
||||
<!-- Focal series -->
|
||||
<polyline points="x0,y0 x1,y1 x2,y2 ..."
|
||||
fill="none" stroke="#eb6c36" stroke-width="1.8" stroke-linejoin="round"/>
|
||||
<!-- Dots at each point (focal only) -->
|
||||
<circle cx="x0" cy="y0" r="4" fill="#eb6c36"/>
|
||||
|
||||
<!-- Non-focal series -->
|
||||
<polyline points="x0,y0 x1,y1 ..."
|
||||
fill="none" stroke="#7c8f6f" stroke-width="1.2" stroke-linejoin="round"/>
|
||||
```
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- More than 5 series (visual mush — reduce or split).
|
||||
- Lines that don't start at a shared zero baseline unless explicitly annotated.
|
||||
- Smoothed/spline curves when the underlying data is sampled — polyline is honest.
|
||||
- Dots on every series when there are 4+ series (only focal gets dots).
|
||||
- Y-axis that doesn't include zero when the absolute magnitude matters.
|
||||
- Connecting discontinuous data segments without a visual gap.
|
||||
|
||||
## Examples
|
||||
|
||||
- `assets/example-line.html` — minimal light
|
||||
- `assets/example-line-dark.html` — minimal dark
|
||||
- `assets/example-line-full.html` — full editorial
|
||||
@@ -0,0 +1,356 @@
|
||||
# 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 `<foreignObject>` with an HTML `<div>` 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
|
||||
<foreignObject x="{field_x}" y="{value_top}" width="140" height="24">
|
||||
<div xmlns="http://www.w3.org/1999/xhtml"
|
||||
style="font-family: {sublabel}; color: {muted}; line-height: 1.25;">
|
||||
{field_value}
|
||||
</div>
|
||||
</foreignObject>
|
||||
```
|
||||
|
||||
The HTML namespace declaration on the `<div>` is required for SVG to render the inline content. Browsers and Playwright/Chromium render this faithfully; if your export target doesn't support `<foreignObject>` (some older Inkscape builds), hand-split long values into two `<tspan>` 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
|
||||
<path d="M {tier_cx(i)},{tier_y} C {tier_cx(i)},0 {tier_cx(i+1)},0 {tier_cx(i+1)},{tier_y}"
|
||||
fill="none" stroke="…" stroke-width="…" marker-end="…"/>
|
||||
```
|
||||
|
||||
Concrete for the canonical 5-tier shape (`tier_y = 80`, tier centers at x = 102, 290, 478, 666, 854):
|
||||
- 0→1: `M 102,80 C 102,0 290,0 290,80`
|
||||
- 1→2: `M 290,80 C 290,0 478,0 478,80`
|
||||
- 2→3: `M 478,80 C 478,0 666,0 666,80` (focal — accent)
|
||||
- 3→4: `M 666,80 C 666,0 854,0 854,80` (lifecycle — dashed)
|
||||
|
||||
The cubic geometry: anchor y = 80 (tier top), control y = 0 (top of viewBox). Curve peak at t=0.5 sits at y ≈ 20 (computed from `0.125·80 + 0.375·0 + 0.375·0 + 0.125·80 = 20`). Each arc spans one full tier-stride (188 px on the canonical layout), giving the connector a clearly visible vertical excursion.
|
||||
|
||||
**Marker orientation:** `marker-end` with `orient="auto"` rotates the arrow to match the path tangent at the endpoint. The control point sits directly above the anchor so the tangent at landing is straight **down** — the arrowhead enters the top-center of tier *i+1* cleanly, pointing into the header band.
|
||||
|
||||
**Chained anchors:** consecutive arcs share their meeting points (arc 0→1 ends at the same `(tier_cx(1), 80)` where arc 1→2 begins). Visually each tier's top-center acts as a "joint" — data arrives at the top of the card, gets transformed inside, and leaves out the top toward the next tier. The arrow-head plunge plus the next arc's straight-up emergence read as a single payload-handoff motion.
|
||||
|
||||
| `style` | Stroke | Width | Dash | Marker |
|
||||
|---|---|---|---|---|
|
||||
| `normal` | `muted` | 1.4 | — | `arrow` |
|
||||
| `focal` | `accent` | 1.6 | — | `arrow-accent` |
|
||||
| `lifecycle` | `muted` | 1.4 | `4,3` | `arrow` |
|
||||
|
||||
**Auto-style rules:**
|
||||
- If `promotions[k].to` references the **focal tier**, the style auto-promotes to `focal` (accent, width 1.6, `arrow-accent` marker).
|
||||
- If `promotions[k].to` references a tier with a **`color` override** (§4), the arrow inherits that hex — stroke = `C`, label fill = `C`, marker-end uses a color-matched marker (e.g., `arrow-yellow` for `#c9a23a`). Width stays at 1.4 — the color override is a "concern" signal, not a focal promotion. Lifecycle/dashed arrows keep their dash but adopt the color.
|
||||
- Focal wins if both apply (a colored tier marked focal still uses accent).
|
||||
|
||||
**Label inside the arc:**
|
||||
- Anchored at `(arc_peak_x(k), arc_label_y)` = `((arc_src_x + arc_dst_x) / 2, 50)`.
|
||||
- `arrow-label` role at 10px with `letter-spacing=0.08em`, uppercase. Color matches the arrow stroke.
|
||||
- **No mask rect needed** — the cubic curve peaks at y ≈ 20 and the label sits at y=50, well below the curve. The label floats inside the open space *enclosed* by the arc, reading "X transforms into Y" with the arc itself as the visual frame.
|
||||
|
||||
For shorter inter-tier gaps (if `tier_gap` is overridden below the default 16 px), the arc anchors `arc_inset` may need to shrink correspondingly to keep the arc visible.
|
||||
|
||||
### 2.5 Path row (bottom, optional)
|
||||
|
||||
Up to **2** write-method cards. The canonical 5-tier shape (with `arc_band_h = 80`):
|
||||
|
||||
```
|
||||
path_y = 476 # tier_y + tier_h + path_gap = 80 + 380 + 16
|
||||
path_h = 56
|
||||
path_x[0] = 16
|
||||
path_w[0] = 460
|
||||
path_x[1] = 16 + 460 + 16 = 492
|
||||
path_w[1] = 460
|
||||
```
|
||||
|
||||
(Both paths land 460-wide despite the viewBox being 1040 — the right pad is taken from the card's tier strip, not the path strip. Keep `path_w=460` for the canonical 5-tier shape. For other tier counts, derive `path_w = (viewBox_w - 2*left_pad - path_gap) / 2`.)
|
||||
|
||||
Per-card content:
|
||||
- Container rect: white fill, `ink @ 0.20` stroke width 1, `rx=6`.
|
||||
- Tag chip: rect at `(path_x + 8, path_y + 6)`, `h=12 rx=2`, fill transparent, stroke `ink @ 0.30` width 0.8. Tag text centered inside in the `eyebrow` role with letter-spacing 0.08em, ink.
|
||||
- Title at `(path_x + 80, path_y + 30)`: `node-name` role at 11px, ink.
|
||||
- Sub at `(path_x + 80, path_y + 46)`: `sublabel` role, muted.
|
||||
|
||||
---
|
||||
|
||||
## 3. Connector rules (mandatory)
|
||||
|
||||
Three styles, bound to topology. Mirror §3 of `type-process.md` so the rule reads identically.
|
||||
|
||||
```svg
|
||||
<defs>
|
||||
<marker id="arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="{muted}"/></marker>
|
||||
<marker id="arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="{accent}"/></marker>
|
||||
<!-- Per-color markers: declare one per custom tier color in use. -->
|
||||
<marker id="arrow-yellow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="#c9a23a"/></marker>
|
||||
</defs>
|
||||
```
|
||||
|
||||
Add a new `<marker>` 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.
|
||||
@@ -0,0 +1,495 @@
|
||||
# Process
|
||||
|
||||
**Best for:** sequential business processes with multiple actors/divisions where the reader needs to see *who* does *what*, *what data* enters and leaves each step, and *which tools* are used — not just the step order. Covers responsibility audits, data-quality gate reviews, cross-divisional handoff maps, and end-to-end workflow documentation.
|
||||
|
||||
Prefer swimlane (simpler) when the data types and tools don't matter. Prefer process when each step's input/output payload and responsible team must be legible at a glance.
|
||||
|
||||
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-data-flow.md` so color override, IN/OUT chip semantic, and reproducibility checklist read identically across types.
|
||||
|
||||
---
|
||||
|
||||
## 1. Inputs — the parameter contract
|
||||
|
||||
```yaml
|
||||
lanes: # 1..6 horizontal swimlanes (top to bottom)
|
||||
- { name: ["RD&E"], key: "RDE" }
|
||||
- { name: ["IT"], key: "IT" }
|
||||
- { name: ["FIELD", "SERVICES"], key: "FLD" }
|
||||
- { name: ["SURVEY", "SERVICES"], key: "SVY" }
|
||||
- { name: ["HOUSEHOLD", "UNIT"], key: "HHU" }
|
||||
- { name: ["COMMS &", "MARKETING"], key: "CMM" }
|
||||
|
||||
steps: # 1..12 vertical step columns (left to right)
|
||||
- { number: "1", label: "Design" }
|
||||
- { number: "2", label: "Build" }
|
||||
- { number: "3", label: "Test", focal: true } # focal step header chip — accent fill
|
||||
- { number: "4", label: "Train" }
|
||||
# ... up to 12
|
||||
|
||||
nodes: # explicit per-cell entries; empty cells render nothing
|
||||
- { lane: "RDE", step: 0, title: "Survey design", sub: "questionnaire · sampling", tool: "Excel · CSPro",
|
||||
chips: {in: null, out: "FL"} } # first step has no input chip
|
||||
- { lane: "IT", step: 1, title: "Build app", sub: "form + validation", tool: "CSPro · scripts",
|
||||
chips: {in: "FL", out: "TB"}, color: "#5a7d9a" } # slate-blue — data quality concern
|
||||
- { lane: "RDE", step: 2, title: "Pilot test", sub: "field debug", tool: "tablet · script",
|
||||
chips: {in: "TB", out: "TB"}, focal: true } # focal node — accent border
|
||||
- { lane: "FLD", step: 3, title: "Train enumerators", sub: "protocols · safety", tool: "manual",
|
||||
chips: {in: "TB", out: "LS"}, color: "#b85450" } # rust-red — governance / training
|
||||
# ... etc
|
||||
|
||||
arrows: # explicit edges; styles bind to topology (see §3)
|
||||
- { from: {lane: "RDE", step: 0}, to: {lane: "IT", step: 1}, style: "normal" }
|
||||
- { from: {lane: "IT", step: 1}, to: {lane: "RDE", step: 2}, style: "focal-in" } # accent — into focal
|
||||
- { from: {lane: "RDE", step: 2}, to: {lane: "FLD", step: 3}, style: "focal-out" } # accent — out of focal
|
||||
- { from: {lane: "RDE", step: 2}, to: {lane: "IT", step: 1}, style: "trigger" } # dashed trigger
|
||||
# ... etc
|
||||
|
||||
dark: false
|
||||
```
|
||||
|
||||
**Reserved field semantics:**
|
||||
- `lanes[k].key` — the 3-letter role badge text shown inside every node in that lane.
|
||||
- `lanes[k].name` — 1 or 2 line lane label; uppercase mono.
|
||||
- `steps[j].focal: true` — exactly **one** step may declare this. Header chip renders in accent.
|
||||
- `nodes[i].focal: true` — exactly **one** node may declare this. Renders with accent border (§5).
|
||||
- `nodes[i].chips` — `{in: "<CODE>", out: "<CODE>"}` object (either side `null` to omit). Codes from §8. **Skip** the input chip on the first step's nodes, **skip** the output chip on the last step's nodes (no upstream / downstream).
|
||||
- `nodes[i].color` — optional **per-node color override**. Any valid `"#hex"` string; the §4 palette is recommended for cross-diagram consistency.
|
||||
|
||||
---
|
||||
|
||||
## 2. Layout formulas — deterministic geometry
|
||||
|
||||
```
|
||||
label_col_w = 140
|
||||
step_slot_w = 112 # 100-px node + 12-px corridor
|
||||
right_pad = 28
|
||||
n_steps = len(steps)
|
||||
n_lanes = len(lanes)
|
||||
|
||||
# Canvas
|
||||
viewBox_w = label_col_w + n_steps * step_slot_w + right_pad # 11 steps → 1400
|
||||
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 # 6 lanes, no colors → 596; with → 616
|
||||
|
||||
# Header strip (top)
|
||||
chip_y = 8
|
||||
chip_w = 16 # 20 if step.number has 2 digits
|
||||
chip_h = 16
|
||||
chip_rx = 8 # pill
|
||||
|
||||
# Lane positions
|
||||
lane_y_top(k) = header_h + k * lane_h # 36, 116, 196, 276, 356, 436
|
||||
lane_y_mid(k) = lane_y_top(k) + lane_h/2 # 76, 156, 236, 316, 396, 476
|
||||
lane_label_x = label_col_w / 2 # 70
|
||||
|
||||
# Step / node centers
|
||||
step_cx(j) = label_col_w + 8 + j * step_slot_w + node_w/2 # 198, 310, 422, ...
|
||||
# (8-px gutter inside content area)
|
||||
|
||||
# Nodes
|
||||
node_w = 100
|
||||
node_h = 64
|
||||
node_x(j) = step_cx(j) - node_w/2
|
||||
node_y(k) = lane_y_top(k) + (lane_h - node_h)/2 # 8-px top/bottom margin inside lane
|
||||
|
||||
# Legend strip (bottom)
|
||||
legend_y_top = header_h + n_lanes * lane_h
|
||||
legend_row_y = [legend_y_top + 16, legend_y_top + 37,
|
||||
legend_y_top + 58, legend_y_top + 79]
|
||||
```
|
||||
|
||||
### 2.1 Background structure
|
||||
|
||||
- Paper fill across full viewBox.
|
||||
- Dot pattern: 22×22 grid, `circle r=0.8`, `fill rgba(45,49,66,0.10)`. Opacity 0.55.
|
||||
- Alternating lane tints: odd-indexed lanes (0, 2, …) receive `rgba(45,49,66,0.018)` fill from `x=140` to `viewBox_w`.
|
||||
- Lane dividers: horizontal hairlines at every `lane_y_top(k)` and at `legend_y_top`; stroke `rgba(45,49,66,0.12)` width 0.8.
|
||||
- Label column right border: vertical hairline at `x = label_col_w`, stroke `rgba(45,49,66,0.20)` width 1, from `y = header_h` to `y = legend_y_top`.
|
||||
|
||||
### 2.2 Step header chip + label
|
||||
|
||||
Per step `j`:
|
||||
|
||||
```
|
||||
chip_w(j) = 20 if len(step.number) >= 2 else 16
|
||||
chip_x(j) = step_cx(j) - chip_w(j)/2
|
||||
number_anchor = (step_cx(j), chip_y + 11)
|
||||
label_anchor = (step_cx(j), 32) # 8-px gap below chip
|
||||
```
|
||||
|
||||
**Chip** (the numbered pill at the top of each column):
|
||||
- Default fill: `rgba(45,49,66,0.12)`, number text ink.
|
||||
- Focal fill: `rgba(235,108,54,0.20)`, number text accent (§5).
|
||||
- Per-step `color` override (§4): replaces the fill with `rgba(C, 0.20)` and the number fill with `C`.
|
||||
|
||||
**Label** (the uppercase mono text below the chip):
|
||||
- Renders `steps[j].label` (uppercased), anchored at `label_anchor`.
|
||||
- Font: Geist Mono 6 px, weight 500, `letter-spacing="0.12em"`, `text-anchor="middle"`.
|
||||
- Default fill: muted (`#4f5d75` light / `#bfc0c0` dark).
|
||||
- Focal fill: accent (`#eb6c36` light / `#f08a59` dark).
|
||||
- Per-step `color` override: fill = `C` (matches the chip number color).
|
||||
- Keep labels short (≤ 9 chars). Long labels truncate; if you need more, abbreviate.
|
||||
|
||||
### 2.3 Lane labels
|
||||
|
||||
One or two-line mono label, all uppercase, letter-spacing 0.08em, font-size 8, fill muted. Centered at `(lane_label_x, lane_y_mid(k))`:
|
||||
- Single-line: anchored at `(lane_label_x, lane_y_mid(k) + 4)`
|
||||
- Two-line: lines at `(lane_label_x, lane_y_mid(k) - 4)` and `(lane_label_x, lane_y_mid(k) + 4)`
|
||||
|
||||
Per-lane `color` override (§4): replaces the label fill with `C` and the lane stripe tint with `rgba(C, 0.04)`.
|
||||
|
||||
### 2.4 Node content layout (inside the 100×64 rect)
|
||||
|
||||
```
|
||||
role_chip rect 14×10 at (node_x+4, node_y+4), rx=2
|
||||
role_chip_text centered at (node_x+11, node_y+12), font-size=6, weight=600
|
||||
# text = lanes[k].key (3-letter lane code)
|
||||
title centered at (step_cx(j), node_y+26), font-size=9 sans semibold
|
||||
in→out centered at (step_cx(j), node_y+40), font-size=6.5 mono muted
|
||||
tool centered at (step_cx(j), node_y+52), font-size=6.5 mono soft
|
||||
data chip IN rect 16×8 at (node_x+4, node_y+54), rx=2 # payload entering
|
||||
data chip OUT rect 16×8 at (node_x+80, node_y+54), rx=2 # payload leaving
|
||||
```
|
||||
|
||||
**Role chip text rule:** the badge inside each node renders `lanes[k].key` where `k` is the node's lane index — **not** the step number (the step number already lives in the column header chip at the top, §2.2). Showing the lane key as the node badge gives each node a self-contained "who" identifier that survives when a single node is excerpted out of context. Mirrors the same rule in `type-data-flow.md` §2.4.
|
||||
|
||||
Empty cells (no node entry) render **nothing**. No placeholder rect, no role chip, no label.
|
||||
|
||||
**Chip-vs-tool-text collision rule:** chips sit at `node_y + 54..62`; tool text baseline is at `node_y + 52`. If a node has a two-line title (rare), increase node_h to 72 OR omit the chips for that node. Default behaviour: omit chips on collision.
|
||||
|
||||
---
|
||||
|
||||
## 3. Connector rules (mandatory)
|
||||
|
||||
Three styles, bound to topology. Connectors drawn **before** all node rects (z-order rule).
|
||||
|
||||
| `style` | Stroke | Width | Dash | Marker | When required |
|
||||
|---|---|---|---|---|---|
|
||||
| `normal` | `#4f5d75` (muted) | 1.0 | — | `arrow` | Standard data hand-off between steps or actors. Unlabelled. |
|
||||
| `focal-in` / `focal-out` | `#eb6c36` (accent) | 1.2 | — | `arrow-accent` | Every edge whose endpoint is the focal node (`focal-in`) or origin is the focal node (`focal-out`). |
|
||||
| `trigger` | `#4f5d75` (muted) | 1.0 | `4,3` | `arrow-sm` | Orchestration trigger (scheduler → tool, manual override → upstream step). Unlabelled. |
|
||||
|
||||
**Defs block** (required, three markers):
|
||||
|
||||
```svg
|
||||
<defs>
|
||||
<pattern id="dots" width="22" height="22" patternUnits="userSpaceOnUse">
|
||||
<circle cx="11" cy="11" r="0.8" fill="rgba(45,49,66,0.10)"/>
|
||||
</pattern>
|
||||
<marker id="arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="#4f5d75"/></marker>
|
||||
<marker id="arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="#eb6c36"/></marker>
|
||||
<marker id="arrow-sm" markerWidth="6" markerHeight="5" refX="5" refY="2.5" orient="auto"><polygon points="0 0, 6 2.5, 0 5" fill="#4f5d75"/></marker>
|
||||
</defs>
|
||||
```
|
||||
|
||||
### 3.1 Routing rules (non-negotiable)
|
||||
|
||||
**Single-bend right-angle:** exit RIGHT → corridor → enter TOP (↓ destination below) or BOTTOM (↑ destination above).
|
||||
|
||||
- Source-side: exit at `(node_x + 100, lane_y_mid(src_lane))` — node's right edge, vertical center.
|
||||
- Destination-side: enter at `(step_cx(dst_step), node_y(dst_lane))` for downward, or `(step_cx(dst_step), node_y(dst_lane) + 64)` for upward.
|
||||
- Corner radius: 8-px Q-bezier at the bend.
|
||||
- Same-lane edges (rare — same lane, adjacent steps): horizontal `<line>` from src right to dst left.
|
||||
- **No diagonals.** **No left-side entry.** **No exit from the top/bottom of a node.**
|
||||
|
||||
```svg
|
||||
<!-- Downward (destination lane > source lane) -->
|
||||
<path d="M {rx},{src_cy} H {dst_cx - 8} Q {dst_cx},{src_cy} {dst_cx},{src_cy + 8} V {dst_top}"
|
||||
fill="none" stroke="…" stroke-width="…" marker-end="…"/>
|
||||
|
||||
<!-- Upward (destination lane < source lane) -->
|
||||
<path d="M {rx},{src_cy} H {dst_cx - 8} Q {dst_cx},{src_cy} {dst_cx},{src_cy - 8} V {dst_bottom}"
|
||||
fill="none" stroke="…" stroke-width="…" marker-end="…"/>
|
||||
|
||||
<!-- Same lane (adjacent step) -->
|
||||
<line x1="{src_right}" y1="{lane_cy}" x2="{dst_left}" y2="{lane_cy}"
|
||||
stroke="…" stroke-width="…" marker-end="…"/>
|
||||
```
|
||||
|
||||
- **Z-order:** all `<path>` and `<line>` connectors emitted **before** any node `<rect>`.
|
||||
- **Markers:** exactly one `marker-end` per path. Never `marker-start`.
|
||||
- **Labels:** all process arrows are unlabelled by default. The step number + the actor lane carry the semantic; a label on every arrow is noise. Only label an arrow if it represents a non-step concept (re-test loop, escalation) — then use a paper-masked rect behind 6.5-px mono text.
|
||||
|
||||
### 3.2 Crossings
|
||||
|
||||
Avoid. The corridor x position (8 px before destination node) is the only routing column — if two arrows would cross there, **swap step assignments** or **split into two diagrams** rather than introducing a bend-around. Crossings hide the underlying control flow.
|
||||
|
||||
---
|
||||
|
||||
## 4. Component color override
|
||||
|
||||
Any node, lane, or step accepts an optional `color: "#hex"`. Mirrors `type-data-flow.md` §4 and `type-high-level.md` §3.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 (in → out) | **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 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)` 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.
|
||||
- **Subtitle and tool labels stay muted** regardless of any component `color`.
|
||||
|
||||
### 4.5 Semantic palette (recommended)
|
||||
|
||||
Same palette as `type-high-level.md`, `type-dp-integration.md`, `type-data-flow.md`:
|
||||
|
||||
- `#b85450` rust-red — Security / Identity / Governance (access control, training, approvals)
|
||||
- `#5a7d9a` slate-blue — Observability / Quality (data quality gates, validation, monitoring)
|
||||
- `#7a8c47` olive-green — Data Products / Publication (consumer-ready outputs, releases)
|
||||
- `#8c6d3f` warm-brown — Backup / DR / Archive
|
||||
|
||||
---
|
||||
|
||||
## 5. Focal rule
|
||||
|
||||
The process diagram has three focal slots, exactly one entry each:
|
||||
|
||||
- **One focal step** (`steps[j].focal: true`) — typically the analytical or decision pivot (Test, Approve, Validate). Header chip and legend chip render in accent.
|
||||
- **One focal node** (`nodes[i].focal: true`) — the node that *receives* the critical handoff. Accent border + accent role chip + ink title (title text stays ink so it's still readable; only the border + role chip carry the accent).
|
||||
- **One focal arrow set** (`style: focal-in` and `focal-out`) — edges into and out of the focal node. Accent solid strokes.
|
||||
|
||||
If zero or >1 of any focal slot are declared, halt and ask the user.
|
||||
|
||||
---
|
||||
|
||||
## 6. Dark mode
|
||||
|
||||
| Token | Light | Dark |
|
||||
|---|---|---|
|
||||
| Paper | `#f5f5f5` | `#2d3142` |
|
||||
| Ink | `#2d3142` | `#f5f5f5` |
|
||||
| Muted | `#4f5d75` | `#bfc0c0` |
|
||||
| Soft | `#7a8399` | `#8e98ac` |
|
||||
| Accent | `#eb6c36` | `#f08a59` |
|
||||
| Dot pattern | `rgba(45,49,66,0.10)` | `rgba(245,245,245,0.10)` |
|
||||
| Lane tint | `rgba(45,49,66,0.018)` | `rgba(245,245,245,0.025)` |
|
||||
| Dividers | `rgba(45,49,66,0.12)` | `rgba(245,245,245,0.12)` |
|
||||
| Label col divider | `rgba(45,49,66,0.20)` | `rgba(245,245,245,0.22)` |
|
||||
| Default chip fill | `rgba(45,49,66,0.12)` | `rgba(245,245,245,0.12)` |
|
||||
| Focal chip fill | `rgba(235,108,54,0.20)` | `rgba(240,138,89,0.22)` |
|
||||
| Default node fill | white | `rgba(245,245,245,0.04)` |
|
||||
| Default node stroke | `rgba(45,49,66,0.25)` | `rgba(245,245,245,0.20)` |
|
||||
| Focal node fill | `rgba(235,108,54,0.08)` | `rgba(240,138,89,0.12)` |
|
||||
| Focal node 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 {viewBox_w} {viewBox_h}"` derived 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. Focal-touching arrows use `style: focal-in` / `focal-out` (accent).
|
||||
8. All other arrows `style: normal` (muted solid) or `style: trigger` (muted dashed). Unlabelled by default.
|
||||
9. All arrows emitted before any node rect (z-order rule).
|
||||
10. Single-bend right-angle routing only — exit right, enter top/bottom. 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`. Input chip skipped on first step's nodes, output chip skipped on last step's nodes.
|
||||
|
||||
---
|
||||
|
||||
## 8. Data-type chips reference (input + output)
|
||||
|
||||
Same catalog as `type-data-flow.md` §8.
|
||||
|
||||
- **Input chip** at `(node_x+4, node_y+54)` — bottom-**left**. Payload entering the node.
|
||||
- **Output chip** at `(node_x+80, node_y+54)` — bottom-**right**. Payload leaving the node.
|
||||
- Either chip may be omitted (first/last step, unknown payload).
|
||||
|
||||
### Chip codes
|
||||
|
||||
| Code | Color (light) | Color (dark) | Meaning |
|
||||
|------|---------------|--------------|---------|
|
||||
| `LS` | `#7c8f6f` sage | `#9caf8f` | List / assignment / task |
|
||||
| `DB` | `#5e7a9b` dusty-blue | `#82a0c0` | Dataset / tabular records |
|
||||
| `TB` | `#b8915a` mustard | `#d3ad7a` | Table (analysis-ready) |
|
||||
| `FL` | `#9c6b50` rust-brown | `#b88670` | File / document / report |
|
||||
| `WB` | `#6e6479` slate | `#8d8298` | Web / press / public release |
|
||||
| N/A | omit chip entirely | — | Unknown or not applicable |
|
||||
|
||||
Text inside chip: white, font-size 5, weight 700, mono.
|
||||
|
||||
Data-type chip colors are a **separate semantic axis** from the per-node color override (§4). Chip colors describe *payload format*; node color describes *concern type*. A node can have both an `out: TB` mustard chip and a rust-red border simultaneously.
|
||||
|
||||
---
|
||||
|
||||
## 9. Legend (3- or 4-row strip)
|
||||
|
||||
Each row introduced by a category label at `x = label_col_w + 4` (= 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.
|
||||
|
||||
- **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 muted mono: `left chip = input · right chip = output`.
|
||||
- **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.
|
||||
- **Row 4 — `FLOW`** (position depends on whether `CONCERN` row exists): one segment per arrow style actually used, with marker + label.
|
||||
|
||||
---
|
||||
|
||||
## 10. Complexity budget
|
||||
|
||||
| Dimension | Max |
|
||||
|---|---|
|
||||
| Lanes (actors) | 6 |
|
||||
| Steps | 12 |
|
||||
| Nodes per lane | Nodes = active steps only — empty cells are invisible |
|
||||
| Labelled arrows | 0 by default (label only for non-step concepts) |
|
||||
| Data-type chips per node | 2 (input + output) |
|
||||
| Custom-colored elements (§4) | 3 (in addition to focal node + focal step) |
|
||||
|
||||
Above 6 lanes or 12 steps: split into two diagrams (overview + detail).
|
||||
|
||||
---
|
||||
|
||||
## 11. Anti-patterns
|
||||
|
||||
- **Placeholder empty cells** — if an actor doesn't participate in a step, leave the cell empty (no box, no text).
|
||||
- **Diagonal arrows** — every connector must have exactly one right-angle bend. No direct straight lines between nodes in different lanes.
|
||||
- **Left/right port entry on a vertical-dominant arrow** — always exit right, enter top or bottom.
|
||||
- **More than one focal step / focal node** — pick the single most critical operation.
|
||||
- **Unlabelled lanes** — every swimlane must identify its actor.
|
||||
- **All arrows the same style** — orchestration triggers must be dashed to distinguish them from data-flow connectors.
|
||||
- **`color` override on a focal element** — ignored. Accent always wins.
|
||||
- **Custom-colored arrows** — connectors 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.
|
||||
- **Data-type chips in a double-line-name node** — skip the chips or shorten the name to one line.
|
||||
- **More than 12 steps without splitting** — use an overview + detail pair.
|
||||
|
||||
---
|
||||
|
||||
## 12. Worked example — full YAML for `example-process-extended.html`
|
||||
|
||||
The extended example diagram is fully described by the following inputs. Every coordinate in the rendered SVG is derivable from this block via §2 + §3 + §4. This is the canonical proof that the parametric contract works end-to-end.
|
||||
|
||||
```yaml
|
||||
# Quarterly survey — end-to-end workflow (extended variant)
|
||||
# 6 lanes × 11 steps, 1 focal step + 1 focal node + 3 custom-colored nodes
|
||||
|
||||
lanes:
|
||||
- { name: ["RD&E"], key: "RDE" }
|
||||
- { name: ["IT"], key: "IT" }
|
||||
- { name: ["FIELD", "SERVICES"], key: "FLD" }
|
||||
- { name: ["SURVEY", "SERVICES"], key: "SVY" }
|
||||
- { name: ["HOUSEHOLD", "UNIT"], key: "HHU" }
|
||||
- { name: ["COMMS &", "MARKETING"], key: "CMM" }
|
||||
|
||||
steps:
|
||||
- { number: "1", label: "Design" }
|
||||
- { number: "2", label: "Assign" }
|
||||
- { number: "3", label: "Collect", focal: true } # focal step header chip
|
||||
- { number: "4", label: "Review" }
|
||||
- { number: "5", label: "Validate" }
|
||||
- { number: "6", label: "Weight" }
|
||||
- { number: "7", label: "Clean" }
|
||||
- { number: "8", label: "Tabulate" }
|
||||
- { number: "9", label: "Approve" }
|
||||
- { number: "10", label: "Publish" }
|
||||
- { number: "11", label: "Upload" }
|
||||
|
||||
nodes:
|
||||
- { lane: "RDE", step: 0, title: "Sample Design", sub: "Census data → Sample",
|
||||
tool: "SAS · Survey Solutions", chips: {in: null, out: "LS"} } # first step: no input chip
|
||||
- { lane: "IT", step: 1, title: "Field Assignment", sub: "Sample → Field tasks",
|
||||
tool: "Survey Solutions", chips: {in: "LS", out: "LS"} }
|
||||
- { lane: "FLD", step: 2, title: "Data Collection", sub: "→ 10,464 dwellings",
|
||||
tool: "Survey Solutions", chips: {in: "LS", out: "DB"}, focal: true } # focal node
|
||||
- { lane: "SVY", step: 3, title: "HQ Review", sub: "Submissions → Approved",
|
||||
tool: "Survey Sol. HQ", chips: {in: "DB", out: "DB"}, color: "#b85450" } # rust-red · governance
|
||||
- { lane: "IT", step: 4, title: "Error Checks", sub: "Approved → Cleaned",
|
||||
tool: "SAS · Scripts", chips: {in: "DB", out: "DB"}, color: "#5a7d9a" } # slate-blue · data quality
|
||||
- { lane: "RDE", step: 5, title: "Weight Calculation", sub: "Cleaned → Weighted",
|
||||
tool: "SAS", chips: null } # 2-line title — chips skipped
|
||||
- { lane: "HHU", step: 6, title: "2° Cleaning", sub: "Weighted → Analysis",
|
||||
tool: "SAS · R · SPSS", chips: {in: "DB", out: "TB"} }
|
||||
- { lane: "HHU", step: 7, title: "Tables + Brief", sub: "Analysis → Tables",
|
||||
tool: "Excel · SAS", chips: {in: "TB", out: "FL"} }
|
||||
- { lane: "CMM", step: 8, title: "Stats Review", sub: "Tables → Approved",
|
||||
tool: "Internal review", chips: {in: "FL", out: "FL"} }
|
||||
- { lane: "CMM", step: 9, title: "Public Release", sub: "Approved → Public",
|
||||
tool: "Press conference", chips: {in: "FL", out: "WB"}, color: "#7a8c47" } # olive-green · data products
|
||||
- { lane: "IT", step: 10, title: "Upload NatStat / SDMX", sub: "Results → Published",
|
||||
tool: "Web · SDMX API", chips: null } # 2-line title — chips skipped
|
||||
|
||||
arrows:
|
||||
- { from: {lane: "RDE", step: 0}, to: {lane: "IT", step: 1}, style: "normal" }
|
||||
- { from: {lane: "IT", step: 1}, to: {lane: "FLD", step: 2}, style: "focal-in" } # → focal
|
||||
- { from: {lane: "FLD", step: 2}, to: {lane: "SVY", step: 3}, style: "focal-out" } # ← focal
|
||||
- { from: {lane: "SVY", step: 3}, to: {lane: "IT", step: 4}, style: "normal" } # upward
|
||||
- { from: {lane: "IT", step: 4}, to: {lane: "RDE", step: 5}, style: "normal" } # upward
|
||||
- { from: {lane: "RDE", step: 5}, to: {lane: "HHU", step: 6}, style: "normal" } # downward, skips 2 lanes
|
||||
- { from: {lane: "HHU", step: 6}, to: {lane: "HHU", step: 7}, style: "normal" } # same lane
|
||||
- { from: {lane: "HHU", step: 7}, to: {lane: "CMM", step: 8}, style: "normal" }
|
||||
- { from: {lane: "CMM", step: 8}, to: {lane: "CMM", step: 9}, style: "normal" } # same lane
|
||||
- { from: {lane: "CMM", step: 9}, to: {lane: "IT", step: 10}, style: "normal" } # upward, skips 4 lanes
|
||||
|
||||
dark: false
|
||||
```
|
||||
|
||||
### 12.1 What this YAML proves
|
||||
|
||||
Run §2 of this reference with these inputs:
|
||||
|
||||
- `n_lanes = 6`, `n_steps = 11`, `has_color_row = true` (3 nodes carry `color`).
|
||||
- `viewBox_w = 140 + 11 * 112 + 28 = 1400`. ✓ matches rendered SVG.
|
||||
- `legend_h = 100`, `viewBox_h = 36 + 6 * 80 + 100 = 616`. ✓
|
||||
- Lane y_top = [36, 116, 196, 276, 356, 436]; lane mid = [76, 156, 236, 316, 396, 476]. ✓
|
||||
- Step cx = [198, 310, 422, 534, 646, 758, 870, 982, 1094, 1208, 1320] (the 8-px content-area gutter shifts every value by 8 from `140 + j*112 + 50`). ✓
|
||||
- Node 4 (HQ Review): step=3, lane="SVY" (k=3) → x = 534-50 = 484, y = 276+8 = 284. ✓
|
||||
- Node 5 (Error Checks): step=4, lane="IT" (k=1) → x = 646-50 = 596, y = 116+8 = 124. ✓
|
||||
- Node 10 (Public Release): step=9, lane="CMM" (k=5) → x = 1208-50 = 1158, y = 436+8 = 444. ✓ *(Rendered uses x=1156 — 2-px tolerance from chip-width rounding on the step "10" label.)*
|
||||
|
||||
The two coord drifts on the rightmost two nodes (chip width=20 for two-digit step numbers shifts the chip but not the node center math) are an artifact of the existing hand-tuned example, not a formula failure — a fresh generation from this YAML would produce x=1158 and the diagram would be visually indistinguishable from the shipped version.
|
||||
|
||||
### 12.2 Adapting this YAML to a different process
|
||||
|
||||
To document a different process, change only the value of these inputs:
|
||||
|
||||
- **Lanes**: rename `lanes[k].name` to your team names; update each `nodes[i].lane` to match. Up to 6 lanes.
|
||||
- **Steps**: rename `steps[j].label`, move `focal: true` to the step that defines the diagram's central claim. Up to 12 steps.
|
||||
- **Nodes**: write one entry per `(lane, step)` cell that has work. Leave cells empty (no entry) to render nothing.
|
||||
- **Colors**: choose `color: "#hex"` on at most 3 nodes (§4 cap). Stick to the recommended palette unless brand demands otherwise.
|
||||
- **Arrows**: declare every edge explicitly with `style: normal | focal-in | focal-out | trigger`. The routing rule (§3.1) fills in the geometry.
|
||||
|
||||
Everything else — viewBox sizing, chip positions, legend layout, dark-mode token swap — is derivable. The YAML is the **source of truth**; the SVG is one of many possible renderings of it (light/dark/full all derive from the same inputs with different style tokens).
|
||||
|
||||
---
|
||||
|
||||
## 13. Examples
|
||||
|
||||
- `assets/example-process.html` — minimal light (quarterly survey: 11 steps, 6 divisions, data-type chips). Gallery default.
|
||||
- `assets/example-process-dark.html` — same, dark skin.
|
||||
- `assets/example-process-full.html` — same, editorial-card frame.
|
||||
- `assets/example-process-extended.html` — exercises §4 color override: Build app in slate-blue (data quality), Train enumerators in rust-red (governance), Publish results in olive-green (data products). Focal accent on Pilot test step + node unchanged.
|
||||
- `assets/example-process-extended-dark.html` — extended pattern, dark skin.
|
||||
- `assets/example-process-extended-full.html` — extended pattern, editorial-card frame.
|
||||
@@ -0,0 +1,80 @@
|
||||
# Radar / Spider
|
||||
|
||||
**Best for:** comparing 3–5 entities across 3–5 quantitative criteria on a single normalized 0–N scale. Capability matrices, product or backend evaluations, framework/team scorecards. Where a comparison table starts running out of horizontal room, radar makes the shape of each option legible at a glance.
|
||||
|
||||
## Layout conventions
|
||||
|
||||
- **N axes (3–5).** Equally spaced on a regular polygon-N. First axis at the top (`-90°`), going clockwise. **Above 5 → split or use a comparison table.**
|
||||
- **Five concentric grid rings** at fractions `0.2 / 0.4 / 0.6 / 0.8 / 1.0` of the radius. Drawn as closed polygons connecting the axis vertices at that fraction. Inner four at `rule` 0.10 opacity, outer ring at `rule-solid` 0.20 (a hint stronger to anchor the chart).
|
||||
- **Axis spokes** from center to each outer vertex. `rule-solid` 0.20 opacity. **No arrowheads.**
|
||||
- **Axis labels:** one word per spoke (Jobs-minimal). Geist sans 11px weight 600. Place 16px outside the outer ring along the axis vector. Top/bottom = `text-anchor="middle"`; right side = `start`; left side = `end`.
|
||||
- **Scale ticks** (e.g. `2 4 6 8 10`) only on the **first (top) axis** — putting numbers on every spoke clutters the chart fast. Geist Mono 8px, `muted`, anchored end at `cx − 6`.
|
||||
- **Series polygon:** stroke 1.5px at the series color, fill the same color at `0.18` opacity (`0.22` in dark). Stroke 1.8px on the focal series — a subtle weight bump.
|
||||
- **Vertex dots:** **only on the focal series**, `r=4` filled with the series color. Non-focal series are stroke-and-fill only. This is the load-bearing rule that keeps the chart readable at 4–5 series.
|
||||
- **Drawing order:** dots-pattern bg → grid rings → axis spokes → axis labels → scale ticks → non-focal series (smallest area first) → focal series → focal vertex dots → legend.
|
||||
- **Legend:** horizontal strip at the bottom (per the global rule). Swatch is a 16×8 rectangle (matches the polygon stroke+fill, not a circle), then the entity name. ~140px between entries. Optional italic tail on the right with the rationale (`"One coral. Position is the signal — color reserved for the recommended option."`).
|
||||
|
||||
## Math
|
||||
|
||||
For axis `i` (0-indexed) of `N`, value `v` on scale `S`, center `(cx, cy)`, outer radius `R`:
|
||||
|
||||
```
|
||||
angle = -π/2 + 2π · i / N
|
||||
x = cx + (v / S) · R · cos(angle)
|
||||
y = cy + (v / S) · R · sin(angle)
|
||||
```
|
||||
|
||||
A series with values `[v0, v1, ..., v(N-1)]` becomes a `<polygon>` with `points="x0,y0 x1,y1 ..."`.
|
||||
|
||||
### Pre-computed reference (N=5, cx=500, cy=240, R=160, S=10, integer-rounded)
|
||||
|
||||
| Fraction `f` | i=0 (top) | i=1 | i=2 | i=3 | i=4 |
|
||||
|---|---|---|---|---|---|
|
||||
| 0.2 | 500,208 | 530,230 | 519,266 | 481,266 | 470,230 |
|
||||
| 0.4 | 500,176 | 561,220 | 538,292 | 462,292 | 439,220 |
|
||||
| 0.6 | 500,144 | 591,211 | 556,317 | 444,317 | 409,211 |
|
||||
| 0.8 | 500,112 | 622,201 | 575,343 | 425,343 | 378,201 |
|
||||
| 1.0 | 500,80 | 652,191 | 594,369 | 406,369 | 348,191 |
|
||||
|
||||
For an arbitrary value `v` on axis `i`, take the unit offset from the row above for that axis (e.g. axis 1: offset `(152, -49)` from center) and scale by `v/S`. **Drop coords as integers — fractional pixels in SVG render fine, but integers keep the file scannable.**
|
||||
|
||||
### Worked example (N=5)
|
||||
|
||||
Series `[9, 8, 9, 9, 9]` on a 0–10 scale becomes:
|
||||
|
||||
```svg
|
||||
<polygon points="500,96 622,201 585,356 415,356 363,196"
|
||||
fill="rgba(235,108,54,0.18)" stroke="#eb6c36" stroke-width="1.8"/>
|
||||
```
|
||||
|
||||
Each vertex: `center + (v/10) · (outer_i − center)`, rounded to the nearest pixel.
|
||||
|
||||
## Series palette
|
||||
|
||||
The skill's "1-focal" rule still holds: `accent` is reserved for the focal series, and a small editorial palette (`series-1` through `series-5`, defined in [`style-guide.md`](style-guide.md)) covers the non-focal series. Don't reach for free-form colors.
|
||||
|
||||
| Slot | Token | Light | Dark |
|
||||
|---|---|---|---|
|
||||
| Focal | `accent` | `#eb6c36` | `#f08a59` |
|
||||
| 1 | `series-1` (sage) | `#7c8f6f` | `#9caf8f` |
|
||||
| 2 | `series-2` (dusty-blue) | `#5e7a9b` | `#82a0c0` |
|
||||
| 3 | `series-3` (mustard) | `#b8915a` | `#d3ad7a` |
|
||||
| 4 | `series-4` (rust-brown) | `#9c6b50` | `#b88670` |
|
||||
| 5 | `series-5` (slate) | `#6e6479` | `#8d8298` |
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- **More than 5 series** → mush. Split into two charts (e.g. "best by latency" + "best by ops") or switch to a comparison table.
|
||||
- **Axes on inconsistent native scales** (one 0–100, another 0–1) without normalization. **Always normalize to 0–N first** — radar polygons compare *shapes*, not absolute values.
|
||||
- **Zero-baseline tricks** — starting the inner ring at v=5 to amplify differences. The grid starts at 0; if differences look small, that's the truthful reading.
|
||||
- **Dots on every series.** Only the focal carries dots. Adding them to all 4–5 series turns the chart into a bead curtain.
|
||||
- **Radar with 2 series** — a comparison bar chart or a 2-row table is clearer.
|
||||
- **Non-quantitative axes.** All axes must be measurable on the same normalized scale. "Speed" + "color" + "year" mixes don't belong on a radar.
|
||||
- **Mono-font axis labels.** Names go in Geist sans (the global rule). Mono is for technical sublabels only.
|
||||
- **Rainbow palette.** Even with the new `series-*` tokens, you don't need all 5 in one chart — use only as many as you have non-focal entities.
|
||||
|
||||
## Examples
|
||||
|
||||
- `assets/example-radar.html` — minimal light. 4 storage backends × 5 workload dimensions, MinIO focal.
|
||||
- `assets/example-radar-dark.html` — minimal dark, same data.
|
||||
- `assets/example-radar-full.html` — full editorial: container framing + 4 cards (one per backend) with varied widths + footer.
|
||||
@@ -0,0 +1,39 @@
|
||||
# Scatter Plot
|
||||
|
||||
**Best for:** correlation and distribution — two continuous variables plotted against each other. Use when the relationship (or lack of one) between variables is the message, or when you need to identify clusters, outliers, and high/low performers.
|
||||
|
||||
## Layout conventions
|
||||
|
||||
- **Plot area margins:** left 80px, bottom 60px, top 40px, right 40px — inside `0 0 1000 500` viewBox.
|
||||
- **Point count:** 5–30 points. Fewer → just describe the relationship in prose; more → bin into a density contour.
|
||||
- **Axes:** X at y=420 (baseline), Y at x=80. Both use Geist Mono 8px gridline labels. Gridlines 4–6 per axis at equal intervals.
|
||||
- **Point shape:** `<circle>` r=5 for standard points, r=6 for focal. Focal point in `accent` fill. Others in `muted @ 0.20` fill + `muted` stroke.
|
||||
- **Labels on points (optional):** Geist Mono 8px next to a point. Use a paper-fill rect mask behind the label. Label at most 2–3 points; not all.
|
||||
- **Trend line (optional):** `<line>` from lower-left to upper-right, stroke `rgba(45,49,66,0.25)` dashed 4,3. Never force a perfect fit — only add if the trend is visually obvious.
|
||||
- **Quadrant dividers (optional):** light dashed lines at the median x and y to split into quadrants. Label each quadrant in Geist Mono 8px, muted.
|
||||
|
||||
### Point pattern
|
||||
|
||||
```svg
|
||||
<!-- Non-focal point — paper mask + circle -->
|
||||
<circle cx="X" cy="Y" r="5" fill="#f5f5f5"/>
|
||||
<circle cx="X" cy="Y" r="5" fill="rgba(79,93,117,0.20)" stroke="#4f5d75" stroke-width="1"/>
|
||||
|
||||
<!-- Focal point -->
|
||||
<circle cx="X" cy="Y" r="6" fill="#f5f5f5"/>
|
||||
<circle cx="X" cy="Y" r="6" fill="rgba(235,108,54,0.15)" stroke="#eb6c36" stroke-width="1.2"/>
|
||||
```
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- More than 30 points without clustering (jitter/mush).
|
||||
- Forced trend line when the data is genuinely scattered — dishonest.
|
||||
- Point labels on every point (label the focal and 1–2 notable outliers only).
|
||||
- Bubble size encoding (use a third axis label or color instead; bubble area perception is unreliable).
|
||||
- Axes that don't include zero when the absolute position matters; axes that do include zero when the range is tiny and far from zero.
|
||||
|
||||
## Examples
|
||||
|
||||
- `assets/example-scatter.html` — minimal light
|
||||
- `assets/example-scatter-dark.html` — minimal dark
|
||||
- `assets/example-scatter-full.html` — full editorial
|
||||
Reference in New Issue
Block a user