diagram-design：为 Claude Code、Codex 和 Pi 提供 27 种编辑级图表

你的设计师不会讨厌的编辑级图表。

2.0 新增功能——Loop：以共享内存中心为核心的飞轮。虚线表示回写。

27 种类型。一项适用于 Claude Code、Codex 和 Pi 的 Agent Skill。60 秒获得你的品牌风格——该 Skill 会读取你的网站，并将颜色和字体映射至每一张图表。已经在 draw.io 或 Mermaid 中拥有图表？将源文件交给它，它会按你的受众所需的格式、尺寸和细节层级重新绘制。

不需要 Figma。没有千篇一律的圆角框。无需花 30 分钟挑选颜色。

---

我在 littlemight.com 写作（业余还经营 BestSelf.co）。每次我需要一张图表——架构草图、流程图，或是一座展示最重要事项的金字塔——我都会询问 Claude，但得到的总是一个通用圆角框图，和网站其余部分看起来完全不搭。最后要么得和 Figma 缠斗 30 分钟，要么干脆不做图。

于是我为此构建了一项 Claude Code Skill。27 种类型，编辑级品质，通过读取你的网站在 60 秒内匹配你的品牌。

最高质量的动作通常是删除。 每个节点都必须证明自己有存在价值。强调色只留给读者首先应关注的 1—2 个对象。目标信息密度：4/10。

---

全部 27 种图表均提供三种变体：极简浅色、极简深色和完整编辑风格。可直接在浏览器中打开任意图表——无需构建步骤、无需 JavaScript、无需外部图片。

架构组件 + 连接关系	流程图决策逻辑	时序图随时间发生的消息
状态机状态 + 转换	ER / 数据模型实体 + 字段	时间线坐标轴上的事件
泳道图跨职能流程	象限图双轴定位	嵌套图按包含关系展示层级
树形图父节点 → 子节点	组织结构图所有权 + 路由	维恩图集合重叠
层叠图堆叠式抽象层	金字塔 / 漏斗排序层级或流失情况	咨询顾问式 2×2情景矩阵 · 命名单元格
雷达图 / 蜘蛛图多轴比较	循环图飞轮 · 围绕中心的站点	IT 当前状态遗留系统全景 · 现代化
高层图集群上的端到端技术栈	柱状图分类比较	折线图随时间变化的趋势
甘特图时间线上的任务和阶段	散点图分布与相关性	流程多参与者顺序工作流
奖章架构多层数据存储	数据流按角色划分的流水线步骤	DP 集成来源 → 核心 → 消费者
DP 安全矩阵按角色划分的访问权限

浏览在线图库： 在浏览器中打开 skills/diagram-design/assets/index.html，即可通过浅色 / 深色 / 完整编辑风格标签浏览全部 27 种图表。

---

Pi：

pi install https://github.com/cathrynlavery/diagram-design

在已打开的 Pi 会话中运行 /reload。Pi 会让该 Skill 可用于匹配的图表请求；使用 /skill:diagram-design 可显式调用它。Pi 还会加载 /export-diagram 提示词模板。

Claude Code：

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

Claude Cowork： Customize → Directory → Plugins → + → 粘贴 cathrynlavery/diagram-design → Sync，然后从 Personal 列表安装。

Codex：

npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design

托管安装很方便，但对 references/style-guide.md 的修改可能会被软件包更新替换。如果你计划自定义风格指南，请克隆仓库并安装本地路径：

git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design

# Pi：将此检出目录注册为本地软件包
pi install ~/code/diagram-design

# Claude Code：为内部 Skill 创建符号链接
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

共享 Skill 位于 skills/diagram-design/。Pi 通过仓库标准的 skills/ 软件包目录发现它；Claude Code、Codex 和其他兼容 Agent Skills 的工具则使用同一批文件。

---

引导配置——让它呈现为_你的_品牌

核心目标是：用你的颜色和字体交付编辑级图表，而不是通用模板。

