38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML + SVG. No shadows. No Mermaid slop.

This repository is empty

Auto Translate

Diagram Design

设计师不会反感的编辑级图表。

2.0 新增 — Loop：带有共享内存枢纽的飞轮。虚线表示回写。

2.3 新增：语义化系统模式与可选的无障碍动效，静态输出仍为默认。

2.5.10 新增：十种布局语法 — Sankey 图、鱼骨图、Wardley 地图、看板、用户旅程、部署图、依赖图、UML 类图、故事地图和数据库架构。

39 种编辑级图表类型，适用于 Claude Code、Codex、Factory Droid、Pi 以及兼容 Agent Skills 的宿主。自包含 HTML + SVG。无阴影。没有 Mermaid 式粗糙。语义模式将行为与布局分开描述，因此队列、策略追踪或信任边界可以复用最接近的现有类型，而无需增加类型数量。静态 HTML 仍是默认输出；可选动效可用于顺序说明。该技能还可按所选的格式、尺寸和细节级别，重绘来自 draw.io、Mermaid 或 Excalidraw 的源图。

无需 Figma。无需千篇一律的圆角框。无需花半小时挑颜色。

我为什么要做它

我在 littlemight.com 写作（副业运营 BestSelf.co）。每次我需要一张图——架构草图、流程图，或一个突出最关键事项的分层金字塔——我让 Claude 生成，得到的却总是通用的圆角框，和网站其他部分格格不入。要么和 Figma 搏斗半小时，要么干脆放弃这张图。

于是我给它做了一个 Claude Code 技能。39 种视觉类型，编辑级质量，通过读取你的网站，在 60 秒内匹配你的品牌。

最高质量的调整往往是删减。 每个节点都有它的位置。强调色只留给读者应首先看到的 1–2 个元素。目标密度：4/10。

它能生成什么

全部 39 种可视化类型均以三种静态变体提供：极简浅色、极简深色和完整编辑版。可直接在浏览器中打开其中任意一种。没有构建步骤、JavaScript 或外部图片依赖。

架构 _{组件 + 连接}	IT 现状 _{遗留全景 + 现代化}	流程图 _决策逻辑
时序 _{随时间变化的消息}	状态机 _{状态 + 转换}	ER / 数据模型 _{实体 + 字段}
时间线 _{轴上的事件}	泳道 _{跨职能流程}	四象限 _双轴定位
雷达 / 蛛网 _多轴比较	循环 / 飞轮 _{强化循环 + 共享中心}	嵌套 _{按包含关系表示层级}
树 _{父节点 → 子节点}	组织架构图 _{归属 + 汇报路径}	层栈 _堆叠抽象
维恩 _集合重叠	金字塔 / 漏斗 _{排序层级或流失}	条形图 _类别比较
矩形树图 _{按面积表示整体与部分}	折线图 _{随时间变化趋势}	甘特 _{时间线上的任务 + 阶段}
散点图 _{分布 + 相关性}	高层级 _{集群上的端到端堆栈}	流程 _{多角色顺序工作流}
Medallion _{多层数据存储}	数据流 _{面向角色的管道步骤}	DP 集成 _{来源 → 核心 → 消费者}
DP 安全矩阵 _{按角色的访问权限}	桑基 _{分流与合并的数量}	鱼骨 _{分组原因 → 单一结果}
Wardley 地图 _{价值链 × 演化}	看板 _{按状态划分的进行中工作}	用户旅程 _{阶段、动作 + 情绪}
部署 _{区域、主机 + 制品}	依赖图 _{扇入、层级 + 环}	UML 类 _{类、操作 + 类型化关系}
故事图 _{主干 × 发布切片}	数据库模式 _{物理表 + 列级外键}	极坐标图 _{圆周量级 · 线性半径}
瀑布 _{累计总额 + 正负桥接}

v2.5.10 版本新增了上述最后十种类型。可在 30 变体对照表中比较它们的浅色、深色和完整编辑版变体。

浏览在线图库： cathrynlavery.github.io/diagram-design — 或在本地打开 skills/diagram-design/assets/index.html，通过浅色 / 深色 / 完整编辑版标签页浏览全部 39 个图表。

安装

Claude Code:

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

只需启用一次更新：运行 /plugin，打开 Marketplaces，选择 diagram-design，然后选择 Enable auto-update。Claude Code 默认会禁用第三方市场的自动更新；开启该开关后，它会在启动后的后台刷新市场以及已安装的插件。如果系统提示运行 /reload-plugins，请按提示执行；或等待下次会话自动加载更新。

