diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 02325ce..45c2308 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -12,6 +12,5 @@ "flowchart", "visualization", "editorial" - ], - "skills": ["./"] + ] } diff --git a/README.md b/README.md index 1591710..95894d6 100644 --- a/README.md +++ b/README.md @@ -52,21 +52,20 @@ All 14 diagrams ship in three variants: minimal light, minimal dark, and full-ed -**Browse the live gallery:** open [`assets/index.html`](assets/index.html) in your browser to flip through all 14 diagrams with light / dark / full-editorial tabs. +**Browse the live gallery:** open [`skills/diagram-design/assets/index.html`](skills/diagram-design/assets/index.html) in your browser to flip through all 14 diagrams with light / dark / full-editorial tabs. --- ## Install ```bash -# Clone into your Claude Code skills directory -git clone git@github.com:cathrynlavery/diagram-design.git ~/.claude/skills/diagram-design - -# Or if you keep skills elsewhere, symlink it +# Clone the repo somewhere, then symlink the inner skill into Claude Code's skills dir git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design -ln -s ~/code/diagram-design ~/.claude/skills/diagram-design +ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design ``` +The real skill lives at `skills/diagram-design/` inside the repo (so the same tree works as a Claude Code plugin, a Codex plugin, and a standalone skill). The symlink points Claude Code at that inner directory. + Restart Claude Code. The skill registers as `diagram-design` and activates whenever you ask Claude to make a diagram. ### Alternative: install as a plugin @@ -129,7 +128,7 @@ Before writing tokens, the skill verifies WCAG AA contrast on `ink` over `paper` ### Manual override -Prefer to set tokens by hand? Open [`references/style-guide.md`](references/style-guide.md) and edit the table. Everything downstream reads from there — all 14 diagrams, the annotation primitive, and the gallery all inherit semantic role names (`accent`, not `#eb6c36`). +Prefer to set tokens by hand? Open [`skills/diagram-design/references/style-guide.md`](skills/diagram-design/references/style-guide.md) and edit the table. Everything downstream reads from there — all 14 diagrams, the annotation primitive, and the gallery all inherit semantic role names (`accent`, not `#eb6c36`). ### First-run gate @@ -137,7 +136,7 @@ The skill won't silently ship default-skinned diagrams into a branded project. O > *"This is your first diagram in this project. The style guide is still at the default. Want to run onboarding, paste tokens manually, or proceed with default?"* -See [`references/onboarding.md`](references/onboarding.md) for the full spec. +See [`skills/diagram-design/references/onboarding.md`](skills/diagram-design/references/onboarding.md) for the full spec. --- @@ -216,14 +215,14 @@ No matter how many types exist, Claude only reads the one you need. Add a new ty ## The design system (in one paragraph) -One accent color, 1–2 focal elements per diagram. Three font families: Instrument Serif (title + italic callouts), Geist sans (node names), Geist Mono (technical sublabels). 1px hairline borders, no shadows, max border-radius 10px. Every coord, width, and gap divisible by 4 — non-negotiable, it's what keeps the diagrams from feeling AI-generated. Mono is for technical content (ports, URLs, field types), not a blanket "dev" aesthetic. Coral-tinted focal nodes draw the eye to the 1–2 things that matter. Full spec in [`SKILL.md`](SKILL.md#5-design-system). +One accent color, 1–2 focal elements per diagram. Three font families: Instrument Serif (title + italic callouts), Geist sans (node names), Geist Mono (technical sublabels). 1px hairline borders, no shadows, max border-radius 10px. Every coord, width, and gap divisible by 4 — non-negotiable, it's what keeps the diagrams from feeling AI-generated. Mono is for technical content (ports, URLs, field types), not a blanket "dev" aesthetic. Coral-tinted focal nodes draw the eye to the 1–2 things that matter. Full spec in [`SKILL.md`](skills/diagram-design/SKILL.md#5-design-system). --- ## Primitives -- **Annotation callout** — italic Instrument Serif + dashed Bézier leader, for editorial asides that sit in the margins. See [`references/primitive-annotation.md`](references/primitive-annotation.md). -- **Sketchy filter** — SVG turbulence + displacement map for a hand-drawn variant. Good for essays, not for technical docs. See [`references/primitive-sketchy.md`](references/primitive-sketchy.md). +- **Annotation callout** — italic Instrument Serif + dashed Bézier leader, for editorial asides that sit in the margins. See [`skills/diagram-design/references/primitive-annotation.md`](skills/diagram-design/references/primitive-annotation.md). +- **Sketchy filter** — SVG turbulence + displacement map for a hand-drawn variant. Good for essays, not for technical docs. See [`skills/diagram-design/references/primitive-sketchy.md`](skills/diagram-design/references/primitive-sketchy.md). --- diff --git a/SKILL.md b/SKILL.md deleted file mode 100644 index 9586bbb..0000000 --- a/SKILL.md +++ /dev/null @@ -1,400 +0,0 @@ ---- -name: diagram-design -description: Create technical and product diagrams — architecture, flowchart, sequence, state machine, ER / data model, timeline, swimlane, quadrant, nested, tree, layer stack, venn, pyramid — as standalone HTML files with inline SVG. Ships with a neutral editorial skin and a first-run gate that prompts users to customize the style guide (colors, fonts) from their own website before generating. Includes annotation-callout primitive and optional sketchy variant. -license: MIT -metadata: - version: "1.0" ---- - -# Diagram Design - -Create visual diagrams as self-contained HTML files with inline SVG and CSS, following an opinionated editorial design system. - -Thirteen 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. - ---- - -## 0. First-time setup — style guide gate - -**Before generating your first diagram in a new project, verify the style guide has been customized.** - -Open [`references/style-guide.md`](references/style-guide.md) and check the default tokens. If they're still the shipped defaults (paper `#faf7f2`, ink `#1c1917`, accent `#b5523a` rust), **pause and ask the user**: - -> *"This is your first Schematic in this project. The style guide is still at the default (neutral stone + rust). Do you want to customize it to match your brand first? Options: (a) run onboarding — I'll pull colors and fonts from your website, (b) paste your tokens manually, (c) proceed with the default for now."* - -Then branch: -- **(a)** → follow [`references/onboarding.md`](references/onboarding.md) to fetch the site, extract palette + fonts, propose a diff, and write `style-guide.md`. -- **(b)** → accept the user's tokens and write them into `style-guide.md` under a new "Custom tokens" section. -- **(c)** → proceed; optionally remind the user they can run onboarding later. - -**Once the style guide has been customized** (or the user explicitly opted for default), skip this gate on subsequent runs. A simple way to detect customization: if the `accent` value in `style-guide.md` differs from `#b5523a`, assume custom. - -Don't silently ship default-skinned diagrams into a branded project — that's the failure mode this gate exists to prevent. - ---- - -## 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 13 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](references/type-architecture.md) | -| Decision logic with branches | **Flowchart** | [type-flowchart.md](references/type-flowchart.md) | -| Time-ordered messages between actors | **Sequence** | [type-sequence.md](references/type-sequence.md) | -| States + transitions + guards | **State machine** | [type-state.md](references/type-state.md) | -| Entities + fields + relationships | **ER / data model** | [type-er.md](references/type-er.md) | -| Events positioned in time | **Timeline** | [type-timeline.md](references/type-timeline.md) | -| Cross-functional process with handoffs | **Swimlane** | [type-swimlane.md](references/type-swimlane.md) | -| Two-axis positioning / prioritization | **Quadrant** | [type-quadrant.md](references/type-quadrant.md) | -| Hierarchy through containment / scope | **Nested** | [type-nested.md](references/type-nested.md) | -| Parent → children relationships | **Tree** | [type-tree.md](references/type-tree.md) | -| Stacked abstraction levels | **Layer stack** | [type-layers.md](references/type-layers.md) | -| Overlap between sets | **Venn** | [type-venn.md](references/type-venn.md) | -| Ranked hierarchy or conversion drop-off | **Pyramid / funnel** | [type-pyramid.md](references/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`. - ---- - -## 5. Design System - -**The design system is skinnable.** All colors, typography, and tokens live in a single source of truth — [`references/style-guide.md`](references/style-guide.md). This file describes semantic roles (`paper`, `ink`, `muted`, `accent`, `link`, …). The default skin is a cool editorial palette (white-smoke paper, jet-black ink, atomic-tangerine accent, blue-slate muted, silver hairlines); to apply your own brand, either edit `style-guide.md` directly or run the URL-based flow described in [`references/onboarding.md`](references/onboarding.md). - -> When specs below or in type references mention "ink", "accent", "muted", etc., look up the current hex value in `style-guide.md`. - -### Semantic roles (at a glance) - -| Role | Purpose | -|---|---| -| `paper`, `paper-2` | Page bg and container bg | -| `ink` | Primary text / stroke | -| `muted`, `soft` | Secondary text, default arrows, sublabels | -| `rule`, `rule-solid` | Hairline borders | -| `accent`, `accent-tint` | 1–2 focal elements per diagram | -| `link` | HTTP/API calls, external arrows | - -**Focal rule:** `accent` goes on 1–2 elements max. Everything else is `ink` / `muted` / `soft`. If you're tempted to accent 4 things, you haven't decided what's focal yet. - -### Node type → treatment - -| Type | Fill | Stroke | -|---|---|---| -| **Focal** (1–2 max) | `accent-tint` | `accent` | -| **Backend / API / Step** | white | `ink` | -| **Store / State** | `ink @ 0.05` | `muted` | -| **External / Cloud** | `ink @ 0.03` | `ink @ 0.30` | -| **Input / User** | `muted @ 0.10` | `soft` | -| **Optional / Async** | `ink @ 0.02` | `ink @ 0.20` dashed `4,3` | -| **Security / Boundary** | `accent @ 0.05` | `accent @ 0.50` dashed `4,4` | - -### Typography (summary — full spec in style-guide.md) - -- **Title** — Instrument Serif, 1.75rem, 400 — H1 only -- **Node name** — Geist (sans), 12px, 600 — human-readable labels -- **Sublabel** — Geist Mono, 9px — ports, URLs, field types -- **Eyebrow / tag** — Geist Mono, 7–8px, uppercase, tracked — type tags, axis labels -- **Arrow label** — Geist Mono, 8px — annotation on arrows -- **Editorial aside** — Instrument Serif *italic*, 14px — callouts only - -**Mono is for technical content.** Names are Geist sans. Page title is Instrument Serif. Italic Instrument Serif is reserved for annotation callouts. Never JetBrains Mono as a blanket "dev" font. - -```html - -``` - ---- - -## 6. Core SVG Primitives - -Universal building blocks. Type-specialized primitives (lifeline, activation bar, region) live in the relevant `references/type-*.md`. Optional primitives: -- Editorial callouts → [primitive-annotation.md](references/primitive-annotation.md) -- Hand-drawn variant → [primitive-sketchy.md](references/primitive-sketchy.md) - -### Background - -**Default: clean paper, no dot pattern.** Single `` filled with `paper`. Don't wrap the diagram in a secondary container background — the diagram sits directly on the page. - -```svg - -``` - -**Optional: dotted paper variant.** When a long-form editorial diagram benefits from textured ground (essays, hero diagrams on a dedicated page), opt in by adding the `dots` pattern and a second rect: - -```svg - - - - - - - -``` - -Don't use the dot pattern when the diagram sits inside a product page, slide, or card — the texture compounds with surrounding chrome and reads as noise. - -### Arrow markers (define all three, always) - -```svg - - - - - - - - - -``` - -| Arrow | Stroke | When | -|---|---|---| -| Default | muted `#4f5d75` | Internal, generic | -| Accent | coral `#eb6c36` | Primary / highlighted / headline | -| Link-blue | `#2e5aa8` | HTTP/API calls, external systems | -| Dashed | `stroke-dasharray="5,4"` + any color | Optional, passive, return, async | - -**Draw arrows before boxes** so z-order puts lines behind nodes. - -### Node box — full pattern - -```svg - - - - - - -API - -Node Name - -tech:port -``` - -### Arrow labels — always mask - -Every arrow label needs an opaque rect behind it. Without one it bleeds through the line. - -```svg - -WRITE -``` - -Rules: ≤14 characters, all-caps, centered on segment midpoint, 8–10px above line. Never `writing-mode` vertical. - -### Legend — horizontal strip at the bottom - -**Never put the legend inside the diagram area.** Place as a horizontal strip after all nodes, with a hairline separator: - -```svg - -LEGEND - -``` - -Expand SVG `viewBox` height by ~60px. - ---- - -## 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 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). - -### Page layout - -1. **Header** — eyebrow (Geist Mono), title (Instrument Serif), optional subtitle (Geist muted). -2. **Diagram container** — default: **clean, borderless**, no background — the SVG sits directly on the page paper. Optional *framed* variant (for card-heavy layouts or hero placements): `paper-2` bg + 1px `rule` border + 8px radius + `1.5rem` padding + `overflow-x: auto`. -3. **Summary cards** — 2–3 col grid with *varied* widths (e.g., `1.1fr 1fr 0.9fr`). -4. **Footer** — colophon in Geist Mono, muted, hairline top border. - ---- - -## 8. Summary Card Pattern - -Don't use 3 identical generic cards. Vary the treatment: - -```html -
-