开箱即用时，图表采用干净的 漆黑 + 原子橙 配色（烟白纸面、漆黑文字、原子橙强调色、蓝灰弱化色、银色细线）。已经足以直接截图使用。但花 60 秒完成引导配置会更好——该 Skill 会从你的网站提取品牌信息，并将其应用到每张图表。

你：     "为 https://yoursite.com 配置 diagram-design"
Agent：  → 获取首页
        → 提取主导配色 + 字体栈
        → 将检测到的值映射至语义角色：
            paper, ink, muted, accent, link
        → 展示建议的 diff
        → 将你的令牌写入 references/style-guide.md
你：     "是，应用它"

此后每一张新图表都会使用你的颜色。你网站的纸面颜色会成为图表背景。你的 CTA 颜色会成为视觉焦点强调色。你的正文字体栈会成为节点标签字体族。

会提取什么

从网站检测到的内容	对应为
<body> 背景	paper 令牌
主文本颜色	ink 令牌
次要 / 图注文本	muted 令牌
卡片或容器	paper-2 令牌
使用最频繁的品牌颜色（CTA、链接、标题）	accent 令牌
<h1> 字体族	title 字体
<body> 字体族	node-name 字体
<code> / <pre> 字体	sublabel 字体

自动执行对比度检查

在写入令牌前，该 Skill 会验证 ink 在 paper 上的 WCAG AA 对比度。如果你的网站有颜色无法在图表尺寸（9—12px）下通过对比度要求，它会提出调整后的值并解释原因。

每个图表模板都会为内联 SVG 提供无障碍名称与描述：role="img"、可解析的 aria-labelledby，以及位于首个子元素位置的 <title> / <desc> 槽位。ID 会按图表和变体添加前缀，因此可以安全地在同一个页面中内联多个 SVG 导出内容，而不会出现重复的无障碍名称 ID。装饰性的样本图标则会对辅助技术隐藏。

想手动设置令牌？打开 skills/diagram-design/references/style-guide.md 并编辑表格。所有下游内容均从这里读取——全部 27 种图表、标注原语和图库都会继承语义角色名称（如 accent，而不是 #eb6c36）。

该 Skill 不会悄悄地把默认皮肤图表交付到已有品牌的项目中。在新项目中首次使用时，它会检查 style-guide.md 是否已自定义。如果没有，它会暂停并询问：

“这是你在此项目中的第一张图表。风格指南仍为默认状态。想运行引导配置、手动粘贴令牌，还是继续使用默认设置？”

完整规范参见 skills/diagram-design/references/onboarding.md。

---

# 从克隆的检出目录中打开图库，查看全部 27 种图表
open skills/diagram-design/assets/index.html       # macOS
xdg-open skills/diagram-design/assets/index.html  # Linux

# 在 Claude Code、Codex 或 Pi 中提出请求：
# "为我的应用制作一张架构图：前端、后端、数据库、Redis 缓存。"
# "我需要一个按影响力与投入程度展示 Q2 项目的象限图。"
# "给我一个带 401 令牌刷新机制的 bearer 调用时序图。"
# （分支刷新使用 type-sequence.md 中的 ALT 组合片段语法；
#  参见 skills/diagram-design/assets/example-sequence-oauth.html ——并非完整的授权码握手流程）

你的 Agent 会选择合适类型、构建 HTML 并保存。你也可以直接从模板开始：

cp skills/diagram-design/assets/template.html my-diagram.html        # 极简浅色
cp skills/diagram-design/assets/template-full.html my-diagram.html   # 带摘要卡片的编辑风格

---

从 draw.io 或 Mermaid 导入

已经在 draw.io / diagrams.net 或 Mermaid 中拥有图表？将源文件交给该 Skill，它会对其进行重绘——保留相同内容，采用这一设计系统，并适配任何目标交付需求。

一个包含 12 个节点的 draw.io 文件，以 balanced 细节层级为博客文章重绘。源文件中的六种柔和填充色变成一种强调色；手工拖拽的坐标变成了 4px 网格。