Codex:

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

Codex 会在启动时刷新已配置的 Git 插件市场。如需立即拉取，请运行 codex plugin marketplace upgrade diagram-design 并开启一个新会话。

GitHub Copilot:

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

Copilot 会从现有仓库市场安装共享的 Diagram Design 技能，以及其 doctor、export、import 和 profile 功能。使用 copilot skill list 确认技能可被发现（交互式会话中也可使用 /skills），然后用自然语言请求生成一个图表。如需拉取已合并的更新，请运行 copilot plugin marketplace update diagram-design，随后运行 copilot plugin update diagram-design@diagram-design。

Factory Droid:

droid plugin marketplace add https://github.com/cathrynlavery/diagram-design
droid plugin install diagram-design@diagram-design --scope user

Droid 会按 Git 提交，而不是按清单中的显示版本来跟踪 Git 插件。若要获取已合并的更新，请执行 droid plugin marketplace update diagram-design，然后执行 droid plugin update diagram-design@diagram-design --scope user，并开启新会话。

Claude Cowork（组织市场）： 组织级 GitHub 市场目前要求仓库为私有或内部仓库，因此请先将此公共仓库镜像到由你的组织拥有的仓库。在 组织设置 → 插件 中，选择 添加插件 → GitHub，连接该镜像，并从市场菜单中启用 自动同步。当包含插件版本提升的拉取请求合并到镜像的默认分支时，自动同步会运行；直接推送不会触发 webhook。从由此生成的组织市场中安装 Diagram Design。

Pi：

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

在已打开的 Pi 会话中运行 /reload。Pi 会为匹配的图表请求提供该技能；要显式调用它，请使用 /skill:diagram-design。Pi 还会加载 /export-diagram、/import-mermaid、/import-excalidraw、/profile 和 /doctor 提示模板。未固定版本的 Git 安装是有意为之：Pi 没有自动刷新包的功能，因此请运行 pi update --extensions 以拉取已合并的更新。

Kiro： 请从仓库子目录 URL 导入 Agent Skill：

https://github.com/cathrynlavery/diagram-design/tree/main/skills/diagram-design

Kiro 会将导入的技能复制到工作区的 .kiro/skills/，或复制到全局的 ~/.kiro/skills/；如需获取更新，请重新导入该 URL。声明了资源的自定义智能体应包含 skill://diagram-design/**/SKILL.md。

OpenCode： 将 skills/diagram-design/ 复制或软链接到项目内的 .opencode/skills/diagram-design，或全局的 ~/.config/opencode/skills/diagram-design。OpenCode 没有 Diagram Design 市场包；复制安装的版本只会在你用较新检出的目录替换原目录时更新。

一次性迁移： 已有的独立 npx skills add 副本不会自动开始跟随 Codex 市场的更新。请移除该独立副本，然后使用上方的 Codex 市场命令。同样，请卸载个人的 Cowork 副本，并重新从组织的市场安装 Diagram Design。此后，市场版本的更新会通过各客户端的原生更新路径生效。

可编辑安装

托管安装虽然方便，但你对 references/style-guide.md 的修改可能会被包更新覆盖。保存在 ~/.diagram-design/profiles/ 中的配置文件在更新后仍会保留，带有 .diagram-design 标记的项目不受影响。如果你打算直接自定义工作样式指南，请克隆仓库并安装本地路径：

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

# Other Agent Skills hosts: create only the roots you use
mkdir -p ~/.agents/skills ~/.cursor/skills ~/.cline/skills ~/.kiro/skills ~/.config/opencode/skills ~/.copilot/skills
ln -s ~/code/diagram-design/skills/diagram-design ~/.agents/skills/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.cursor/skills/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.cline/skills/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.kiro/skills/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.config/opencode/skills/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.copilot/skills/diagram-design

共享技能位于 skills/diagram-design/。Pi 会通过仓库标准的 skills/ 包目录发现它；Claude Code、GitHub Copilot、Codex、Factory Droid 以及其他兼容 Agent Skills 的工具都会使用同一套文件。

入门 — 让它呈现你的品牌

核心目标：交付具备编辑级质感的图表，采用你的品牌配色与字体，而不是通用模板。

