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.
• The accent color (spec_lock.colors) 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:

• 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
Mono as blanket "dev" font	Mono is for technical content — ports, commands, URLs. Names go in the spec_lock.typography body role (Pretendard on this install).
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
Accent color on every "important" node	The deck's accent token from spec_lock.colors 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 accent-color 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:

• Right type for what I'm showing? (§3 selection guide)
• Would a table / paragraph do the same job? (If yes — don't draw.)
• Loaded the matching references/type-*.md?

Remove test:

• Can I remove any node? (Would a reader still understand?)
• Can I merge any two nodes? (Do they always travel together?)
• Can I remove any arrow? (Is the relationship obvious from layout?)
• Can I remove any label? (Does color or shape already signal it?)

Signal:

• Accent token (spec_lock.colors) used on ≤2 elements? If more, which actually deserve focal status?
• Legend covers every type used — and nothing extra?
• Within the type's complexity budget (§7)?

Technical:

• Arrows drawn before boxes?
• Every arrow label has an opaque rect behind it, filled with the deck's background token from spec_lock.colors?
• Legend is a horizontal bottom strip, not floating?
• No vertical writing-mode text?
• viewBox expanded for the legend strip (~60px)?
• Every font size, coord, width, height, gap divisible by 4?

Typography:

• Names / labels / title use the spec_lock.typography roles (Pretendard on this install), not a mono face?
• Technical sublabels (ports, commands, URLs) in the spec_lock.typography code role, when the deck declares one?
• Annotation callouts (if any) use the locked annotation role? (see primitive-annotation.md)