Diagram Design
ppt-master integration note: This skill is vendored as a reference library. In this repo, diagram
slides are hand-authored by ppt-master's Executor as SVG pages in svg_output/ — not emitted as
standalone HTML. Do NOT run the URL onboarding flow (references/onboarding.md) or the upstream
style-guide gate; colors, fonts, and icons always come from the project's spec_lock.md, and the SVG
must obey ppt-master's technical constraints
(.claude/skills/ppt-master/references/shared-standards.md). The guidance below is upstream
context — read it for per-type layout conventions, node/edge discipline, and complexity budgets,
then author the page per ppt-master SKILL.md Step 6.
The upstream onboarding / one-time-setup / standalone-HTML-export sections (§0 style-guide gate,
§5 Design System skinning, §6 HTML-skin SVG primitives, §7 page layout, §8 summary cards,
§10 templates & variants, §11 HTML output) are preserved verbatim in
references/diagram-onboarding-legacy.md —
upstream provenance record only, never executed in ppt-master.
Fourteen diagram types. One shared design system, complexity budget, and taste gate. Type-specific conventions live in references/ and are loaded only when you pick a type.
1. Philosophy
The highest-quality move is usually deletion.
From .impeccable.md: "Confident restraint. Earn every element. One color accent, two families, a small spacing vocabulary. If removing it wouldn't hurt the page, remove it."
Applied to schematics:
- Every node represents a distinct idea. Two nodes that always travel together are one node.
- Every connection carries information. If the relationship is obvious from layout, remove the line.
- Coral is editorial, not a flag. 1–2 focal nodes per diagram. Using it on 5 nodes erases the signal.
- The schematic isn't done when everything is added. It's done when nothing can be removed.
Target density: 4/10. Enough to be technically complete. Not so dense it needs a guide. Above 9 nodes, it's probably two diagrams.
2. When to Use
Use for any of the 14 diagram types (§3) when a reader will learn more from a visual than from prose, a table, or a bulleted list.
Don't use for:
- Quick unicode diagrams → use wiretext.
- Lists of things → table or bullets.
- Simple before/after → table.
- One-shape "diagrams" → just write the sentence.
Before drawing, ask: Would the reader learn more from this than from a well-written paragraph? If no, don't draw.
3. Diagram Types
Selection guide
| If you're showing… |
Use |
Reference |
| Components + connections in a system |
Architecture |
type-architecture.md |
| Decision logic with branches |
Flowchart |
type-flowchart.md |
| Time-ordered messages between actors |
Sequence |
type-sequence.md |
| States + transitions + guards |
State machine |
type-state.md |
| Entities + fields + relationships |
ER / data model |
type-er.md |
| Events positioned in time |
Timeline |
type-timeline.md |
| Cross-functional process with handoffs |
Swimlane |
type-swimlane.md |
| Two-axis positioning / prioritization |
Quadrant |
type-quadrant.md |
| Hierarchy through containment / scope |
Nested |
type-nested.md |
| Parent → children relationships |
Tree |
type-tree.md |
| Human/agent/team ownership, reporting, routing, escalation |
Org chart |
type-org-chart.md |
| Stacked abstraction levels |
Layer stack |
type-layers.md |
| Overlap between sets |
Venn |
type-venn.md |
| Ranked hierarchy or conversion drop-off |
Pyramid / funnel |
type-pyramid.md |
Rules of thumb:
- If a 3-column table communicates the same thing, pick the table.
- If you're combining two types, pick the dominant axis — don't hybridize grammars.
- If you're past the complexity budget (§7), split into an overview + detail.
Always load the relevant references/type-*.md before drawing — it contains layout conventions, anti-patterns, and example files for that type.
4. Universal Anti-patterns
These mark "AI slop" schematics of any type:
| Anti-pattern |
Why it fails |
| Dark mode + cyan/purple glow |
Looks "technical" without design decisions |
| JetBrains Mono as blanket "dev" font |
Mono is for technical content — ports, commands, URLs. Names go in Geist sans. |
| Identical boxes for every node |
Erases hierarchy |
| Legend floating inside the diagram area |
Collides with nodes |
| Arrow labels with no masking rect |
Bleeds through the line |
Vertical writing-mode text on arrows |
Unreadable |
| 3 equal-width summary cards as default |
Generic grid — vary widths |
| Shadow on any element |
Shadows are out. Borders are in. |
rounded-2xl on boxes |
Max radius 6–10px or none |
| Coral on every "important" node |
Coral is 1–2 editorial accents, not a signaling system |
Type-specific anti-patterns live in each references/type-*.md.
7. Layout & Spacing
4px grid
All values — font sizes, padding, node dimensions, gaps, x/y coords — divisible by 4. Non-negotiable.
| Category |
Allowed values |
| Font sizes |
8, 12, 16, 20, 24, 28, 32, 40 |
| Node width / height |
80, 96, 112, 120, 128, 140, 144, 160, 180, 200, 240, 320 |
| x / y coordinates |
multiples of 4 |
| Gap between nodes |
20, 24, 32, 40, 48 |
| Padding inside boxes |
8, 12, 16 |
| Border radius |
4, 6, 8 |
Exempt: stroke widths (0.8, 1, 1.2), opacity values, and the 22×22 dot-pattern.
Quick check: if a coordinate ends in 1, 2, 3, 5, 6, 7, 9 — fix it.
Complexity budget (per diagram)
| Limit |
Rule |
| Max nodes |
9 |
| Max arrows / transitions |
12 |
| Max coral elements |
2 |
| Max lifelines (sequence) |
5 |
| Max lanes (swimlane) |
5 |
| Max items (quadrant) |
12 |
| Max entities (ER) |
8 |
| Max nesting levels (nested) |
6 |
| Max tree depth |
4 |
| Max org chart depth |
4 |
| Max org chart nodes |
12 |
| Max layers (layer stack) |
6 |
| Max circles (venn) |
3 |
| Max layers (pyramid) |
6 |
| Max annotation callouts |
2 |
If you exceed, split into two diagrams (overview + detail).
9. Pre-Output Checklist (Taste Gate)
Run before producing any diagram.
Type fit:
Remove test:
Signal:
Technical:
Typography:
1---2name: diagram-design-23description: Diagram design reference library (14 types — architecture, flowchart, sequence, state, ER, timeline, swimlane, quadrant, nested, tree, org chart, layers, venn, pyramid). In ppt-master this is consumed by the Executor when hand-authoring diagram-type SVG pages — it is NOT a standalone HTML generator here. Read for deep per-type layout conventions.4license: MIT5---67# Diagram Design89> **ppt-master integration note:** This skill is vendored as a *reference library*. In this repo, diagram10> slides are hand-authored by ppt-master's Executor as SVG pages in `svg_output/` — not emitted as11> standalone HTML. Do NOT run the URL onboarding flow (`references/onboarding.md`) or the upstream12> style-guide gate; colors, fonts, and icons always come from the project's `spec_lock.md`, and the SVG13> must obey ppt-master's technical constraints14> (`.claude/skills/ppt-master/references/shared-standards.md`). The guidance below is upstream15> context — read it for per-type layout conventions, node/edge discipline, and complexity budgets,16> then author the page per ppt-master SKILL.md Step 6.17>18> The upstream onboarding / one-time-setup / standalone-HTML-export sections (§0 style-guide gate,19> §5 Design System skinning, §6 HTML-skin SVG primitives, §7 page layout, §8 summary cards,20> §10 templates & variants, §11 HTML output) are preserved **verbatim** in21> [`references/diagram-onboarding-legacy.md`](references/diagram-onboarding-legacy.md) —22> upstream provenance record only, never executed in ppt-master.2324Fourteen diagram types. One shared design system, complexity budget, and taste gate. Type-specific conventions live in `references/` and are loaded only when you pick a type.2526---2728## 1. Philosophy2930**The highest-quality move is usually deletion.**3132From `.impeccable.md`: *"Confident restraint. Earn every element. One color accent, two families, a small spacing vocabulary. If removing it wouldn't hurt the page, remove it."*3334Applied to schematics:35- Every node represents a distinct idea. Two nodes that always travel together are one node.36- Every connection carries information. If the relationship is obvious from layout, remove the line.37- Coral is **editorial, not a flag.** 1–2 focal nodes per diagram. Using it on 5 nodes erases the signal.38- The schematic isn't done when everything is added. It's done when nothing can be removed.3940**Target density: 4/10.** Enough to be technically complete. Not so dense it needs a guide. Above 9 nodes, it's probably two diagrams.4142---4344## 2. When to Use4546Use for any of the 14 diagram types (§3) when a reader will learn more from a visual than from prose, a table, or a bulleted list.4748**Don't use for:**49- Quick unicode diagrams → use **wiretext**.50- Lists of things → table or bullets.51- Simple before/after → table.52- One-shape "diagrams" → just write the sentence.5354Before drawing, ask: *Would the reader learn more from this than from a well-written paragraph?* If no, don't draw.5556---5758## 3. Diagram Types5960### Selection guide6162| If you're showing… | Use | Reference |63|---|---|---|64| Components + connections in a system | **Architecture** | [type-architecture.md](references/type-architecture.md) |65| Decision logic with branches | **Flowchart** | [type-flowchart.md](references/type-flowchart.md) |66| Time-ordered messages between actors | **Sequence** | [type-sequence.md](references/type-sequence.md) |67| States + transitions + guards | **State machine** | [type-state.md](references/type-state.md) |68| Entities + fields + relationships | **ER / data model** | [type-er.md](references/type-er.md) |69| Events positioned in time | **Timeline** | [type-timeline.md](references/type-timeline.md) |70| Cross-functional process with handoffs | **Swimlane** | [type-swimlane.md](references/type-swimlane.md) |71| Two-axis positioning / prioritization | **Quadrant** | [type-quadrant.md](references/type-quadrant.md) |72| Hierarchy through containment / scope | **Nested** | [type-nested.md](references/type-nested.md) |73| Parent → children relationships | **Tree** | [type-tree.md](references/type-tree.md) |74| Human/agent/team ownership, reporting, routing, escalation | **Org chart** | [type-org-chart.md](references/type-org-chart.md) |75| Stacked abstraction levels | **Layer stack** | [type-layers.md](references/type-layers.md) |76| Overlap between sets | **Venn** | [type-venn.md](references/type-venn.md) |77| Ranked hierarchy or conversion drop-off | **Pyramid / funnel** | [type-pyramid.md](references/type-pyramid.md) |7879Rules of thumb:80- If a 3-column table communicates the same thing, pick the table.81- If you're combining two types, pick the dominant axis — don't hybridize grammars.82- If you're past the complexity budget (§7), split into an overview + detail.8384**Always load the relevant `references/type-*.md` before drawing** — it contains layout conventions, anti-patterns, and example files for that type.8586---8788## 4. Universal Anti-patterns8990These mark "AI slop" schematics of any type:9192| Anti-pattern | Why it fails |93|---|---|94| Dark mode + cyan/purple glow | Looks "technical" without design decisions |95| JetBrains Mono as blanket "dev" font | Mono is for *technical* content — ports, commands, URLs. Names go in Geist sans. |96| Identical boxes for every node | Erases hierarchy |97| Legend floating inside the diagram area | Collides with nodes |98| Arrow labels with no masking rect | Bleeds through the line |99| Vertical `writing-mode` text on arrows | Unreadable |100| 3 equal-width summary cards as default | Generic grid — vary widths |101| Shadow on any element | Shadows are out. Borders are in. |102| `rounded-2xl` on boxes | Max radius 6–10px or none |103| Coral on every "important" node | Coral is 1–2 editorial accents, not a signaling system |104105Type-specific anti-patterns live in each `references/type-*.md`.106107---108109## 7. Layout & Spacing110111### 4px grid112113**All values — font sizes, padding, node dimensions, gaps, x/y coords — divisible by 4.** Non-negotiable.114115| Category | Allowed values |116|---|---|117| Font sizes | 8, 12, 16, 20, 24, 28, 32, 40 |118| Node width / height | 80, 96, 112, 120, 128, 140, 144, 160, 180, 200, 240, 320 |119| x / y coordinates | multiples of 4 |120| Gap between nodes | 20, 24, 32, 40, 48 |121| Padding inside boxes | 8, 12, 16 |122| Border radius | 4, 6, 8 |123124Exempt: stroke widths (0.8, 1, 1.2), opacity values, and the 22×22 dot-pattern.125126Quick check: if a coordinate ends in 1, 2, 3, 5, 6, 7, 9 — fix it.127128### Complexity budget (per diagram)129130| Limit | Rule |131|---|---|132| Max nodes | 9 |133| Max arrows / transitions | 12 |134| Max coral elements | 2 |135| Max lifelines (sequence) | 5 |136| Max lanes (swimlane) | 5 |137| Max items (quadrant) | 12 |138| Max entities (ER) | 8 |139| Max nesting levels (nested) | 6 |140| Max tree depth | 4 |141| Max org chart depth | 4 |142| Max org chart nodes | 12 |143| Max layers (layer stack) | 6 |144| Max circles (venn) | 3 |145| Max layers (pyramid) | 6 |146| Max annotation callouts | 2 |147148If you exceed, split into two diagrams (overview + detail).149150---151152## 9. Pre-Output Checklist (Taste Gate)153154Run before producing any diagram.155156**Type fit:**157- [ ] Right type for what I'm showing? (§3 selection guide)158- [ ] Would a table / paragraph do the same job? (If yes — don't draw.)159- [ ] Loaded the matching `references/type-*.md`?160161**Remove test:**162- [ ] Can I remove any node? (Would a reader still understand?)163- [ ] Can I merge any two nodes? (Do they always travel together?)164- [ ] Can I remove any arrow? (Is the relationship obvious from layout?)165- [ ] Can I remove any label? (Does color or shape already signal it?)166167**Signal:**168- [ ] Coral used on ≤2 elements? If more, which actually deserve focal status?169- [ ] Legend covers every type used — and nothing extra?170- [ ] Within the type's complexity budget (§7)?171172**Technical:**173- [ ] Arrows drawn before boxes?174- [ ] Every arrow label has an opaque `fill="#f5f5f5"` rect behind it?175- [ ] Legend is a horizontal bottom strip, not floating?176- [ ] No vertical `writing-mode` text?177- [ ] `viewBox` expanded for the legend strip (~60px)?178- [ ] Every font size, coord, width, height, gap divisible by 4?179180**Typography:**181- [ ] Human-readable names in Geist sans, not Geist Mono?182- [ ] Technical sublabels (ports, commands, URLs) in Geist Mono?183- [ ] Page title in Instrument Serif?184- [ ] Annotation callouts (if any) in *italic* Instrument Serif? (see [primitive-annotation.md](references/primitive-annotation.md))185- [ ] No JetBrains Mono anywhere?
humanist96