How do I install the Diagram Design Editorial skill?

Run npx skillmds@latest add aradotso/diagram-design-editorial in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Diagram Design Editorial skill do?

Create editorial-quality diagrams in HTML + SVG matching your brand — architecture, flowcharts, sequences, timelines, quadrants, and 9 more types. It is listed under Web & Frontend on SkillMD.

Is Diagram Design Editorial safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Diagram Design Editorial?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Diagram Design Editorial free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Diagram Design Editorial?

aradotso (@aradotso) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Diagram Design Editorial by aradotso

Name: Diagram Design Editorial
Author: aradotso

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:

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:

# 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:

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

Diagram Design Editorial

File contents

Diagram Design — Editorial Diagrams

Installation

Brand Onboarding (60 seconds)

Creating Diagrams

Quick Start

The 14 Diagram Types

Template Scaffolds

Working Code Examples

Example 1: Architecture Diagram

Example 2: Flowchart

Example 3: Timeline

Design System Rules

Grid & Spacing

Colors

Typography

Shapes

Density

Configuration

Common Patterns

Adding Editorial Annotations

Hand-Drawn Variant (Sketchy Filter)

Dark Mode Variant

Consultant 2×2 Quadrant

Browsing the Gallery

Troubleshooting

"Diagram looks generic / AI-generated"

"Fonts not loading"

"Onboarding failed — no colors extracted"

"Contrast check failed"

"Diagram type not recognized"

Environment Variables

Advanced Usage

Exporting as PNG

Embedding in Markdown

Custom Diagram Type

Frequently asked questions

Diagram Design Editorial

File contents

Diagram Design — Editorial Diagrams

Installation

Brand Onboarding (60 seconds)

Creating Diagrams

Quick Start

The 14 Diagram Types

Template Scaffolds

Working Code Examples

Example 1: Architecture Diagram

Example 2: Flowchart

Example 3: Timeline

Design System Rules

Grid & Spacing

Colors

Typography

Shapes

Density

Configuration

Common Patterns

Adding Editorial Annotations

Hand-Drawn Variant (Sketchy Filter)

Dark Mode Variant

Consultant 2×2 Quadrant

Browsing the Gallery

Troubleshooting

"Diagram looks generic / AI-generated"

"Fonts not loading"

"Onboarding failed — no colors extracted"

"Contrast check failed"

"Diagram type not recognized"

Environment Variables

Advanced Usage

Exporting as PNG

Embedding in Markdown

Custom Diagram Type

Related skills

Frequently asked questions

How do I install the Diagram Design Editorial skill?

What does the Diagram Design Editorial skill do?

Is Diagram Design Editorial safe to use?

Which AI agents work with Diagram Design Editorial?

Is Diagram Design Editorial free to use?

Who published Diagram Design Editorial?