--- name: diagram-design-editorial description: Generate editorial-quality HTML+SVG diagrams (13 types) for blog posts and documentation using Claude Code, with brand-matched styling and no external dependencies. triggers: - make me a diagram - create an architecture diagram - generate a flowchart - I need a sequence diagram - draw a state machine - make an ER diagram - create a timeline diagram - onboard diagram-design to my site --- # Diagram Design — Editorial HTML+SVG Diagrams > Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection. Editorial-quality diagrams for blog posts and documentation. 13 types, self-contained HTML+SVG, no build step, no Mermaid, no shadows. Brand-matched in 60 seconds by reading your website. --- ## Installation ```bash git clone git@github.com:cathrynlavery/diagram-design.git ~/.claude/skills/diagram-design # restart Claude Code — skill registers as `diagram-design` ``` Or symlink from another location: ```bash git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design ln -s ~/code/diagram-design ~/.claude/skills/diagram-design ``` Browse all 13 types locally: ```bash open ~/.claude/skills/diagram-design/assets/index.html ``` --- ## The 13 Diagram Types | Type | Use when… | |---|---| | **Architecture** | Components + connections (services, APIs, infra) | | **Flowchart** | Decision logic, yes/no branches | | **Sequence** | Messages over time (OAuth, API calls, user flows) | | **State machine** | States + transitions (order lifecycle, auth states) | | **ER / data model** | Entities + fields + relationships | | **Timeline** | Events on a horizontal or vertical axis | | **Swimlane** | Cross-functional flows (who does what, when) | | **Quadrant** | Two-axis positioning (impact vs effort, risk vs value) | | **Nested** | Hierarchy by containment (layers inside layers) | | **Tree** | Parent → children (org chart, file tree, decision tree) | | **Layer stack** | Stacked abstractions (OSI model, tech stack) | | **Venn** | Set overlap (2–3 circles) | | **Pyramid / funnel** | Ranked hierarchy or conversion drop-off | **Selection rule:** ask "would a reader learn more from this than from a well-written paragraph?" If no, don't draw. Default to deletion over addition. --- ## Quickstart ``` # In Claude Code — just describe what you need: "Make me an architecture diagram: frontend, backend, Postgres, Redis cache." "I need a quadrant of Q2 projects by impact vs effort." "Give me a sequence diagram of the OAuth 2.0 handshake." "Draw a state machine for an e-commerce order: pending → paid → shipped → delivered." "Timeline of the Roman Empire's key turning points." ``` Claude picks the right type, builds HTML, saves the file. To use a template directly: ```bash cp assets/template.html my-diagram.html # minimal light cp assets/template-full.html my-diagram.html # editorial with summary cards ``` --- ## Brand Onboarding (60 seconds) Without onboarding, diagrams render in neutral stone + rust (warm off-white paper, charcoal ink, rust-orange accent). Run onboarding to match your site: ``` "onboard diagram-design to https://yoursite.com" ``` Claude will: 1. Fetch your homepage 2. Extract dominant palette + font stack 3. Map values to semantic roles: `paper`, `ink`, `muted`, `accent`, `link` 4. Run WCAG AA contrast checks (auto-adjusts failures) 5. Show a proposed diff → write tokens to `references/style-guide.md` ### What gets extracted | Detected from your site | Becomes | |---|---| | `` background | `paper` token | | Primary text color | `ink` token | | Secondary / caption text | `muted` token | | Cards or containers | `paper-2` token | | Most-used brand color (CTA, link, heading) | `accent` token | | `

` font family | `title` font | | `` font family | `node-name` font | | `

` / `` font | `sublabel` font |

### Manual token override

Edit `references/style-guide.md` directly:

```markdown
| Token      | Value     | Role                          |
|------------|-----------|-------------------------------|
| paper      | #F8F5F0   | diagram background            |
| ink        | #1A1A1A   | primary text, borders         |
| muted      | #6B6560   | secondary labels, grid lines  |
| paper-2    | #EEEAE4   | card fills, lane backgrounds  |
| accent     | #B5523A   | focal nodes, 1–2 per diagram  |
| accent-fg  | #FFFFFF   | text on accent-colored nodes  |
```

**First-run gate:** on first use in a new project, if `style-guide.md` is still at default, Claude pauses and asks: *"Run onboarding, paste tokens manually, or proceed with default?"*

---

## Design System Rules

Every diagram generated by this skill follows these non-negotiable constraints:

### Grid
- All coordinates, widths, gaps divisible by **4px** — prevents the AI-generated jitter
- No shadows anywhere
- Max border-radius: **10px**
- Borders: **1px hairline** only

### Typography (three families, three roles)
```
Instrument Serif  → titles, italic editorial callouts
Geist Sans        → node names, labels (primary UI text)
Geist Mono        → technical sublabels (ports, URLs, field types, IDs)
```
Mono is for technical content specifically — not a blanket "dev aesthetic."

### Color discipline
- **One accent color** per diagram
- Accent reserved for **1–2 focal nodes** — the things the reader looks at first
- Everything else: `ink`, `muted`, `paper-2`
- Target visual density: **4/10** — ruthlessly sparse

### Focal nodes (coral tint)
```html



  Primary Component





  Secondary Component

