diagram-design-editorial

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

# Clone and symlink into Claude Code's skills directory
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:

1. Choose the appropriate diagram type
2. Build the HTML + SVG
3. Save it as a self-contained file
4. 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:

# Minimal light variant
cp assets/template.html my-diagram.html

# Full editorial with summary cards
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 node (focal, coral tint) -->
    <rect x="100" y="100" width="160" height="80" 
          fill="#FFF5F0" stroke="var(--accent)" stroke-width="2" rx="8"/>
    <text x="180" y="145" text-anchor="middle" 
          font-size="14" font-weight="500" fill="var(--ink)">
      Frontend
    </text>
    
    <!-- Backend node -->
    <rect x="100" y="260" width="160" height="80"
          fill="var(--paper)" stroke="var(--hairline)" stroke-width="1" rx="8"/>
    <text x="180" y="305" text-anchor="middle"
          font-size="14" font-weight="500" fill="var(--ink)">
      Backend API
    </text>
    
    <!-- Database node -->
    <rect x="400" y="260" width="160" height="80"
          fill="var(--paper)" stroke="var(--hairline)" stroke-width="1" rx="8"/>
    <text x="480" y="305" text-anchor="middle"
          font-size="14" font-weight="500" fill="var(--ink)">
      PostgreSQL
    </text>
    
    <!-- Connection lines -->
    <path d="M 180 180 L 180 260" stroke="var(--muted)" 
          stroke-width="1" fill="none" stroke-dasharray="4 4"/>
    <path d="M 260 300 L 400 300" stroke="var(--muted)"
          stroke-width="1" fill="none" stroke-dasharray="4 4"/>
    
    <!-- Labels on connections -->
    <text x="190" y="220" font-size="10" fill="var(--muted)"
          font-family="'Geist Mono', monospace">
      HTTPS
    </text>
    <text x="310" y="290" font-size="10" fill="var(--muted)"
          font-family="'Geist Mono', monospace">
      SQL
    </text>
  </svg>
</body>
</html>

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">
    <!-- Start node (pill shape) -->
    <rect x="220" y="40" width="160" height="48"
          fill="var(--ink)" rx="24"/>
    <text x="300" y="68" text-anchor="middle"
          font-size="12" font-weight="500" fill="var(--paper)">
      Start
    </text>
    
    <!-- Decision node (diamond) -->
    <path d="M 300 160 L 380 220 L 300 280 L 220 220 Z"
          fill="var(--paper)" stroke="var(--hairline)" stroke-width="1"/>
    <text x="300" y="225" text-anchor="middle"
          font-size="12" fill="var(--ink)">
      Valid user?
    </text>
    
    <!-- Process nodes -->
    <rect x="420" y="196" width="140" height="48"
          fill="var(--paper)" stroke="var(--hairline)" stroke-width="1" rx="8"/>
    <text x="490" y="224" text-anchor="middle"
          font-size="12" fill="var(--ink)">
      Grant access
    </text>
    
    <rect x="40" y="196" width="140" height="48"
          fill="#FFF5F0" stroke="var(--accent)" stroke-width="2" rx="8"/>
    <text x="110" y="224" text-anchor="middle"
          font-size="12" fill="var(--ink)">
      Show error
    </text>
    
    <!-- Arrows -->
    <path d="M 300 88 L 300 160" stroke="var(--muted)" 
          stroke-width="1" marker-end="url(#arrowhead)"/>
    <path d="M 380 220 L 420 220" stroke="var(--muted)"
          stroke-width="1" marker-end="url(#arrowhead)"/>
    <path d="M 220 220 L 180 220" stroke="var(--accent)"
          stroke-width="1" marker-end="url(#arrowhead-accent)"/>
    
    <!-- Arrow markers -->
    <defs>
      <marker id="arrowhead" markerWidth="6" markerHeight="6"
              refX="5" refY="3" orient="auto">
        <polygon points="0 0, 6 3, 0 6" fill="var(--muted)"/>
      </marker>
      <marker id="arrowhead-accent" markerWidth="6" markerHeight="6"
              refX="5" refY="3" orient="auto">
        <polygon points="0 0, 6 3, 0 6" fill="var(--accent)"/>
      </marker>
    </defs>
    
    <!-- Labels -->
    <text x="390" y="210" font-size="10" fill="var(--muted)">Yes</text>
    <text x="190" y="210" font-size="10" fill="var(--accent)">No</text>
  </svg>
</body>
</html>

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">
    <!-- Timeline axis -->
    <line x1="100" y1="150" x2="800" y2="150"
          stroke="var(--hairline)" stroke-width="1"/>
    
    <!-- Event 1 (focal) -->
    <circle cx="200" cy="150" r="8" fill="var(--accent)"/>
    <text x="200" y="120" text-anchor="middle"
          font-size="12" font-weight="500" fill="var(--ink)">
      Beta Launch
    </text>
    <text x="200" y="180" text-anchor="middle"
          font-size="10" fill="var(--muted)"
          font-family="'Geist Mono', monospace">
      Jan 2024
    </text>
    
    <!-- Event 2 -->
    <circle cx="400" cy="150" r="6" fill="var(--muted)"/>
    <text x="400" y="120" text-anchor="middle"
          font-size="12" fill="var(--ink)">
      Feature X
    </text>
    <text x="400" y="180" text-anchor="middle"
          font-size="10" fill="var(--muted)"
          font-family="'Geist Mono', monospace">
      Mar 2024
    </text>
    
    <!-- Event 3 -->
    <circle cx="600" cy="150" r="6" fill="var(--muted)"/>
    <text x="600" y="120" text-anchor="middle"
          font-size="12" fill="var(--ink)">
      Public GA
    </text>
    <text x="600" y="180" text-anchor="middle"
          font-size="10" fill="var(--muted)"
          font-family="'Geist Mono', monospace">
      May 2024
    </text>
  </svg>
</body>
</html>

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:

<!-- Annotation callout -->
<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>
<!-- Dashed leader to relevant node -->
<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>

<!-- Apply to shapes -->
<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:

<!-- Top-left cell -->
<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:

# Using headless Chrome
npx playwright screenshot my-diagram.html my-diagram.png --full-page

# Or manually: open in browser, screenshot at 2x zoom for retina

Embedding in Markdown

Use an <iframe> or convert to data URI:

![Architecture](data:image/svg+xml;base64,...)

Or link directly:

![Architecture](./diagrams/architecture.html)

Custom Diagram Type

To add a 15th type:

1. Create references/type-custom.md with the same structure as existing types
2. Add selection trigger to SKILL.md:

   - **Custom diagram** — <use case>
     - Trigger: "create a custom diagram"
   

3. 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