| name | diagram-design-editorial |
| description | Create editorial-quality diagrams in HTML + SVG matching your brand — architecture, flowcharts, sequences, timelines, quadrants, and 9 more types. |
| triggers | ["create a diagram","make an architecture diagram","build a flowchart","generate a sequence diagram","design a timeline","create a quadrant chart","make an org chart","build a state machine diagram"] |
Diagram Design — Editorial Diagrams
Skill by ara.so — Design Skills collection.
Editorial-quality diagrams that match your brand. Fourteen diagram types (architecture, flowchart, sequence, state machine, ER, timeline, swimlane, quadrant, nested, tree, org chart, venn, layers, pyramid) shipped as self-contained HTML + SVG files. No build step, no shadows, no generic rounded boxes.
The skill reads your website and extracts colors + fonts, then applies them across every diagram. Your site's paper color becomes the diagram background. Your CTA color becomes the focal accent. Your body font becomes the node label family.
Installation
git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design
Restart Claude Code. The skill registers as diagram-design.
Alternative (plugin install):
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design
For Codex:
npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design
Brand Onboarding (60 seconds)
Out of the box, diagrams use a clean default palette (jet-black + atomic-tangerine). To apply your brand:
You: "onboard diagram-design to https://yoursite.com"
Claude: → fetches homepage
→ extracts dominant palette + font stack
→ maps to semantic roles (paper, ink, muted, accent)
→ shows proposed diff
→ writes to references/style-guide.md
You: "apply it"
What gets extracted:
| From your site | Becomes |
|---|
<body> background | paper token |
| Primary text color | ink token |
| Secondary text | muted token |
| Cards/containers | paper-2 token |
| Brand color (CTA/link) | accent token |
<h1> font | title font |
<body> font | node-name font |
<code> font | sublabel font |
Contrast checks run automatically (WCAG AA). If a color fails at diagram sizes (9–12px), the skill proposes an adjusted value.
Manual override: Edit skills/diagram-design/references/style-guide.md directly.
Creating Diagrams
Quick Start
Just ask Claude to make a diagram — it will pick the right type:
"Make an architecture diagram of my app: frontend, backend, database, Redis cache."
"I need a quadrant showing Q2 projects by impact vs effort."
"Give me a sequence diagram of the OAuth handshake."
"Create a timeline of our product milestones."
Claude will:
- Choose the appropriate diagram type
- Build the HTML + SVG
- Save it as a self-contained file
- Apply your brand tokens from
style-guide.md
The 14 Diagram Types
| Type | Use for |
|---|
| Architecture | Components + connections |
| Flowchart | Decision logic |
| Sequence | Messages over time |
| State machine | States + transitions |
| ER / data model | Entities + fields |
| Timeline | Events on an axis |
| Swimlane | Cross-functional flow |
| Quadrant | Two-axis positioning |
| Nested | Hierarchy by containment |
| Tree | Parent → children |
| Org chart | Ownership + routing |
| Venn | Set overlap |
| Layers | Stacked abstractions |
| Pyramid / funnel | Ranked hierarchy or drop-off |
Bonus: Consultant 2×2 (scenario matrix with named cells)
Template Scaffolds
Start from a template:
cp assets/template.html my-diagram.html
cp assets/template-full.html my-diagram.html
Each template is self-contained HTML with inline SVG and CSS.
Working Code Examples
Example 1: Architecture Diagram
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>App Architecture</title>
<style>
:root {
--paper: #FEFEFE;
--ink: #1A1A1A;
--accent: #EB6C36;
--muted: #64748B;
--hairline: #D1D5DB;
}
body {
margin: 0;
padding: 48px;
background: var(--paper);
font-family: 'Geist', -apple-system, sans-serif;
}
svg {
display: block;
max-width: 100%;
height: auto;
}
</style>
</head>
<body>
<svg viewBox="0 0 800 600" xmlns="http://www.w3.org/2000/svg">
Frontend
Backend API
PostgreSQL
HTTPS
SQL
Example 2: Flowchart
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Decision Flow</title>
<style>
:root {
--paper: #FEFEFE;
--ink: #1A1A1A;
--accent: #EB6C36;
--muted: #64748B;
--hairline: #D1D5DB;
}
body {
margin: 0;
padding: 48px;
background: var(--paper);
font-family: 'Geist', -apple-system, sans-serif;
}
</style>
</head>
<body>
<svg viewBox="0 0 600 800" xmlns="http://www.w3.org/2000/svg">
<rect x="220" y="40" width= =
= =/>
Start
Valid user?
Grant access
Show error
Yes
No
Example 3: Timeline
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Product Timeline</title>
<style>
:root {
--paper: #FEFEFE;
--ink: #1A1A1A;
--accent: #EB6C36;
--muted: #64748B;
--hairline: #D1D5DB;
}
body {
margin: 0;
padding: 48px;
background: var(--paper);
font-family: 'Geist', -apple-system, sans-serif;
}
</style>
</head>
<body>
<svg viewBox="0 0 900 300" xmlns="http://www.w3.org/2000/svg">
<line x1="100" y1="150" x2= =
= =/>
Beta Launch
Jan 2024
Feature X
Mar 2024
Public GA
May 2024
Design System Rules
Every diagram follows these constraints (enforced in all 14 type references):
Grid & Spacing
- All coordinates, widths, gaps divisible by 4 (non-negotiable)
- Base unit: 4px
- Typical node padding: 16px
- Gap between nodes: 40px minimum
- Margin from edge: 48px
Colors
- One accent color — used for 1–2 focal elements only
- Coral-tinted focal nodes:
#FFF5F0 fill + accent stroke
- Non-focal nodes:
paper fill + hairline stroke
- Connection lines:
muted (solid or dashed)
Typography
- Instrument Serif — titles + italic editorial callouts
- Geist Sans — node names, labels
- Geist Mono — technical sublabels (ports, URLs, field types)
- Font sizes: 10px (sublabel), 12px (label), 14px (node name), 18px (title)
Shapes
- Max border-radius: 10px (8px typical for nodes)
- Border width: 1px (hairline), 2px (focal)
- No shadows, no gradients, no blur effects
Density
- Target density: 4/10 — every node earns its place
- Show 5–9 primary nodes
- Sublabels only when they add clarity (ports, field types, conditions)
Configuration
All style tokens live in skills/diagram-design/references/style-guide.md:
| Role | Token | Light default | Dark default |
|------------|--------------|---------------|---------------|
| Background | `paper` | `#FEFEFE` | `#0F0F0F` |
| Primary | `ink` | `#1A1A1A` | `#E5E5E5` |
| Accent | `accent` | `#EB6C36` | `#F97316` |
| Muted | `muted` | `#64748B` | `#94A3B8` |
| Hairline | `hairline` | `#D1D5DB` | `#334155` |
| Card | `paper-2` | `#F8F9FA` | `#1A1A1A` |
Font stack:
| Role | Family |
|------------|---------------------------------------------|
| Title | 'Instrument Serif', Georgia, serif |
| Node name | 'Geist', -apple-system, sans-serif |
| Sublabel | 'Geist Mono', 'SF Mono', Consolas, monospace|
Edit this file to override tokens globally, or run onboard diagram-design to <url> to extract from a website.
Common Patterns
Adding Editorial Annotations
Italic callouts that sit in the margins:
"Add an annotation to this diagram explaining why Redis sits between the backend and database."
Claude will insert:
<text x="520" y="340" font-size="11" font-style="italic"
font-family="'Instrument Serif', Georgia, serif" fill="var(--muted)">
Redis caches hot queries,
</text>
<text x="520" y="356" font-size="11" font-style="italic"
font-family="'Instrument Serif', Georgia, serif" fill="var(--muted)">
reducing DB load by 70%.
</text>
<path d="M 500 300 Q 510 320, 515 335" stroke="var(--muted)"
stroke-width="1" stroke-dasharray="2 3" fill="none"/>
Hand-Drawn Variant (Sketchy Filter)
"Make this diagram look hand-drawn."
Applies SVG filters for rough edges:
<defs>
<filter id="sketchy">
<feTurbulence type="fractalNoise" baseFrequency="0.05" numOctaves="2" result="noise"/>
<feDisplacementMap in="SourceGraphic" in2="noise" scale="2"/>
</filter>
</defs>
<rect x="100" y="100" width="160" height="80" filter="url(#sketchy)" ... />
Dark Mode Variant
All templates include CSS custom properties. To generate a dark variant:
"Create a dark mode version of this diagram."
Claude will swap tokens:
:root {
--paper: #0F0F0F;
--ink: #E5E5E5;
--accent: #F97316;
--muted: #94A3B8;
--hairline: #334155;
}
Consultant 2×2 Quadrant
Named scenario matrix (4 cells, each with a label):
"Make a 2x2 showing product strategy: differentiation vs cost, and broad vs niche market."
Generates quadrant with named cells:
<rect x="100" y="100" width="300" height="200"
fill="#FFF5F0" stroke="var(--accent)" stroke-width="2" rx="8"/>
<text x="250" y="190" text-anchor="middle"
font-size="14" font-weight="500" fill="var(--ink)">
Premium Niche
</text>
<text x="250" y="210" text-anchor="middle"
font-size="10" fill="var(--muted)">
High margin, focused
</text>
Browsing the Gallery
Open the live gallery to see all 14 types with light/dark/editorial tabs:
open ~/.claude/skills/diagram-design/assets/index.html
Or from the repo root:
open skills/diagram-design/assets/index.html
Each example includes three variants:
- Minimal Light —
template.html scaffold
- Minimal Dark — dark mode tokens
- Full Editorial —
template-full.html with annotation callouts
Troubleshooting
"Diagram looks generic / AI-generated"
Cause: Coordinates or gaps not divisible by 4, or too many accent colors.
Fix: Check the SVG for non-4-divisible x/y/width/height. Ensure only 1–2 nodes have the accent stroke.
"Fonts not loading"
Cause: Font families require web fonts (Geist, Instrument Serif).
Fix: Add to <head>:
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&display=swap" rel="stylesheet">
For Geist, use the Vercel CDN or local files:
<link href="https://cdn.jsdelivr.net/npm/@vercel/style-guide@latest/fonts/geist.css" rel="stylesheet">
"Onboarding failed — no colors extracted"
Cause: Target site uses inline styles or CSS-in-JS that isn't in the DOM on initial load.
Fix: Manually set tokens in references/style-guide.md:
| Role | Token | Value |
|--------|----------|-----------|
| paper | `paper` | `#FFFFFF` |
| ink | `ink` | `#000000` |
| accent | `accent` | `#FF6B35` |
"Contrast check failed"
Cause: Extracted ink color fails WCAG AA at small sizes (9–12px).
Fix: The skill auto-adjusts and shows a proposed value. Accept it, or override in style-guide.md.
"Diagram type not recognized"
Cause: Request didn't match one of the 14 types.
Fix: Be explicit:
"Make a sequence diagram of the login flow."
"Create an architecture diagram showing microservices."
"Build a quadrant chart for prioritization."
See the selection guide in SKILL.md for triggers.
Environment Variables
If deploying diagrams to a server that applies tokens via env vars:
export DIAGRAM_PAPER="#FEFEFE"
export DIAGRAM_INK="#1A1A1A"
export DIAGRAM_ACCENT="#EB6C36"
Then reference in HTML:
<style>
:root {
--paper: ${DIAGRAM_PAPER};
--ink: ${DIAGRAM_INK};
--accent: ${DIAGRAM_ACCENT};
}
</style>
(Most users will edit style-guide.md directly instead.)
Advanced Usage
Exporting as PNG
Diagrams are self-contained HTML. To export as PNG:
npx playwright screenshot my-diagram.html my-diagram.png --full-page
Embedding in Markdown
Use an <iframe> or convert to data URI:
Or link directly:
Custom Diagram Type
To add a 15th type:
- Create
references/type-custom.md with the same structure as existing types
- Add selection trigger to
SKILL.md:
- **Custom diagram** — <use case>
- Trigger: "create a custom diagram"
- Drop an example in
assets/example-custom.html
Claude will auto-load the reference when triggered.
License: MIT
Repo: github.com/cathrynlavery/diagram-design
Gallery: skills/diagram-design/assets/index.html