开箱即用状态下，图表会以干净的 喷黑 + 原子橙 配色呈现（白烟纸底色、喷黑墨色、原子橙强调色、蓝石板弱化色、银色极细线）。直接截图也足够好看。但花 60 秒完成入门体验更佳——该技能会从你的网站提取品牌信息，并应用到每一张图表中。

流程

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"

现在，每张新图表都会使用你的配色。你网站的纸色会成为图表背景。你的 CTA 颜色会成为焦点强调色。你的正文字体栈会成为节点标签字体族。

品牌匹配还会生成一份保真回执：包含采样 URL、精确的颜色角色、字体族与字重、字体源 URL，以及任何回退方案。公开网站的字体会被直接使用，并在渲染后校验，而不是被悄悄替换为通用系统字体。

会提取哪些内容

从你的站点检测到	生成
`<body>` 背景	`paper` token
主要文本颜色	`ink` token
次要 / 说明文本	`muted` token
卡片或容器	`paper-2` token
最常用的品牌色（CTA、链接、标题）	`accent` token
`<h1>` 字体族	`title` 字体
`<body>` 字体族	`node-name` 字体
`<code>` / `<pre>` 字体	`sublabel` 字体

对比度检查自动执行

在写入 token 之前，该技能会校验 ink 在 paper 上的 WCAG AA 对比度。如果你的站点中有某个颜色在图表尺寸（9–12px）下未通过对比度，它会建议一个调整后的值，并说明原因。

默认无障碍

每个图表模板都会为内联 SVG 提供可访问名称和描述：role="img"、可解析的 aria-labelledby，以及作为首个子元素的 <title> / <desc> 槽位。ID 会按图表和变体添加前缀，因此多个 SVG 导出可以安全地内联到同一页面上，且不会出现重复的可访问名称 ID。装饰性示例图标则会从辅助技术中隐藏。

手动覆盖

更希望手动设置 token？打开 skills/diagram-design/references/style-guide.md，编辑表格。下游所有内容都会从这里读取——全部 39 个图表、注释基元和图库，都会继承语义角色名（使用 accent，而不是 #eb6c36）。

首次运行检查

该技能不会悄悄把默认样式的图表带入品牌项目。在新项目中首次使用时，它会检查 style-guide.md 是否已自定义。如果没有，它会暂停并询问：

"这是你在这个项目中的第一张图表。样式指南仍处于默认状态。要运行引导、手动粘贴 token，还是按默认继续？"

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

处理多个客户

品牌只需接入一次，将结果保存为命名配置，然后在每个客户项目中添加一个包含 profile: <slug> 的 .diagram-design 标记。带标记的项目会直接读取 ~/.diagram-design/profiles/<slug>.md，这样并行工作区可以使用不同品牌，而不会覆盖共享安装的 style-guide.md。

配置库在 Claude Code、Codex、Factory Droid 和 Pi 之间共享。在 Claude Code 中使用 /diagram-design:profile，在 Factory Droid 或 Pi 中使用 /profile，或直接在任意宿主环境中以自然语言提出请求。有关存储、标记与恢复约定，请参阅 profiles.md。

快速上手

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

# In Claude Code, Codex, Factory Droid, 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)

可编辑安装、首个图形、品牌设置、导入、导出、校验、Windows 联接以及可复用提示词的操作指南位于 docs/cookbook.md。

你的智能体会选择合适的类型，生成 HTML，并保存。你也可以直接从模板开始：

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
cp skills/diagram-design/assets/template-motion.html my-diagram.html # optional accessible motion

语义模式与可选动效

当行为重要时，该 skill 会先选择语义模式，再选择视觉类型。九种路由模式覆盖扇入队列与瓶颈、重复阶段槽位、非结构化输入转换、成对策略追踪、安全的既定路径、治理目录、补偿性安全层、可追溯块分解和生命周期阶段图。每个模式都在 semantic-patterns.md 中定义其触发条件、原语、预算、反模式、静态回退方案及最接近的视觉类型。

动效是可选的，也不会新增视觉类型。animation.md 定义了 none、reveal、step 和 loop 模式，并具备完整的静态首帧、确定性时序，以及交互可用时的控件。减少动态效果的输出会显示完整静态帧，并隐藏/禁用播放控件。动效 HTML 使用 template-motion.html 中经过审核的、完全一致的控制器；任意或经修改的内联脚本、远程资源、CSS 导入以及可执行的 HTML 属性均会被拒绝。默认值为 none：普通输出保持静态且无脚本。example-policy-trace-animated.html 是自包含的交互示例。