/diagram-design:import platform.drawio
/diagram-design:import platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-de

Editorial diagrams your designer won't hate.

New in 2.0 — the Loop: flywheels with a shared-memory hub. The dashed lines are the write-backs.

27 types. One agent skill for Claude Code, Codex, and Pi. Your brand in 60 seconds — the skill reads your website and maps colors + fonts to every diagram. Already have diagrams in draw.io or Mermaid? Point it at the source and it redraws them at the format, size, and level of detail your audience needs.

No Figma. No generic rounded boxes. No 30-minute color-picking sessions.

---

I write at littlemight.com (and run BestSelf.co on the side). Every time I needed a diagram — an architecture sketch, a flowchart, a pyramid of what matters most — I'd ask Claude and get back a generic rounded-box thing that looked nothing like the rest of the site. I'd either fight with Figma for 30 minutes or just skip the diagram.

So I built a Claude Code skill for it. Twenty-seven types, editorial quality, matches your brand in 60 seconds by reading your website.

The highest-quality move is usually deletion. Every node earns its place. The accent color is reserved for the 1–2 things the reader should look at first. Target density: 4/10.

---

All 27 diagrams ship in three variants: minimal light, minimal dark, and full-editorial. Open any of them directly in a browser — no build step, no JS, no external images.

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

Layer stack
Stacked abstractions |
Pyramid / funnel
Ranked hierarchy or drop-off |
Consultant 2×2
Scenario matrix · named cells

Radar / Spider
Multi-axis comparison |
Loop
Flywheel · stations around a hub |
IT current-state
Legacy landscape · modernization

High-Level
End-to-end stack on a cluster |
Bar chart
Categorical comparison |
Line chart
Trends over time

Gantt
Tasks and phases on a timeline |
Scatter plot
Distribution and correlation |
Process
Multi-actor sequential workflow

Medallion
Multi-tier data storage |
Data flow
Role-scoped pipeline steps |
DP integration
Sources → core → consumers

DP security matrix
Per-role access permissions | |

Browse the live gallery: open skills/diagram-design/assets/index.html in your browser to flip through all 27 diagrams with light / dark / full-editorial tabs.

---

Pi:

pi install https://github.com/cathrynlavery/diagram-design

Run /reload in an open Pi session. Pi makes the skill available for matching diagram requests; use /skill:diagram-design to invoke it explicitly. Pi also loads the /export-diagram prompt template.

Claude Code:

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

Claude Cowork: Customize → Directory → Plugins → + → paste cathrynlavery/diagram-design → Sync, then install from the Personal list.

Codex:

npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design

Managed installs are convenient, but changes to references/style-guide.md may be replaced by package updates. Clone the repo and install the local path if you plan to customize the style guide:

git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design

# Pi: register the checkout as a local package
pi install ~/code/diagram-design

# Claude Code: symlink the inner skill
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

The shared skill lives at skills/diagram-design/. Pi discovers it through the repo's standard skills/ package directory; Claude Code, Codex, and other Agent Skills-compatible tools use the same files.

---

Onboarding — make it look like your brand

The whole point: ship editorial-quality diagrams in your colors and typography, not a generic template.

Out of the box, diagrams render in a clean jet-black + atomic-tangerine palette (white-smoke paper, jet-black ink, atomic-tangerine accent, blue-slate muted, silver hairlines). Good enough to screenshot straight away. But 60 seconds of onboarding is better — the skill will pull your brand from your website and apply it across every diagram.

You:     "onboard diagram-design to https://yoursite.com"
Agent:   → fetches the homepage
         → extracts the dominant palette + font stack
         → maps detected values to semantic roles:
             paper, ink, muted, accent, link
         → shows a proposed diff
         → writes your tokens to references/style-guide.md
You:     "yes, apply it"

Every new diagram now uses your colors. Your website's paper color becomes the diagram background. Your CTA color becomes the focal accent. Your body font stack becomes the node label family.

What gets extracted