```

---

## Code Examples

### Architecture Diagram (minimal structure)

```html



  
  





```

### Quadrant Diagram

```html

```

### Sequence Diagram

```html

```

---

## Primitives

### Annotation Callout
Italic Instrument Serif + dashed Bézier leader for editorial asides in diagram margins:

```html


  






only runs on cold start
```

### Sketchy Filter (hand-drawn variant)
For essays and informal posts — not technical docs:

```html

  
    
    
  




```

---

## File Structure

```
diagram-design/
├── SKILL.md                         # type selection guide, design rules
├── references/
│   ├── style-guide.md               # color + font tokens (edit for your brand)
│   ├── onboarding.md                # URL-to-tokens extraction spec
│   ├── type-architecture.md
│   ├── type-flowchart.md
│   ├── type-sequence.md
│   ├── type-state.md
│   ├── type-er.md
│   ├── type-timeline.md
│   ├── type-swimlane.md
│   ├── type-quadrant.md
│   ├── type-nested.md
│   ├── type-tree.md
│   ├── type-layers.md
│   ├── type-venn.md
│   ├── type-pyramid.md
│   ├── primitive-annotation.md
│   └── primitive-sketchy.md
├── assets/
│   ├── index.html                   # live gallery, all 13 types, 3 variants each
│   ├── template.html                # minimal light scaffold
│   ├── template-full.html           # editorial with summary cards
│   └── example-.html          # 39 files: 3 variants × 13 types
└── docs/screenshots/
```

**Context loading (what Claude reads per request):**

| Request | Files loaded |
|---|---|
| Any specific type | `SKILL.md` + `references/type-.md` |
| Onboarding | `SKILL.md` + `onboarding.md` + `style-guide.md` |
| Add annotation | `SKILL.md` + `primitive-annotation.md` |
| Hand-drawn variant | `SKILL.md` + `primitive-sketchy.md` |

Only the relevant reference file loads — keeps context tight regardless of how many types exist.

---

## Common Patterns

### Choosing the right type
```
# Decision logic with yes/no branches → flowchart
"Should I use X?" branching → flowchart

# Time-ordered messages between actors → sequence
OAuth, webhooks, API calls → sequence

# Lifecycle with transitions → state machine
Order status, auth state, connection state → state machine

# Two-axis comparison → quadrant
Impact vs effort, risk vs value → quadrant

# Ranked importance → pyramid
Priority tiers, conversion funnel → pyramid

# System components and how they connect → architecture
Services, databases, queues → architecture
```

### Controlling focal emphasis
```
# Accent = 1–2 nodes only — the main point of the diagram
# If everything is accent, nothing is accent

# Wrong: 5 accent nodes in a 7-node diagram
# Right: 1 accent node (the bottleneck / the thing that matters)
```

### Density calibration
```
# Target: 4/10 density
# 5 nodes is usually enough
# 8 nodes is usually too many
# 12 nodes → split into two diagrams or use layers/nested

# Eliminate any node the reader doesn't need to understand the point
```

---

## Troubleshooting

**Diagrams look generic / AI-generated**
- Check all coordinates are divisible by 4 — misaligned grids are the tell
- Reduce node count; every node must earn its place
- Confirm only 1–2 nodes use `var(--accent)`; the rest should be `var(--paper-2)`

**Colors don't match my site**
- Run onboarding: `"onboard diagram-design to https://yoursite.com"`
- Or edit `references/style-guide.md` directly with your hex values

**Fonts not loading**
- Diagrams use system fallbacks by default — Geist and Instrument Serif only load if available
- Add Google Fonts or Bunny Fonts link in `` for exact rendering:

```html


```

**WCAG contrast failing on my brand colors**
- Onboarding runs contrast checks automatically and proposes adjustments
- Manual fix: darken `ink` or lighten `paper` until ratio ≥ 4.5:1 at 12px

**Diagram too dense / cluttered**
- Delete nodes until it hurts, then delete one more
- Split into two diagrams: overview + detail
- Use a nested or layers type if you need to show hierarchy without individual connections

**Wrong type chosen**
- Override explicitly: `"Make this a swimlane, not a flowchart — rows for Design, Eng, PM"`

---

## When NOT to use this skill

- Quick ASCII/unicode diagrams for terminal or tweets → use wiretext
- Before/after comparisons → use a table
- Simple lists → use bullets
- Single-shape "diagrams" (one box, one label) → write the sentence instead