从 draw.io、Mermaid 或 Excalidraw 导入

已有 draw.io / diagrams.net、Mermaid 或 Excalidraw 中的图表？将该 skill 指向源文件，它便会重新绘制它们——内容保持不变，采用本设计系统，并按目标所需调整。

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

/diagram-design:import-drawio platform.drawio
/diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:import-drawio 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
/diagram-design:import-excalidraw whiteboard.excalidraw --size=slide-16x9 --detail=simplified

或直接这样问："把这份 drawio 文件重画成适合我的演示文稿"、"把这个 Mermaid 块改成编辑级风格"、"让这张白板草图适合展示"，或 "把这个 Mermaid 整理成适合幻灯片的样子"。

可读取 draw.io 生成的常见容器——.drawio、.drawio.xml、.drawio.png（内嵌图形）和 .drawio.svg——包括在编辑器中看似 base64 乱码的压缩载荷。对于 Mermaid，可接受 .mmd、.mermaid，以及 Markdown 中一个或多个围栏 mermaid 代码块。对于 Excalidraw，可接受 .excalidraw 和 .excalidraw.json 场景文件（不接受 .excalidraw.png/.excalidraw.svg 导出）。它仅解析文本：不渲染、不执行 JavaScript、不使用浏览器或网络，也不跟随点击目标。

四个调节项

重点不在于转换，而在于让输出适配使用场景。同一份源文件，可呈现为三种不同的图：

调节项	选项	改变什么
格式	`html` · `svg` · `png` · `html+png`	交付物。SVG 用于 Figma，PNG 用于幻灯片，HTML 用于网页。
尺寸	`doc-inline` · `doc-wide` · `slide-16x9` · `slide-4x3` · `social-og` · `social-square` · `print-a4-landscape` · `print-letter-landscape` · `fit`	`viewBox` 以及字号阶梯——投影幻灯片会得到 16px 的节点名称，而不是 12px。
细节	`faithful`（≤24 个节点，分区） · `balanced`（≤12） · `simplified`（≤7）	源内容能保留多少，取决于固定的降级阶梯——先装饰，再重复项，再叶节点簇，最后基础设施。
受众	`engineer` · `mixed` · `executive`	改变的是措辞，而不是数量。`Auth Service / JWT · RS256 · :8443` → `Auth Service / token check` → `Sign-in`。

每次导入都会以一份保真清单收尾——哪些被合并、折叠或丢弃。你了解源内容；反正你也会注意到。

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)

以下内容永远不会被保留：源坐标或渲染器坐标、源调色板、源字体，draw.io 的斜向连线乱麻，Mermaid 的自动布局，以及 Excalidraw 的手绘几何。以下内容始终会保留：组件、关系、分组和方向。参见 references/import-drawio.md、references/import-mermaid.md、references/import-excalidraw.md 以及 references/output-spec.md。

导出为 PNG / SVG

图表以自包含 HTML 形式交付，但你可以将图表本身导出到 Figma、幻灯片或社交卡片中。请使用你当前 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
/export-diagram path/to/diagram.html --registry

Claude Code:

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

或者直接用自然语言提问：

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

SVG — 提取 <svg> 节点并注入 Google Fonts，使其可在浏览器、Figma 和 Illustrator 中独立渲染。
PNG — 默认通过 Playwright 以 2× 比例将图表光栅化。一次性设置：pip install playwright && playwright install chromium。

两种格式均仅导出图表本体——-full 变体中的编辑卡片和页眉不包含在内。如需截取完整的编辑式版面，请使用浏览器的“打印为 PDF”或整页截图功能。完整流程见 skills/diagram-design/references/export.md。

--registry — 针对采用 traceable block decomposition 模式的图表，还会输出 <basename>.registry.json，其中包含每个块 data-block-* 元数据的结构化投影。可与任一位图格式组合使用，也可单独运行。详细说明见 skills/diagram-design/references/export-registry.md。

对于启用动效的 HTML，请导出显式最终状态：打开 ?motion=static，等待 document.fonts.ready，并在捕获前确认动效根节点具有 data-frame="static"。仅当请求了指定中间帧时，才使用 ?motion=step&step=N。

架构

渐进式披露。SKILL.md 会在需要时先路由行为，再路由布局。语义、字体与动画参考仅在相关时加载。