Detected from your site	Becomes
<body> 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
<h1> font family	title font
<body> font family	node-name font
<code> / <pre> font	sublabel font

Contrast checks happen automatically

Before writing tokens, the skill verifies WCAG AA contrast on ink over paper. If your site has a color that fails contrast at diagram sizes (9–12px), it proposes an adjusted value and explains why.

Every diagram template gives the inline SVG an accessible name and description: role="img", a resolving aria-labelledby, and first-child <title> / <desc> slots. IDs are prefixed per diagram and variant, so multiple SVG exports can be safely inlined on one page without duplicate accessible-name IDs. Decorative specimen icons are hidden from assistive technology instead.

Prefer to set tokens by hand? Open skills/diagram-design/references/style-guide.md and edit the table. Everything downstream reads from there — all 27 diagrams, the annotation primitive, and the gallery all inherit semantic role names (accent, not #eb6c36).

The skill won't silently ship default-skinned diagrams into a branded project. On first use in a new project, it checks if style-guide.md has been customized. If not, it pauses and asks:

"This is your first diagram in this project. The style guide is still at the default. Want to run onboarding, paste tokens manually, or proceed with default?"

See skills/diagram-design/references/onboarding.md for the full spec.

---

# From a cloned checkout, open the gallery to see all 27 diagrams
open skills/diagram-design/assets/index.html       # macOS
xdg-open skills/diagram-design/assets/index.html  # Linux

# In Claude Code, Codex, or Pi, ask:
# "Make me 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 of a bearer call with token refresh on 401."
# (branching refresh uses the ALT combined-fragment grammar in type-sequence.md;
#  see skills/diagram-design/assets/example-sequence-oauth.html — not a full authorize-code handshake)

Your agent will pick the right type, build the HTML, and save it. You can also start from a template directly:

cp skills/diagram-design/assets/template.html my-diagram.html        # minimal light
cp skills/diagram-design/assets/template-full.html my-diagram.html   # editorial with summary cards

---

Import from draw.io or Mermaid

Already have diagrams in draw.io / diagrams.net or Mermaid? Point the skill at the source and it redraws them — same content, this design system, at whatever the destination needs.

A 12-node draw.io file redrawn atbalanced detail for a blog post. The source's six pastel fills became one accent; its hand-dragged coordinates became a 4px grid.

/diagram-design:import platform.drawio
/diagram-design:import platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:import platform.drawio --detail=faithful --format=png --page=all
/diagram-design:import-mermaid README.md --diagram=all
/diagram-design:import-mermaid architecture.mmd --size=slide-16x9 --detail=simplified

Or just ask: "redraw this drawio file for my deck" , "make this Mermaid block editorial" , or "この Mermaid をスライド用にきれいにして".

Reads the common containers draw.io writes — .drawio, .drawio.xml, .drawio.png (embedded diagram), and .drawio.svg — including compressed payloads that look like base64 garbage in an editor. For Mermaid, it accepts .mmd, .mermaid, and one or more fenced mermaid blocks in Markdown. It parses text only: no rendering, JavaScript, browser, network, or followed click targets.

The point isn't conversion, it's fitting the output to where it's going. Same source file, three different diagrams:

Dial	Options	What it changes
Format	html · svg · png · html+png	The deliverable. SVG for Figma, PNG for slides, HTML for the web.
Size	doc-inline · doc-wide · slide-16x9 · slide-4x3 · social-og · social-square · print-a4-landscape · print-letter-landscape · fit	The viewBox and the type ramp — a projected slide gets 16px node names, not 12px.
Detail	faithful (≤24 nodes, zoned) · balanced (≤12) · simplified (≤7)	How much of the source survives, via a fixed degrade ladder — decorations, then duplicates, then leaf clusters, then infrastructure.
Audience	engineer · mixed · executive	The wording , not the count. Auth Service / JWT · RS256 · :8443 → Auth Service / token check → Sign-in.

Every import ends with a fidelity ledger — what got merged, collapsed, or dropped. You know the source; you'd notice anyway.

Detail: balanced · 12 source nodes → 8 drawn
Collapsed: "Token valid?" decision → edge label on Gateway → Auth
Dropped:   1 sticky note ("legacy path, to be retired") — unconnected in source
Kept in full: the request path (Web/Mobile → Gateway → Orders → Postgres)

What never carries over: source or renderer coordinates, source palette, source fonts, draw.io's diagonal connector spaghetti, or Mermaid's automatic layout. What always does: components, relationships, grouping, and direction. See references/import-drawio.md, references/import-mermaid.md, and references/output-spec.md.

---

Diagrams ship as self-contained HTML, but you can export the diagram itself for Figma, slides, or social cards. Use the slash command for your agent:

Pi:

/export-diagram path/to/diagram.html
/export-diagram path/to/diagram.html --svg-only
/export-diagram path/to/diagram.html --png-only --scale=3

Claude Code:

/diagram-design:export path/to/diagram.html
/diagram-design:export path/to/diagram.html --svg-only
/diagram-design:export path/to/diagram.html --png-only --scale=3

Or just ask in natural language:

"Export this diagram as SVG and PNG."
"Save my-diagram.html as PNG."

• SVG — extracts the <svg> node and injects Google Fonts so it renders standalone in browsers, Figma, and Illustrator.
• PNG — rasterizes the diagram via Playwright at 2× by default. One-time setup: pip install playwright && playwright install chromium.

Both formats are diagram-only — editorial cards and headers from -full variants aren't included. For a screenshot of the full editorial layout, use your browser's print-to-PDF or full-page screenshot. See skills/diagram-design/references/export.md for the full procedure.

---

Progressive disclosure. SKILL.md is a lean index — it tells the agent how to pick a type and where to look for detail. Every type lives in its own reference file, loaded only when relevant.

diagram-design/
├── commands/
│   ├── export-diagram.md            — Claude Code export command
│   ├── import-drawio.md             — Claude Code draw.io import command
│   └── import-mermaid.md            — Claude Code Mermaid import command
├── prompts/
│   ├── export-diagram.md            — Pi `/export-diagram` prompt template
│   └── import-mermaid.md            — Pi Mermaid import prompt template
├── skills/
│   └── diagram-design/
│       ├── SKILL.md                 — philosophy, selection guide, checklist
│       ├── references/              — loaded only when a type or primitive is chosen
│       │   ├── style-guide.md       — single source of truth for colors + fonts
│       │   ├── onboarding.md        — the URL-to-tokens flow
│       │   ├── import-drawio.md     — draw.io redraw procedure
│       │   ├── import-mermaid.md    — Mermaid redraw procedure
│       │   ├── output-spec.md       — format × size × detail level
│       │   ├── export.md            — SVG / PNG export + sizing
│       │   ├── 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-org-chart.md
│       │   ├── type-layers.md
│       │   ├── type-venn.md
│       │   ├── type-pyramid.md
│       │   ├── primitive-annotation.md
│       │   ├── primitive-sketchy.md
│       │   └── primitive-terminal.md
│       ├── scripts/
│       │   ├── drawio_extract.py    — draw.io → structured IR
│       │   └── mermaid_extract.py   — Mermaid → structured IR
│       └── assets/
│           ├── index.html           — live gallery, tabbed
│           ├── template*.html       — scaffolds for new diagrams
│           ├── example-<type>.html  — 3 variants × 27 types
│           ├── example-loop-terminal.html
│           ├── example-quadrant-consultant.html
│           ├── example-import-drawio.html
│           ├── example-import-mermaid.html
│           └── example-sequence-oauth*.html
├── scripts/fixtures/
│   ├── sample-flowchart.mmd
│   ├── sample-readme-with-mermaid.md
│   └── sample-adversarial.mmd
└── docs/screenshots/                — images used in this README

This keeps the agent's working context tight (only load what you need) and makes the skill easy to extend — drop a new type-<name>.md and wire it into the selection guide. The skill ships with 37 reference files covering every diagram type, primitive, and utility.

Before submitting a new example, run python3 scripts/lint-skin.py <your-new-example.html>. The repository-wide check python3 scripts/lint-skin.py --all --baseline must stay green. The linter's a11y category rejects diagram SVGs without a resolving accessible name, an empty or misplaced title/description, or unsafe bare title / desc IDs. If you touch the draw.io import path, python3 scripts/verify-drawio-import.py must also pass — it drives the real extractor against scripts/fixtures/sample-architecture.drawio in all four container formats and checks the references stay in sync. If you touch the Mermaid import path, python3 scripts/verify-mermaid-import.py must also pass — it covers all supported grammars, multi-block Markdown, adversarial labels, trust-boundary behavior, resource caps, named failures, and reference/command wiring.

All pull requests and pushes are automatically validated via GitHub Actions CI (.github/workflows/ci.yml).

At startup, the agent sees only the skill name and description. When a request matches, it loads SKILL.md; type references are pulled in only when relevant. This keeps the skill fast even with 37 reference files.

You ask for…	Agent loads
"Make me a flowchart"	SKILL.md + references/type-flowchart.md
"Build an architecture diagram"	SKILL.md + references/type-architecture.md
"Onboard this skill to my site"	SKILL.md + references/onboarding.md + references/style-guide.md
"Add an editorial callout to this diagram"	SKILL.md + references/primitive-annotation.md
"Give me a hand-drawn version"	SKILL.md + references/primitive-sketchy.md
"Give me a terminal / CLI-window version"	SKILL.md + references/primitive-terminal.md
"Redraw this .drawio file for my deck"	SKILL.md + references/import-drawio.md + references/output-spec.md + the chosen type's reference
"Redraw this Mermaid block for my deck"	SKILL.md + references/import-mermaid.md + references/output-spec.md + the chosen type's reference
Routine diagram-making (any of the 27 diagrams)	Only SKILL.md + that one type's reference

No matter how many types exist, the agent only reads the one you need. Add a new type tomorrow and nothing else changes.

---

The design system (in one paragraph)

One accent color, 1–2 focal elements per diagram. Three font families: Instrument Serif (title + italic callouts), Geist sans (node names), Geist Mono (technical sublabels). 1px hairline borders, no shadows, max border-radius 10px. Every coord, width, and gap divisible by 4 — non-negotiable, it's what keeps the diagrams from feeling AI-generated. Mono is for technical content (ports, URLs, field types), not a blanket "dev" aesthetic. Coral-tinted focal nodes draw the eye to the 1–2 things that matter. Full spec in SKILL.md.

---

• Annotation callout — italic Instrument Serif + dashed Bézier leader, for editorial asides that sit in the margins. See skills/diagram-design/references/primitive-annotation.md.
• Sketchy filter — SVG turbulence + displacement map for a hand-drawn variant. Good for essays, not for technical docs. See skills/diagram-design/references/primitive-sketchy.md.
• Icon set — 55 monochrome IT/cloud icons (laptop, phone, user, server, database, Docker, Kubernetes, AWS, Azure, GitHub, Postgres…) for richer architecture and sequence diagrams. Stroked icons from Tabler Icons (MIT); brand silhouettes from Simple Icons (CC0). Each icon uses currentColor so it inherits the editorial skin or your onboarded brand. See skills/diagram-design/references/primitive-icons.md; browse the gallery. Regenerate with python scripts/build-icons.py.

---

When not to use this skill

• Quick unicode diagrams for tweets or terminal output → wiretext-style skill.
• Lists of anything → a table or bullets.
• Before/after comparisons → a table.
• One-shape "diagrams" — a single box with a label → just write the sentence.

Before drawing, ask: would a reader learn more from this than from a well-written paragraph? If no, don't draw.

---

Made by Cathryn Lavery — founder of BestSelf.co. I write about AI, entrepreneurship, and designing nice-looking things at littlemight.com — blog + newsletter.

If this is useful, star the repo and come say hi on X.