SECTION LABEL

-
- -

Card Title

-
-
  • Item
-
-``` - -Rules: -- `background: #ffffff` (not paper — slight lift without shadow) -- `border: 1px solid rgba(45,49,66,0.12)` -- `border-radius: 6px`, `padding: 1.25rem` -- **No `box-shadow`** -- Card dots: 7px, `border-radius: 50%` — ink / muted / coral / link / soft variants - ---- - -## 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:** -- [ ] Coral 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 `fill="#f5f5f5"` rect behind it? -- [ ] 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:** -- [ ] Human-readable names in Geist sans, not Geist Mono? -- [ ] Technical sublabels (ports, commands, URLs) in Geist Mono? -- [ ] Page title in Instrument Serif? -- [ ] Annotation callouts (if any) in *italic* Instrument Serif? (see [primitive-annotation.md](references/primitive-annotation.md)) -- [ ] No JetBrains Mono anywhere? - ---- - -## 10. Templates & Variants - -Every diagram ships in three variants (see `assets/`): - -| Variant | File pattern | When to use | -|---|---|---| -| **Minimal light** (default) | `template.html`, `example-.html` | Screenshot-ready. Diagram + title. Warm paper. | -| **Minimal dark** | `template-dark.html`, `example--dark.html` | Dark mode sites, slides, high-contrast posts. | -| **Full editorial** | `template-full.html`, `example--full.html` | Long-form posts where the diagram is the hero. | -| **Consultant special** (quadrant only) | `example-quadrant-consultant.html` | BCG/McKinsey-style 2×2 scenario matrix. Clinical sans-serif, white bg, bold blue double-ended axes, named scenario cells. See [type-quadrant.md](references/type-quadrant.md#consultant-special-2x2-scenario-matrix). | - -**Sketchy variant** (optional, applied to any of the above) — see [primitive-sketchy.md](references/primitive-sketchy.md). SVG turbulence filter wobbles strokes for a hand-drawn feel. Good for essays, not for technical docs. - -### To create a new diagram - -1. Copy the variant closest to what you want (`template.html` for minimal, `template-full.html` for cards). -2. Load the matching `references/type-.md` for layout conventions. -3. Replace the eyebrow, h1, and SVG body. -4. Run the §9 taste gate. - ---- - -## 11. Output - -Always produce a single self-contained `.html` file: -- Embedded CSS (no external except Google Fonts) -- Inline SVG (no external images) -- No JavaScript required - -Renders correctly in any modern browser. diff --git a/skills/diagram-design/SKILL.md b/skills/diagram-design/SKILL.md index d57cd62..9586bbb 100644 --- a/skills/diagram-design/SKILL.md +++ b/skills/diagram-design/SKILL.md @@ -1,6 +1,6 @@ --- name: diagram-design -description: Create technical and product diagrams - architecture, flowchart, sequence, state machine, ER / data model, timeline, swimlane, quadrant, nested, tree, layer stack, venn, pyramid - as standalone HTML files with inline SVG. Ships with a neutral editorial skin and a first-run gate that prompts users to customize the style guide before generating. +description: Create technical and product diagrams — architecture, flowchart, sequence, state machine, ER / data model, timeline, swimlane, quadrant, nested, tree, layer stack, venn, pyramid — as standalone HTML files with inline SVG. Ships with a neutral editorial skin and a first-run gate that prompts users to customize the style guide (colors, fonts) from their own website before generating. Includes annotation-callout primitive and optional sketchy variant. license: MIT metadata: version: "1.0" @@ -8,6 +8,393 @@ metadata: # Diagram Design -This is the Codex plugin wrapper for the root skill. +Create visual diagrams as self-contained HTML files with inline SVG and CSS, following an opinionated editorial design system. -Before creating a diagram, open and follow `../../SKILL.md`. Resolve all referenced paths from the repository root, including `../../references/` and `../../assets/`. +Thirteen 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. + +--- + +## 0. First-time setup — style guide gate + +**Before generating your first diagram in a new project, verify the style guide has been customized.** + +Open [`references/style-guide.md`](references/style-guide.md) and check the default tokens. If they're still the shipped defaults (paper `#faf7f2`, ink `#1c1917`, accent `#b5523a` rust), **pause and ask the user**: + +> *"This is your first Schematic in this project. The style guide is still at the default (neutral stone + rust). Do you want to customize it to match your brand first? Options: (a) run onboarding — I'll pull colors and fonts from your website, (b) paste your tokens manually, (c) proceed with the default for now."* + +Then branch: +- **(a)** → follow [`references/onboarding.md`](references/onboarding.md) to fetch the site, extract palette + fonts, propose a diff, and write `style-guide.md`. +- **(b)** → accept the user's tokens and write them into `style-guide.md` under a new "Custom tokens" section. +- **(c)** → proceed; optionally remind the user they can run onboarding later. + +**Once the style guide has been customized** (or the user explicitly opted for default), skip this gate on subsequent runs. A simple way to detect customization: if the `accent` value in `style-guide.md` differs from `#b5523a`, assume custom. + +Don't silently ship default-skinned diagrams into a branded project — that's the failure mode this gate exists to prevent. + +--- + +## 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 13 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](references/type-architecture.md) | +| Decision logic with branches | **Flowchart** | [type-flowchart.md](references/type-flowchart.md) | +| Time-ordered messages between actors | **Sequence** | [type-sequence.md](references/type-sequence.md) | +| States + transitions + guards | **State machine** | [type-state.md](references/type-state.md) | +| Entities + fields + relationships | **ER / data model** | [type-er.md](references/type-er.md) | +| Events positioned in time | **Timeline** | [type-timeline.md](references/type-timeline.md) | +| Cross-functional process with handoffs | **Swimlane** | [type-swimlane.md](references/type-swimlane.md) | +| Two-axis positioning / prioritization | **Quadrant** | [type-quadrant.md](references/type-quadrant.md) | +| Hierarchy through containment / scope | **Nested** | [type-nested.md](references/type-nested.md) | +| Parent → children relationships | **Tree** | [type-tree.md](references/type-tree.md) | +| Stacked abstraction levels | **Layer stack** | [type-layers.md](references/type-layers.md) | +| Overlap between sets | **Venn** | [type-venn.md](references/type-venn.md) | +| Ranked hierarchy or conversion drop-off | **Pyramid / funnel** | [type-pyramid.md](references/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`. + +--- + +## 5. Design System + +**The design system is skinnable.** All colors, typography, and tokens live in a single source of truth — [`references/style-guide.md`](references/style-guide.md). This file describes semantic roles (`paper`, `ink`, `muted`, `accent`, `link`, …). The default skin is a cool editorial palette (white-smoke paper, jet-black ink, atomic-tangerine accent, blue-slate muted, silver hairlines); to apply your own brand, either edit `style-guide.md` directly or run the URL-based flow described in [`references/onboarding.md`](references/onboarding.md). + +> When specs below or in type references mention "ink", "accent", "muted", etc., look up the current hex value in `style-guide.md`. + +### Semantic roles (at a glance) + +| Role | Purpose | +|---|---| +| `paper`, `paper-2` | Page bg and container bg | +| `ink` | Primary text / stroke | +| `muted`, `soft` | Secondary text, default arrows, sublabels | +| `rule`, `rule-solid` | Hairline borders | +| `accent`, `accent-tint` | 1–2 focal elements per diagram | +| `link` | HTTP/API calls, external arrows | + +**Focal rule:** `accent` goes on 1–2 elements max. Everything else is `ink` / `muted` / `soft`. If you're tempted to accent 4 things, you haven't decided what's focal yet. + +### Node type → treatment + +| Type | Fill | Stroke | +|---|---|---| +| **Focal** (1–2 max) | `accent-tint` | `accent` | +| **Backend / API / Step** | white | `ink` | +| **Store / State** | `ink @ 0.05` | `muted` | +| **External / Cloud** | `ink @ 0.03` | `ink @ 0.30` | +| **Input / User** | `muted @ 0.10` | `soft` | +| **Optional / Async** | `ink @ 0.02` | `ink @ 0.20` dashed `4,3` | +| **Security / Boundary** | `accent @ 0.05` | `accent @ 0.50` dashed `4,4` | + +### Typography (summary — full spec in style-guide.md) + +- **Title** — Instrument Serif, 1.75rem, 400 — H1 only +- **Node name** — Geist (sans), 12px, 600 — human-readable labels +- **Sublabel** — Geist Mono, 9px — ports, URLs, field types +- **Eyebrow / tag** — Geist Mono, 7–8px, uppercase, tracked — type tags, axis labels +- **Arrow label** — Geist Mono, 8px — annotation on arrows +- **Editorial aside** — Instrument Serif *italic*, 14px — callouts only + +**Mono is for technical content.** Names are Geist sans. Page title is Instrument Serif. Italic Instrument Serif is reserved for annotation callouts. Never JetBrains Mono as a blanket "dev" font. + +```html + +``` + +--- + +## 6. Core SVG Primitives + +Universal building blocks. Type-specialized primitives (lifeline, activation bar, region) live in the relevant `references/type-*.md`. Optional primitives: +- Editorial callouts → [primitive-annotation.md](references/primitive-annotation.md) +- Hand-drawn variant → [primitive-sketchy.md](references/primitive-sketchy.md) + +### Background + +**Default: clean paper, no dot pattern.** Single `` filled with `paper`. Don't wrap the diagram in a secondary container background — the diagram sits directly on the page. + +```svg + +``` + +**Optional: dotted paper variant.** When a long-form editorial diagram benefits from textured ground (essays, hero diagrams on a dedicated page), opt in by adding the `dots` pattern and a second rect: + +```svg + + + + + + + +``` + +Don't use the dot pattern when the diagram sits inside a product page, slide, or card — the texture compounds with surrounding chrome and reads as noise. + +### Arrow markers (define all three, always) + +```svg + + + + + + + + + +``` + +| Arrow | Stroke | When | +|---|---|---| +| Default | muted `#4f5d75` | Internal, generic | +| Accent | coral `#eb6c36` | Primary / highlighted / headline | +| Link-blue | `#2e5aa8` | HTTP/API calls, external systems | +| Dashed | `stroke-dasharray="5,4"` + any color | Optional, passive, return, async | + +**Draw arrows before boxes** so z-order puts lines behind nodes. + +### Node box — full pattern + +```svg + + + + + + +API + +Node Name + +tech:port +``` + +### Arrow labels — always mask + +Every arrow label needs an opaque rect behind it. Without one it bleeds through the line. + +```svg + +WRITE +``` + +Rules: ≤14 characters, all-caps, centered on segment midpoint, 8–10px above line. Never `writing-mode` vertical. + +### Legend — horizontal strip at the bottom + +**Never put the legend inside the diagram area.** Place as a horizontal strip after all nodes, with a hairline separator: + +```svg + +LEGEND + +``` + +Expand SVG `viewBox` height by ~60px. + +--- + +## 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 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). + +### Page layout + +1. **Header** — eyebrow (Geist Mono), title (Instrument Serif), optional subtitle (Geist muted). +2. **Diagram container** — default: **clean, borderless**, no background — the SVG sits directly on the page paper. Optional *framed* variant (for card-heavy layouts or hero placements): `paper-2` bg + 1px `rule` border + 8px radius + `1.5rem` padding + `overflow-x: auto`. +3. **Summary cards** — 2–3 col grid with *varied* widths (e.g., `1.1fr 1fr 0.9fr`). +4. **Footer** — colophon in Geist Mono, muted, hairline top border. + +--- + +## 8. Summary Card Pattern + +Don't use 3 identical generic cards. Vary the treatment: + +```html +
+