diagram-design/
├── .agents/plugins/marketplace.json — Codex marketplace catalog
├── .claude-plugin/                  — Claude marketplace + plugin manifest
├── .codex-plugin/                   — Codex plugin manifest
├── .factory-plugin/                 — Factory Droid marketplace + plugin manifest
├── commands/
│   ├── export-diagram.md            — plugin export command
│   ├── import-drawio.md             — plugin draw.io import command
│   ├── import-mermaid.md            — plugin Mermaid import command
│   ├── import-excalidraw.md         — plugin Excalidraw import command
│   ├── profile.md                   — plugin client-profile command
│   └── doctor.md                    — plugin environment diagnostics command
├── prompts/
│   ├── export-diagram.md            — Pi `/export-diagram` prompt template
│   ├── import-mermaid.md            — Pi Mermaid import prompt template
│   ├── import-excalidraw.md         — Pi Excalidraw import prompt template
│   ├── profile.md                   — Pi `/profile` prompt template
│   └── doctor.md                    — Pi `/doctor` diagnostics 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
│       │   ├── semantic-patterns.md — behavior patterns independent of layout
│       │   ├── animation.md         — optional motion + accessibility contract
│       │   ├── onboarding.md        — the URL-to-tokens flow
│       │   ├── profiles.md          — named client profiles + project markers
│       │   ├── import-drawio.md     — draw.io redraw procedure
│       │   ├── import-mermaid.md    — Mermaid redraw procedure
│       │   ├── import-excalidraw.md — Excalidraw redraw procedure
│       │   ├── output-spec.md       — format × size × detail level
│       │   ├── export.md            — SVG / PNG export + sizing
│       │   ├── export-registry.md   — block-metadata JSON sidecar export
│       │   ├── 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
│       │   ├── type-sankey.md
│       │   ├── type-fishbone.md
│       │   ├── type-wardley.md
│       │   ├── type-kanban.md
│       │   ├── type-journey.md
│       │   ├── type-deployment.md
│       │   ├── type-dependency.md
│       │   ├── type-uml-class.md
│       │   ├── type-story-map.md
│       │   ├── type-db-schema.md
│       │   ├── primitive-annotation.md
│       │   ├── primitive-sketchy.md
│       │   └── primitive-terminal.md
│       ├── scripts/
│       │   ├── drawio_extract.py    — draw.io → structured IR
│       │   ├── mermaid_extract.py   — Mermaid → structured IR
│       │   ├── excalidraw_extract.py — Excalidraw → structured IR
│       │   └── self_check.py        — packaged output self-check (runs installed)
│       └── assets/
│           ├── index.html           — live gallery, tabbed
│           ├── template*.html       — scaffolds for new diagrams
│           ├── example-<type>.html  — 3 variants × 39 types
│           ├── example-loop-terminal.html
│           ├── example-quadrant-consultant.html
│           ├── example-import-drawio.html
│           ├── example-import-mermaid.html
│           ├── example-import-excalidraw.html
│           ├── example-policy-trace-animated.html
│           └── example-sequence-oauth*.html
├── scripts/
│   ├── build-readme-thumbs.py       — regenerates docs/screenshots/thumbs/
│   ├── bump-plugin-version.py       — synchronized Claude/Codex/Factory version bump
│   ├── render-canonical-screenshots.py — deterministic 39-type PNG catalog renderer
│   ├── verify-screenshot-freshness.py — source + screenshot digest gate
│   ├── verify-plugin-package.py     — version + marketplace package gate
│   ├── test-plugin-package.py       — adversarial package-gate tests
│   ├── lint-render.py               — Chromium rendered-layout checker
│   ├── verify-doctor.py             — doctor diagnostics contract gate
│   ├── test-verify-doctor.py        — doctor diagnostics adversarial tests
│   ├── verify-polar.py              — quantitative polar encoding gate
│   ├── test-verify-polar.py         — polar gate adversarial tests
│   ├── verify-sankey.py             — Sankey conservation + geometry gate
│   ├── test-verify-sankey.py        — Sankey gate adversarial tests
│   ├── verify-waterfall.py          — waterfall running-total + bridge gate
│   ├── test-verify-waterfall.py     — waterfall gate adversarial tests
│   ├── test-verify-docs-sync.py     — docs/routing-surface gate tests
│   └── fixtures/
│       ├── sample-flowchart.mmd
│       ├── sample-readme-with-mermaid.md
│       ├── sample-adversarial.mmd
│       ├── sample-whiteboard.excalidraw
│       └── sample-adversarial.excalidraw
├── docs/cookbook.md                 — operator recipes for editable installs and common tasks
├── docs/adr/                        — short records of settled design decisions
├── docs/screenshots/                — full-resolution images + source-digest manifest.json
└── docs/screenshots/thumbs/         — generated WebP previews the README renders

