Diagram Design

Create diagrams as self-contained HTML files with inline SVG and an editorial design system.

Forty-five visual types. Semantic patterns describe behavior; type references describe layout.

0. First-time setup — style guide gate

Before generating your first diagram in a new project, verify the style guide has been customized.

Do not silently ship default-skinned diagrams into a branded project.

First resolve any project .diagram-design marker per references/profiles.md; a successfully resolved marker selects its profile and bypasses this gate. That reference owns failures, the protected default, and save behavior.

Open references/style-guide.md and check the default tokens. If they are still the shipped defaults (paper #f5f5f5, ink #2d3142, accent #bf4520), pause and ask the user:

"This is your first diagram in this project and the style guide is still default. Customize now? Options: (a) website URL, (b) installed skill, (c) local folder/design-system, (d) paste tokens, (e) keep default, (f) load saved profile."

Then branch per the matching section of references/onboarding.md; for (f) follow references/profiles.md.

Once the style guide has been customized (or the user explicitly chose default), skip this gate on later runs. A leading profile header names the copied-in active profile. Without a header, any semantic-role value or typography family differing from shipped defaults means custom-unsaved: skip the gate and offer to save it as a profile. All-default tokens with no marker/header trigger the gate. After onboarding, offer to save as a named client profile per references/profiles.md.

1. Philosophy

The highest-quality move is usually deletion.

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 45 visual 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.
• Attribute-only before/after → table; topology changes → Architecture delta.
• 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. Selection: semantic pattern, then visual type

When behavior, state, enforcement, or risk carries the meaning, first load references/semantic-patterns.md and choose one primary pattern. Then choose the nearest visual type for layout. If no pattern matches, choose the type directly.

…