SECTION LABEL

+
+ +

Card Title

+
+
  • Item
+
+``` + +Rules: +- `background: #ffffff` (not paper — slight lift without shadow) +- `border: 1px solid rgba(45,49,66,0.12)` +- `border-radius: 6px`, `padding: 1.25rem` +- **No `box-shadow`** +- Card dots: 7px, `border-radius: 50%` — ink / muted / coral / link / soft variants + +--- + +## 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:** +- [ ] Coral 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 `fill="#f5f5f5"` rect behind it? +- [ ] 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:** +- [ ] Human-readable names in Geist sans, not Geist Mono? +- [ ] Technical sublabels (ports, commands, URLs) in Geist Mono? +- [ ] Page title in Instrument Serif? +- [ ] Annotation callouts (if any) in *italic* Instrument Serif? (see [primitive-annotation.md](references/primitive-annotation.md)) +- [ ] No JetBrains Mono anywhere? + +--- + +## 10. Templates & Variants + +Every diagram ships in three variants (see `assets/`): + +| Variant | File pattern | When to use | +|---|---|---| +| **Minimal light** (default) | `template.html`, `example-.html` | Screenshot-ready. Diagram + title. Warm paper. | +| **Minimal dark** | `template-dark.html`, `example--dark.html` | Dark mode sites, slides, high-contrast posts. | +| **Full editorial** | `template-full.html`, `example--full.html` | Long-form posts where the diagram is the hero. | +| **Consultant special** (quadrant only) | `example-quadrant-consultant.html` | BCG/McKinsey-style 2×2 scenario matrix. Clinical sans-serif, white bg, bold blue double-ended axes, named scenario cells. See [type-quadrant.md](references/type-quadrant.md#consultant-special-2x2-scenario-matrix). | + +**Sketchy variant** (optional, applied to any of the above) — see [primitive-sketchy.md](references/primitive-sketchy.md). SVG turbulence filter wobbles strokes for a hand-drawn feel. Good for essays, not for technical docs. + +### To create a new diagram + +1. Copy the variant closest to what you want (`template.html` for minimal, `template-full.html` for cards). +2. Load the matching `references/type-.md` for layout conventions. +3. Replace the eyebrow, h1, and SVG body. +4. Run the §9 taste gate. + +--- + +## 11. Output + +Always produce a single self-contained `.html` file: +- Embedded CSS (no external except Google Fonts) +- Inline SVG (no external images) +- No JavaScript required + +Renders correctly in any modern browser. diff --git a/assets/example-architecture-dark.html b/skills/diagram-design/assets/example-architecture-dark.html similarity index 100% rename from assets/example-architecture-dark.html rename to skills/diagram-design/assets/example-architecture-dark.html diff --git a/assets/example-architecture-full.html b/skills/diagram-design/assets/example-architecture-full.html similarity index 100% rename from assets/example-architecture-full.html rename to skills/diagram-design/assets/example-architecture-full.html diff --git a/assets/example-architecture.html b/skills/diagram-design/assets/example-architecture.html similarity index 100% rename from assets/example-architecture.html rename to skills/diagram-design/assets/example-architecture.html diff --git a/assets/example-er-dark.html b/skills/diagram-design/assets/example-er-dark.html similarity index 100% rename from assets/example-er-dark.html rename to skills/diagram-design/assets/example-er-dark.html diff --git a/assets/example-er-full.html b/skills/diagram-design/assets/example-er-full.html similarity index 100% rename from assets/example-er-full.html rename to skills/diagram-design/assets/example-er-full.html diff --git a/assets/example-er.html b/skills/diagram-design/assets/example-er.html similarity index 100% rename from assets/example-er.html rename to skills/diagram-design/assets/example-er.html diff --git a/assets/example-flowchart-dark.html b/skills/diagram-design/assets/example-flowchart-dark.html similarity index 100% rename from assets/example-flowchart-dark.html rename to skills/diagram-design/assets/example-flowchart-dark.html diff --git a/assets/example-flowchart-full.html b/skills/diagram-design/assets/example-flowchart-full.html similarity index 100% rename from assets/example-flowchart-full.html rename to skills/diagram-design/assets/example-flowchart-full.html diff --git a/assets/example-flowchart.html b/skills/diagram-design/assets/example-flowchart.html similarity index 100% rename from assets/example-flowchart.html rename to skills/diagram-design/assets/example-flowchart.html diff --git a/assets/example-layers-dark.html b/skills/diagram-design/assets/example-layers-dark.html similarity index 100% rename from assets/example-layers-dark.html rename to skills/diagram-design/assets/example-layers-dark.html diff --git a/assets/example-layers-full.html b/skills/diagram-design/assets/example-layers-full.html similarity index 100% rename from assets/example-layers-full.html rename to skills/diagram-design/assets/example-layers-full.html diff --git a/assets/example-layers.html b/skills/diagram-design/assets/example-layers.html similarity index 100% rename from assets/example-layers.html rename to skills/diagram-design/assets/example-layers.html diff --git a/assets/example-nested-dark.html b/skills/diagram-design/assets/example-nested-dark.html similarity index 100% rename from assets/example-nested-dark.html rename to skills/diagram-design/assets/example-nested-dark.html diff --git a/assets/example-nested-full.html b/skills/diagram-design/assets/example-nested-full.html similarity index 100% rename from assets/example-nested-full.html rename to skills/diagram-design/assets/example-nested-full.html diff --git a/assets/example-nested.html b/skills/diagram-design/assets/example-nested.html similarity index 100% rename from assets/example-nested.html rename to skills/diagram-design/assets/example-nested.html diff --git a/assets/example-pyramid-dark.html b/skills/diagram-design/assets/example-pyramid-dark.html similarity index 100% rename from assets/example-pyramid-dark.html rename to skills/diagram-design/assets/example-pyramid-dark.html diff --git a/assets/example-pyramid-full.html b/skills/diagram-design/assets/example-pyramid-full.html similarity index 100% rename from assets/example-pyramid-full.html rename to skills/diagram-design/assets/example-pyramid-full.html diff --git a/assets/example-pyramid.html b/skills/diagram-design/assets/example-pyramid.html similarity index 100% rename from assets/example-pyramid.html rename to skills/diagram-design/assets/example-pyramid.html diff --git a/assets/example-quadrant-consultant.html b/skills/diagram-design/assets/example-quadrant-consultant.html similarity index 100% rename from assets/example-quadrant-consultant.html rename to skills/diagram-design/assets/example-quadrant-consultant.html diff --git a/assets/example-quadrant-dark.html b/skills/diagram-design/assets/example-quadrant-dark.html similarity index 100% rename from assets/example-quadrant-dark.html rename to skills/diagram-design/assets/example-quadrant-dark.html diff --git a/assets/example-quadrant-full.html b/skills/diagram-design/assets/example-quadrant-full.html similarity index 100% rename from assets/example-quadrant-full.html rename to skills/diagram-design/assets/example-quadrant-full.html diff --git a/assets/example-quadrant.html b/skills/diagram-design/assets/example-quadrant.html similarity index 100% rename from assets/example-quadrant.html rename to skills/diagram-design/assets/example-quadrant.html diff --git a/assets/example-sequence-dark.html b/skills/diagram-design/assets/example-sequence-dark.html similarity index 100% rename from assets/example-sequence-dark.html rename to skills/diagram-design/assets/example-sequence-dark.html diff --git a/assets/example-sequence-full.html b/skills/diagram-design/assets/example-sequence-full.html similarity index 100% rename from assets/example-sequence-full.html rename to skills/diagram-design/assets/example-sequence-full.html diff --git a/assets/example-sequence.html b/skills/diagram-design/assets/example-sequence.html similarity index 100% rename from assets/example-sequence.html rename to skills/diagram-design/assets/example-sequence.html diff --git a/assets/example-state-dark.html b/skills/diagram-design/assets/example-state-dark.html similarity index 100% rename from assets/example-state-dark.html rename to skills/diagram-design/assets/example-state-dark.html diff --git a/assets/example-state-full.html b/skills/diagram-design/assets/example-state-full.html similarity index 100% rename from assets/example-state-full.html rename to skills/diagram-design/assets/example-state-full.html diff --git a/assets/example-state.html b/skills/diagram-design/assets/example-state.html similarity index 100% rename from assets/example-state.html rename to skills/diagram-design/assets/example-state.html diff --git a/assets/example-swimlane-dark.html b/skills/diagram-design/assets/example-swimlane-dark.html similarity index 100% rename from assets/example-swimlane-dark.html rename to skills/diagram-design/assets/example-swimlane-dark.html diff --git a/assets/example-swimlane-full.html b/skills/diagram-design/assets/example-swimlane-full.html similarity index 100% rename from assets/example-swimlane-full.html rename to skills/diagram-design/assets/example-swimlane-full.html diff --git a/assets/example-swimlane.html b/skills/diagram-design/assets/example-swimlane.html similarity index 100% rename from assets/example-swimlane.html rename to skills/diagram-design/assets/example-swimlane.html diff --git a/assets/example-timeline-dark.html b/skills/diagram-design/assets/example-timeline-dark.html similarity index 100% rename from assets/example-timeline-dark.html rename to skills/diagram-design/assets/example-timeline-dark.html diff --git a/assets/example-timeline-full.html b/skills/diagram-design/assets/example-timeline-full.html similarity index 100% rename from assets/example-timeline-full.html rename to skills/diagram-design/assets/example-timeline-full.html diff --git a/assets/example-timeline.html b/skills/diagram-design/assets/example-timeline.html similarity index 100% rename from assets/example-timeline.html rename to skills/diagram-design/assets/example-timeline.html diff --git a/assets/example-tree-dark.html b/skills/diagram-design/assets/example-tree-dark.html similarity index 100% rename from assets/example-tree-dark.html rename to skills/diagram-design/assets/example-tree-dark.html diff --git a/assets/example-tree-full.html b/skills/diagram-design/assets/example-tree-full.html similarity index 100% rename from assets/example-tree-full.html rename to skills/diagram-design/assets/example-tree-full.html diff --git a/assets/example-tree.html b/skills/diagram-design/assets/example-tree.html similarity index 100% rename from assets/example-tree.html rename to skills/diagram-design/assets/example-tree.html diff --git a/assets/example-venn-dark.html b/skills/diagram-design/assets/example-venn-dark.html similarity index 100% rename from assets/example-venn-dark.html rename to skills/diagram-design/assets/example-venn-dark.html diff --git a/assets/example-venn-full.html b/skills/diagram-design/assets/example-venn-full.html similarity index 100% rename from assets/example-venn-full.html rename to skills/diagram-design/assets/example-venn-full.html diff --git a/assets/example-venn.html b/skills/diagram-design/assets/example-venn.html similarity index 100% rename from assets/example-venn.html rename to skills/diagram-design/assets/example-venn.html diff --git a/assets/index.html b/skills/diagram-design/assets/index.html similarity index 100% rename from assets/index.html rename to skills/diagram-design/assets/index.html diff --git a/assets/template-dark.html b/skills/diagram-design/assets/template-dark.html similarity index 100% rename from assets/template-dark.html rename to skills/diagram-design/assets/template-dark.html diff --git a/assets/template-full.html b/skills/diagram-design/assets/template-full.html similarity index 100% rename from assets/template-full.html rename to skills/diagram-design/assets/template-full.html diff --git a/assets/template.html b/skills/diagram-design/assets/template.html similarity index 100% rename from assets/template.html rename to skills/diagram-design/assets/template.html diff --git a/references/onboarding.md b/skills/diagram-design/references/onboarding.md similarity index 100% rename from references/onboarding.md rename to skills/diagram-design/references/onboarding.md diff --git a/references/primitive-annotation.md b/skills/diagram-design/references/primitive-annotation.md similarity index 100% rename from references/primitive-annotation.md rename to skills/diagram-design/references/primitive-annotation.md diff --git a/references/primitive-sketchy.md b/skills/diagram-design/references/primitive-sketchy.md similarity index 100% rename from references/primitive-sketchy.md rename to skills/diagram-design/references/primitive-sketchy.md diff --git a/references/style-guide.md b/skills/diagram-design/references/style-guide.md similarity index 100% rename from references/style-guide.md rename to skills/diagram-design/references/style-guide.md diff --git a/references/type-architecture.md b/skills/diagram-design/references/type-architecture.md similarity index 100% rename from references/type-architecture.md rename to skills/diagram-design/references/type-architecture.md diff --git a/references/type-er.md b/skills/diagram-design/references/type-er.md similarity index 100% rename from references/type-er.md rename to skills/diagram-design/references/type-er.md diff --git a/references/type-flowchart.md b/skills/diagram-design/references/type-flowchart.md similarity index 100% rename from references/type-flowchart.md rename to skills/diagram-design/references/type-flowchart.md diff --git a/references/type-layers.md b/skills/diagram-design/references/type-layers.md similarity index 100% rename from references/type-layers.md rename to skills/diagram-design/references/type-layers.md diff --git a/references/type-nested.md b/skills/diagram-design/references/type-nested.md similarity index 100% rename from references/type-nested.md rename to skills/diagram-design/references/type-nested.md diff --git a/references/type-pyramid.md b/skills/diagram-design/references/type-pyramid.md similarity index 100% rename from references/type-pyramid.md rename to skills/diagram-design/references/type-pyramid.md diff --git a/references/type-quadrant.md b/skills/diagram-design/references/type-quadrant.md similarity index 100% rename from references/type-quadrant.md rename to skills/diagram-design/references/type-quadrant.md diff --git a/references/type-sequence.md b/skills/diagram-design/references/type-sequence.md similarity index 100% rename from references/type-sequence.md rename to skills/diagram-design/references/type-sequence.md diff --git a/references/type-state.md b/skills/diagram-design/references/type-state.md similarity index 100% rename from references/type-state.md rename to skills/diagram-design/references/type-state.md diff --git a/references/type-swimlane.md b/skills/diagram-design/references/type-swimlane.md similarity index 100% rename from references/type-swimlane.md rename to skills/diagram-design/references/type-swimlane.md diff --git a/references/type-timeline.md b/skills/diagram-design/references/type-timeline.md similarity index 100% rename from references/type-timeline.md rename to skills/diagram-design/references/type-timeline.md diff --git a/references/type-tree.md b/skills/diagram-design/references/type-tree.md similarity index 100% rename from references/type-tree.md rename to skills/diagram-design/references/type-tree.md diff --git a/references/type-venn.md b/skills/diagram-design/references/type-venn.md similarity index 100% rename from references/type-venn.md rename to skills/diagram-design/references/type-venn.md