这让智能体的工作上下文保持精简：常规图表只加载一个类型参考；行为复杂的图表会补充路由的语义参考；动画只有在被选中时才会引入其契约。

贡献 / skin lint

提交新示例前，请运行 python3 scripts/lint-skin.py <your-new-example.html>。仓库级检查 python3 scripts/lint-skin.py --all --baseline 覆盖示例和模板，并且必须保持绿色。 CI 会分别验证语义路由、动效示例结构、动效皮肤、每个已发布的动效资产，以及控制器契约的对抗性变更；即使前面的门禁失败，也会报告后续门禁的结果。语义路由必须通过 python3 scripts/verify-semantic-motion.py --markdown-only；动效示例有独立的 --example-only 门禁。每个已发布的动效模板/示例也必须通过 python3 scripts/verify-motion.py --shipped。检查器的 a11y 类别会拒绝没有可解析无障碍名称的图表 SVG、空或位置不当的 title/description，以及不安全的裸 title / desc ID。它还会锁定经过审查的精确动效控制器，并拒绝远程资源、CSS @import、非片段 CSS url()，以及可执行属性，例如 onclick 或 srcdoc。如果你修改 draw.io 导入路径，python3 scripts/verify-drawio-import.py 也必须通过——它会在全部四种容器格式下驱动真实提取器处理 scripts/fixtures/sample-architecture.drawio，并检查引用保持同步。如果你修改 Mermaid 导入路径，python3 scripts/verify-mermaid-import.py 也必须通过——它覆盖所有受支持语法、多块 Markdown、对抗性标签、信任边界行为、资源上限、命名失败，以及引用/命令接线。如果你修改 Excalidraw 导入路径，python3 scripts/verify-excalidraw-import.py 也必须通过——它覆盖场景解析、绑定标签、分组和画框、对抗性标签、信任边界行为、资源上限、命名失败，以及引用/命令接线。

标签位置会以几何方式设置门禁：python3 scripts/verify-geometry.py --all 会在标签遮罩与文档中更晚声明的节点重叠时让 CI 失败，因为节点填充会在渲染时裁切文本。python3 scripts/test-verify-geometry.py 确保该检查器在两个方向上都可靠。使用可追溯块分解模式的图表，在这之外还会增加一道结构门禁：python3 scripts/verify-block-registry.py --all 会在出现重复 data-block-id、无法解析到同一文件中另一个块的 data-block-parent、父级链中的环、空 data-block-id，或缺失或空的 data-block-name 时让 CI 失败——正是这些缺陷会使 --registry 导出的 JSON（见 export-registry.md）歪曲它所声称描述的树。python3 scripts/test-verify-block-registry.py 确保该检查器在两个方向上都可靠。树状图还有第二道几何门禁，因为它们的核心主张是面积就是编码：python3 scripts/verify-treemap.py --all 会在某个单元在绘制面积中的占比与其内部标注的数值不一致，或标签越出它所标识的单元时让 CI 失败。它以相对数值衡量面积误差——如果使用绝对数值，恰好最可能出错的极小单元会通过。python3 scripts/test-verify-treemap.py 确保它在两个方向上都可靠。瀑布图也会接受同样处理，因为它们的核心主张是累计总额守恒：python3 scripts/verify-waterfall.py --all 会在声明的起始值、增量和终值无法对账、桥梁柱没有绘制在共享标尺上对应的两个累计水平上、结转连接线缺失或位于错误水平、增量未显示明确正负号，或两个方向被合并为一种填充时让 CI 失败。python3 scripts/test-verify-waterfall.py 确保它在两个方向上都可靠。文档与路由界面本身也受门禁约束：python3 scripts/verify-docs-sync.py 会在以下情况让 CI 失败：SKILL.md 的描述丢失了某个类型的词法钩子，示例画廊无法访问已发布的示例，README 树中列出了不存在的文件，相对引用链接失效，扫描器可见的支持路径未随 skill 包发布，或任何命令/提示界面与其路由参考产生偏差。python3 scripts/test-verify-docs-sync.py 会以对抗方式验证这些较新的检查项，包括 Hermes Agent 使用的严格打包器行为。该 skill 还附带 skills/diagram-design/scripts/self_check.py——一个精简的输出检查器，已安装的智能体可以用它检查自身生成的图表；python3 scripts/test-self-check.py 确保它可靠。已确定的设计决策（为什么固定一个控制器、为什么模式从不新增类型、自动播放策略、SKILL.md 字节上限、为什么以几何方式验证标签位置，以及为什么客户端配置采用 marker 优先解析）以简短 ADR 形式存放在 docs/adr/ 中——重新讨论某一条之前，请先阅读它们；确定新政策时，请新增一条。

