diagram-design-editorial

Q: How do I install diagram-design-editorial?

Run npx skills add https://github.com/reason-machines/design-skills --skill diagram-design-editorial in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/diagram-design-editorial/ (personal) or .claude/skills/diagram-design-editorial/ (project).

by reason-machinesDocs & Writing

Create editorial-quality diagrams in HTML + SVG matching your brand — architecture, flowcharts, sequences, timelines, quadrants, and 9 more types.

Installs: 169
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/design-skills --skill diagram-design-editorial

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads diagram-design-editorial automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

FAQ

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.

How do I install diagram-design-editorial?

Run npx skills add https://github.com/reason-machines/design-skills --skill diagram-design-editorial in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/diagram-design-editorial/ (personal) or .claude/skills/diagram-design-editorial/ (project).

Which AI agents can use diagram-design-editorial?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is diagram-design-editorial safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains diagram-design-editorial?

It is published by reason-machines in reason-machines/design-skills. It has 169 recorded installs.

Popular docs & writing skills

View category →

grill-with-docs

mattpocock/skills

A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.

Docs & Writing1.2M installs

lark-markdown

open.feishu.cn

飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。

Docs & Writing778.7K installs

writing-beats

mattpocock/skills

Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.

Docs & Writing490.7K installs

writing-shape

mattpocock/skills

Writing, exploit: shape raw material into an article, paragraph by paragraph.

Docs & Writing490.2K installs

writing-fragments

mattpocock/skills

Writing, explore: mine raw fragments, no structure yet.

Docs & Writing489.6K installs

writing-for-agents

mattpocock/skills

Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.

Docs & Writing479.3K installs

diagram-design-editorial

Install

Install

Describe the task

Review the result

SKILL.md

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

FAQ

More from reason-machines/design-skills

Popular docs & writing skills