所有 pull request 和 push 都会在 Linux、Windows 和 macOS runners 上通过 GitHub Actions CI（.github/workflows/ci.yml）自动验证。

lint-skin.py 读取源码。lint-render.py 会渲染它——无头 Chromium 会报告实际被绘制的内容，从而捕获被 SVG 视口裁切的内容、塌缩的 SVG、水平页面溢出、缺失的本地资源以及 JS 错误。两者都会在每次 pull request 的 CI 中运行。

pip install playwright && playwright install chromium   # same dep as PNG export
python3 scripts/lint-render.py --self-test              # checks the checks
python3 scripts/lint-render.py --all                   # examples and templates
python3 scripts/lint-render.py <your-new-example.html>
python3 scripts/lint-render.py --fonts --all           # measure with the real webfonts

裁剪以实际绘制（paint）为准，而不是几何形状：对 SVG 子元素调用 getBoundingClientRect() 会忽略线宽、标记和滤镜溢出，也完全不考虑 clip-path 或 overflow: visible，因此它既可能漏掉真实裁剪，也可能凭空判定出不存在的裁剪。相反，每个 SVG 都会先按原样截图，再解除其 overflow 后重新截图，然后对两张图做差异比较——出现在外部的墨迹，就是之前被裁掉的内容。解除操作是分阶段进行的——先只针对 SVG 本身，再逐一处理每个裁剪祖先元素——这样外层包裹器的解除就不会掩盖 SVG 自身边缘处的溢出，并且如果 SVG 本身声明了 overflow: visible 但位于裁剪包裹器内，也仍会被检查。 --self-test 会在 23 个用例中验证以上所有行为，其中超过一半是不应被标记的用例，同时还会断言测量后 DOM 逐字节相同。

不使用黄金图像，因此无需重新录制，仓库里也不会有 PNG。网络会在浏览器解析器处被切断，覆盖 WebSockets 及其他绕过请求路由的场景，请求路由则作为第二层防护； --fonts 会精确排除两个 Google Fonts 主机名，并且只允许通过 HTTPS 访问它们。既然判定基准是像素，CI 会固定 Playwright 及其 Chromium 构建版本，而不是安装最新版本。

默认运行与 --fonts 之间的字体度量不同。 在网络被阻断的情况下—— 这也是默认配置，并且是 CI 的运行方式——文本会使用回退字体排版，而不是 Instrument Serif 和 Geist。这是确定性的，并且不依赖机器，正是 linter 所需要的，但它并不是读者实际看到的内容。当你关心真实文本是否能放进其框内时，请在本地运行 --fonts --all。

何时加载哪些内容

启动时，Agent 只能看到 Skill 的名称和描述。当请求匹配时，它会加载 SKILL.md；语义、类型和动画参考资料只在相关时才会引入。

你请求…	Agent 加载
"帮我做一个流程图"	`SKILL.md` + `references/type-flowchart.md`
"构建一个架构图"	`SKILL.md` + `references/type-architecture.md`
"比较为什么这两个策略请求不同"	`SKILL.md` + `references/semantic-patterns.md` + `references/type-flowchart.md`
"为那个策略跟踪添加动画"	先前选择 + `references/animation.md`
"将这个 Skill 接入我的网站"	`SKILL.md` + `references/onboarding.md` + `references/style-guide.md`
"使用我保存的 Acme 客户档案"	`SKILL.md` + `references/profiles.md` + `~/.diagram-design/profiles/acme.md`
"为这张图添加一个编辑风格标注"	`SKILL.md` + `references/primitive-annotation.md`
"给我一个手绘版本"	`SKILL.md` + `references/primitive-sketchy.md`
"给我一个终端 / CLI 窗口版本"	`SKILL.md` + `references/primitive-terminal.md`
"为我的演示稿重绘这个 .drawio 文件"	`SKILL.md` + `references/import-drawio.md` + `references/output-spec.md` + 所选类型的参考资料
"为我的演示稿重绘这个 Mermaid 代码块"	`SKILL.md` + `references/import-mermaid.md` + `references/output-spec.md` + 所选类型的参考资料
"为我的演示稿重绘这个 Excalidraw 草图"	`SKILL.md` + `references/import-excalidraw.md` + `references/output-spec.md` + 所选类型的参考资料
"常规静态图表制作（39 种视觉类型中的任意一种）"	仅 `SKILL.md` + 该类型对应的参考资料

无论存在多少类型，Agent 都只读取你需要的那一个。明天新增一种类型，其他任何东西都不用改变。

如果它能做到这些，就说明它正常工作……

一个常规请求（“帮我画一张流程图”）只会加载 SKILL.md，外加恰好一份类型参考——不会加载其他任何内容。
绘制前，智能体会先说明所选类型、模式、尺寸以及计划中的取舍，然后进行渲染。
输出是一个 .html 文件，双击即可离线打开，除 Google Fonts 外不会发起任何网络请求。
屏幕阅读器会播报图表的标题和描述；prefers-reduced-motion 会显示完整的静态画面。
python3 skills/diagram-design/scripts/self_check.py <file> 对生成的文件打印 OK。
完成品牌接入后，新图表会使用你站点的纸色、墨色、强调色和字体——并附有一份保真回执，逐项列明每项内容。

如果其中任何一条不满足，那就是一个值得提交的 bug。

设计系统（一段话说明）

仅用一个强调色，每张图表 1–2 个焦点元素。三种字体：Instrument Serif（标题与斜体批注）、Geist sans（节点名称）、Geist Mono（技术性子标签）。1px 发丝边框，无阴影，最大圆角 10px。每个坐标、宽度和间距都能被 4 整除——不可妥协，正是这一点让图表不会显得像 AI 生成的。等宽字体用于技术内容（端口、URL、字段类型），而不是一刀切的“开发者”美学。带珊瑚色调的焦点节点会把视线引向真正重要的 1–2 件事。完整规范见 SKILL.md。

基础元素

注释标注 — 斜体 Instrument Serif + 虚线 Bézier 引导线，用于页边呈现的编辑式旁注。参见 skills/diagram-design/references/primitive-annotation.md。
手绘滤镜 — 使用 SVG 湍流 + 置换映射生成手绘感变体。适合文章，不适合技术文档。参见 skills/diagram-design/references/primitive-sketchy.md。
图标集 — 87 个单色 IT/云图标（笔记本电脑、手机、用户、服务器、数据库、Docker、Kubernetes、AWS、Azure、GitHub、Postgres…），用于让架构图和时序图更丰富。线性图标来自 Tabler Icons（MIT）；品牌剪影来自 Simple Icons（CC0）。每个图标都使用 currentColor，从而继承编辑风格的视觉皮肤或你已接入的品牌。参见 skills/diagram-design/references/primitive-icons.md；浏览图库。使用 python scripts/build-icons.py 重新生成。

何时不要使用此 skill

快速 Unicode 图示，用于推文或终端输出 → wiretext 风格的 skill。
任何清单 → 表格或项目符号列表。
前后对比 → 表格。
单图形“图示” — 一个带标签的方框 → 直接写成句子。

画图之前，先问自己：读者从中能比从一段写得好的段落里学到更多吗？ 如果不能，就别画。

贡献

欢迎贡献——新的图示类型、导入语法支持、示例、文档和工具。请查阅 CONTRIBUTING.md 了解校验关卡和工作流，并查阅 CODE_OF_CONDUCT.md 了解社区准则。

关于

由 Cathryn Lavery 制作——BestSelf.co 创始人。我在 littlemight.com 撰写关于 AI、创业以及设计美观事物的内容——博客 + 通讯。

如果对你有帮助，请给仓库加星，并来 X 上打个招呼。

Introduction

Claude Code 的十三种编辑图表类型。独立的 HTML + SVG。无阴影，无 Mermaid 杂乱元素。【此简介由AI生成】

MIT HTML 169Commitsagent-skills claude-code codex data-visualization diagrams drawio mermaid svg

Customize your domain

README

Code of conduct

12140.48 K2.58 KVisit GitHub

diagram-design:基于 Claude Code 的编辑级图表生成工具项目