38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML + SVG. No shadows. No Mermaid slop.
Diagram Design
设计师不会讨厌的编辑式图表。
2.0 新增 — Loop：带有共享记忆中枢的飞轮。虚线表示回写。
2.3 新增：语义系统模式和可选的无障碍动效，静态输出仍为默认。
2.5.10 新增：十种布局语法 — Sankey 图、鱼骨图、Wardley 地图、看板、用户旅程、部署图、依赖图、UML 类图、故事地图和数据库模式。
39 种编辑式图表类型，适用于 Claude Code、Codex、Factory Droid 和 Pi。自包含的 HTML + SVG。没有阴影。没有 Mermaid 式的粗糙产物。语义模式将行为与布局分开描述，因此队列、策略追踪或信任边界都可以使用最接近的现有类型，而无需增加类型数量。静态 HTML 保持为默认输出；如需顺序讲解，可选用动效。该技能还可按指定的格式、尺寸和细节级别，重绘 draw.io 或 Mermaid 源文件。
没有 Figma。没有千篇一律的圆角矩形。没有 30 分钟的选色环节。
我为什么构建它
我在 littlemight.com 写作（同时运营 BestSelf.co）。每次我需要一张图——架构草图、流程图，或是“什么最重要”的金字塔——我都会问 Claude，结果得到的是一堆通用圆角框，和网站其余部分格格不入。要么花 30 分钟和 Figma 较劲，要么干脆不画。
所以我为它做了一个 Claude Code 技能。39 种视觉类型，编辑级品质，通过读取你的网站，在 60 秒内匹配你的品牌。
最高质量的动作通常是删减。 每个节点都有存在的理由。强调色只留给读者应当首先看到的 1–2 个元素。目标密度：4/10。
它能生成什么
全部 39 种视觉类型均提供三种静态样式：极简浅色、极简深色与完整编辑风格。可直接在浏览器中打开任意一种。无需构建步骤、JavaScript 或外部图片依赖。
架构图 组件 + 连接 |
 IT 现状 旧有格局 + 现代化改造 |
 流程图 决策逻辑 |
 时序图 时间维度的消息 |
 状态机 状态 + 转换 |
 ER / 数据模型 实体 + 字段 |
 时间线 轴上的事件 |
 泳道图 跨职能流程 |
 象限图 双轴定位 |
 雷达图 / 蛛网图 多轴对比 |
循环 / 飞轮 强化循环 + 共享中心 |
 嵌套图 包含式层级 |
 树状图 父节点 → 子节点 |
 组织架构图 归属 + 路由 |
 层叠图 层叠抽象 |
 维恩图 集合重叠 |
 金字塔图 / 漏斗图 排序层级或流失 |
 柱状图 类别对比 |
 矩形树图 以面积表示部分与整体 |
 折线图 时间趋势 |
 甘特图 时间线上的任务 + 阶段 |
 散点图 分布 + 相关性 |
 高层架构 集群上的端到端技术栈 |
 流程 多角色顺序工作流 |
 勋章图 多层数据存储 |
 数据流 按角色划分的管道步骤 |
 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，并选择 启用自动更新。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，然后开启新会话。
Factory Droid:
droid plugin marketplace add https://github.com/cathrynlavery/diagram-design
droid plugin install diagram-design@diagram-design --scope user
Droid 按提交而非清单中的显示版本来跟踪 Git 插件。若要获取已合并的更新，请运行 droid plugin marketplace update diagram-design，然后运行 droid plugin update diagram-design@diagram-design --scope user，并启动新会话。
Claude Cowork（组织市场）： 组织级 GitHub 市场目前要求使用私有或内部仓库，因此请先将此公开仓库镜像到你组织名下的仓库。在 组织设置 → 插件 中，选择 添加插件 → GitHub，连接该镜像，并从市场菜单中启用 自动同步。当包含插件版本升级的 Pull Request 合并到镜像仓库的默认分支时，自动同步会触发；直接 push 不会触发 webhook。从由此生成的组织市场中安装 Diagram Design。
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, /import-mermaid, /profile, and /doctor prompt templates. The unpinned Git install is intentional: Pi has no automatic package refresh, so run pi update --extensions to pull merged updates.
One-time migration: an existing standalone
npx skills addcopy will not start following the Codex marketplace automatically. Remove that standalone copy, then use the Codex marketplace commands above. Likewise, uninstall a personal Cowork copy and reinstall Diagram Design from your organization's marketplace. Future marketplace version bumps then flow through each client's native update path.
Editable install
Managed installs are convenient, but changes to references/style-guide.md may be replaced by package updates. Saved profiles in ~/.diagram-design/profiles/ survive updates, and projects with a .diagram-design marker are unaffected. Clone the repo and install the local path if you plan to customize the working style guide directly:
Wait, I accidentally output source. Need replace with translation. Final must only translation. Let's correct.
Final:
Run /reload ... translation. Ensure no source.
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, /import-mermaid, /profile, and /doctor prompt templates. The unpinned Git install is intentional: Pi has no automatic package refresh, so run pi update --extensions to pull merged updates.
One-time migration: an existing standalone
npx skills addcopy will not start following the Codex marketplace automatically. Remove that standalone copy, then use the Codex marketplace commands above. Likewise, uninstall a personal Cowork copy and reinstall Diagram Design from your organization's marketplace. Future marketplace version bumps then flow through each client's native update path.
Editable install
Managed installs are convenient, but changes to references/style-guide.md may be replaced by package updates. Saved profiles in ~/.diagram-design/profiles/ survive updates, and projects with a .diagram-design marker are unaffected. Clone the repo and install the local path if you plan to customize the working style guide directly:
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
共享技能位于 skills/diagram-design/。Pi 通过仓库的标准 skills/ 包目录发现它；Claude Code、Codex、Factory Droid 以及其他支持 Agent Skills 的工具使用相同的文件。
接入 — 让图表呈现你的品牌
核心目标：用你的色彩与字体交付杂志级品质的图表，而非通用模板。
开箱即用，图表即以干净的 jet-black + atomic-tangerine 色板呈现（white-smoke 纸面、jet-black 墨色、atomic-tangerine 强调色、blue-slate 弱化色、silver 细线）。已可直接截图使用。但 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 令牌 |
| 主要文本颜色 | ink 令牌 |
| 次要 / 说明文本 | muted 令牌 |
| 卡片或容器 | paper-2 令牌 |
| 最常用的品牌颜色（CTA、链接、标题） | accent 令牌 |
<h1> 字体族 |
title 字体 |
<body> 字体族 |
node-name 字体 |
<code> / <pre> 字体 |
sublabel 字体 |
对比度检查会自动执行
在写入令牌之前，该技能会验证 ink 相对于 paper 的 WCAG AA 对比度。如果你的网站存在在图表字号（9–12px）下无法通过对比度的颜色，它会建议一个调整后的数值，并解释原因。
默认可访问
每个图表模板都会为内联 SVG 提供可访问名称和描述：role="img"、可解析的 aria-labelledby，以及首个子元素的 <title> / <desc> 占位。ID 会按图表和变体添加前缀，因此多个 SVG 导出可以安全地内联到同一页面，而不会导致可访问名称 ID 重复。装饰性示例图标则会从辅助技术中隐藏。
手动覆盖
更希望手动设置令牌？打开 skills/diagram-design/references/style-guide.md 并编辑表格。下游所有内容都从该处读取——全部 39 个图表、标注原语以及图库都会继承语义角色名称（使用 accent，而不是 #eb6c36）。
首次运行门禁
该技能不会悄悄地把默认皮肤图表交付到已建立品牌的项目中。在新项目中首次使用时，它会检查 style-guide.md 是否已自定义。如果没有，它会暂停并询问：
“这是你在这个项目中的第一张图表。样式指南仍为默认状态。你要运行引导流程、手动粘贴令牌，还是继续使用默认设置？”
完整规格参见 skills/diagram-design/references/onboarding.md。
处理多个客户
只需接入一次品牌，将结果保存为命名配置文件，然后在每个客户项目中添加一个 .diagram-design 标记，其中包含 profile: <slug>。带标记的项目会直接读取 ~/.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)
你的 agent 会选择合适的图示类型，生成 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
语义模式与可选动效
当行为本身很重要时，该技能会先选择语义模式，再选择视觉类型。七种已路由的模式涵盖扇入队列与瓶颈、重复阶段槽位、非结构化输入转换、成对策略追踪、安全铺设通道、治理目录以及补偿性安全层。每种模式都在 semantic-patterns.md 中定义了触发条件、基本图元、预算、反模式、静态回退方案，以及最接近的视觉类型。
动效是可选的，也不会新增一种视觉类型。animation.md 定义了 none、reveal、step 和 loop 模式，并提供完整的静态首帧、确定性时序，以及可在交互环境中使用的控件。低动效输出会显示完整的静态帧，并隐藏或禁用播放控件。动态 HTML 使用 template-motion.html 中经过审阅的精确控制器；任意或修改过的内联脚本、远程资源、CSS 导入以及可执行的 HTML 属性都会被拒绝。默认值为 none：常规输出保持静态且不含脚本。example-policy-trace-animated.html 是这一自包含的交互式示例。
从 draw.io 或 Mermaid 导入
如果你已有 draw.io / diagrams.net 或 Mermaid 格式的图表，可以将该技能指向源文件，它会重绘这些图表——内容保持一致，沿用本设计系统，并按目标所需呈现。
一个包含 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
或者直接说："把这份 drawio 文件重画进我的演示稿"、"让这段 Mermaid 更像编辑级图表"，或*"把这个 Mermaid 改得更适合幻灯片"*。
读取 draw.io 生成的常见容器格式——.drawio、.drawio.xml、.drawio.png（内嵌图形）以及 .drawio.svg——包括在编辑器里看起来像 base64 乱码的压缩负载。
对于 Mermaid，支持 .mmd、.mermaid，以及 Markdown 中一个或多个带围栏的 mermaid 代码块。它只解析文本：不渲染、不执行 JavaScript、不依赖浏览器或网络，也不跟踪 click targets。
四个调节项
重点不是转换，而是让输出适配它的去向。同一份源文件，三种不同的图示：
| 调节项 | 选项 | 改变的内容 |
|---|---|---|
| 格式 | 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 的自动布局。以下内容总会保留：组件、关系、分组和方向。参见 references/import-drawio.md、references/import-mermaid.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
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
也可以直接用自然语言提问：
"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。
对于启用动效的 HTML，应导出明确的最终状态：打开 ?motion=static，等待 document.fonts.ready 完成，并在截取前确认动效根节点带有 data-frame="static"。只有在明确要求某个命名的中间帧时，才使用 ?motion=step&step=N。
Architecture
渐进式披露。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
│ ├── 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
│ ├── 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
│ │ ├── 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
│ │ ├── 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
│ │ └── 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-policy-trace-animated.html
│ └── example-sequence-oauth*.html
├── scripts/
│ ├── 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
│ ├── test-verify-docs-sync.py — docs/routing-surface gate tests
│ └── fixtures/
│ ├── sample-flowchart.mmd
│ ├── sample-readme-with-mermaid.md
│ └── sample-adversarial.mmd
├── docs/adr/ — short records of settled design decisions
└── docs/screenshots/ — README images + source-digest manifest.json
这会保持 agent 的工作上下文紧凑：常规图形加载一个类型参考；行为丰富的图形加入路由后的语义参考；动画仅在选中时引入其契约。
贡献 / skin lint
提交新示例前，运行 python3 scripts/lint-skin.py <your-new-example.html>。
全仓库检查 python3 scripts/lint-skin.py --all --baseline 覆盖示例与模板，并且必须保持绿色。
CI 会分别校验语义路由、动画示例结构、动画 skin、每个已发布的动效资源，以及对控制器契约的对抗性变更，即使较早门禁失败，也会报告后续门禁结果。语义路由必须通过 python3 scripts/verify-semantic-motion.py --markdown-only；动画示例有独立的 --example-only 门禁。每个已发布的动效模板/示例也必须通过 python3 scripts/verify-motion.py --shipped。
该 linter 的 a11y 类别会拒绝缺少可解析的可访问名称的图形 SVG，
空或位置不当的 title/description，或不安全的裸 title / desc ID。它还会锁定经过审阅的指定动效控制器，并拒绝远程资源、CSS @import、非片段式 CSS url()，以及 onclick 或 srcdoc 等可执行属性。
如果你修改 draw.io 导入路径，python3 scripts/verify-drawio-import.py 也必须通过——
它会驱动真实 extractor，针对 scripts/fixtures/sample-architecture.drawio 在所有四种
容器格式上运行，并检查引用保持同步。
如果你修改 Mermaid 导入路径，python3 scripts/verify-mermaid-import.py 也必须通过——
它覆盖所有受支持的语法、多块 Markdown、对抗性标签、信任边界
行为、资源上限、具名失败，以及 reference/command 接线。
标签布局通过几何方式设置门禁：python3 scripts/verify-geometry.py --all 在标签遮罩与文档中更晚声明的节点重叠时会导致 CI 失败，因为节点填充会在渲染时裁切文本。python3 scripts/test-verify-geometry.py 会从正反两个方向保证该检查器的可靠性。
Treemap 有第二道几何门禁，因为它们的核心主张就是面积 就是 编码：python3 scripts/verify-treemap.py --all 在某个单元格的绘制面积占比与其中显示的数值不一致，或标签超出其指向的单元格时，会导致 CI 失败。它以 相对 数值衡量面积误差——绝对数值恰恰会让最可能出错的小单元格通过。python3 scripts/test-verify-treemap.py 会从正反两个方向保证它可靠。
文档和路由表面本身也会被门禁：python3 scripts/verify-docs-sync.py 在 SKILL.md 描述丢失某种类型的词法钩子、示例库无法访问已发布示例、README 树中列出不存在的文件、某个相对引用链接失效、扫描器可见的支持路径未随 skill 包一起发布，或任何命令/提示表面与其路由参考不一致时，都会导致 CI 失败。python3 scripts/test-verify-docs-sync.py 会以对抗性方式演练这些较新的检查，包括 Hermes Agent 使用的严格打包器行为。该 skill 还附带 skills/diagram-design/scripts/self_check.py ——一个精简的输出检查器，已安装的 agent 可将其运行在自己生成的图形上；python3 scripts/test-self-check.py 会保证其可靠性。已定型的设计决策（为什么只有一个固定 controller、为什么模式从不新增类型、自动播放策略、SKILL.md 字节上限、为什么标签布局要通过几何方式验证，以及为什么客户端 profile 使用 marker 优先解析）以简短 ADR 的形式存放在 docs/adr/ ——在重新争论任何一项之前先阅读它们，确定新政策时新增一篇。
所有 pull request 和 push 都会通过 GitHub Actions CI 在 Linux、Windows 和 macOS runner 上自动验证（.github/workflows/ci.yml）。
lint-skin.py 读取源码。lint-render.py 渲染它——headless Chromium
会报告实际被绘制的内容，从而捕获被 SVG
视口截断的内容、塌缩的 SVG、页面横向溢出、缺失的本地资源以及 JS
错误。两者都会在 CI 中针对每个 pull request 运行。
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
裁剪按绘制结果而非几何形状来测量：SVG 子元素上的 getBoundingClientRect() 会忽略描边宽度、标记和滤镜溢出，也完全不考虑 clip-path 或 overflow: visible，因此它既会漏掉真实发生的裁剪，又会把并不存在的裁剪当成事实。于是，每个 SVG 都会先按原始代码截图，再在其 overflow 限制被放开后截图，并对两张图进行比对——若外部出现了额外的墨迹，就说明它原本被裁掉了。放开是分级进行的——先只放开 SVG 本身，再逐个放开每个产生裁剪的祖先元素——这样，外层容器的放开不会掩盖 SVG 自身边缘的溢出；即使某个 SVG 在原始代码中设置了 overflow: visible，只要它仍处在裁剪容器内，也会被检查。
--self-test 会在 23 个用例中校验上述所有行为，其中过半属于必须不被标记的用例；它还会校验测量结束后 DOM 保持逐字节一致。
没有基准图像，因此没有任何需要重新录制的截图，仓库里也不存在 PNG 文件。
网络在浏览器的解析器处被切断，覆盖 WebSocket 以及其他任何绕过请求路由的通道，请求路由则作为第二层防护；--fonts 会精确排除两个 Google Fonts 主机名，并且只允许通过 HTTPS 访问它们。既然判定依据是像素，CI 会锁定 Playwright 及其 Chromium 构建，而不是安装最新可用的版本。
默认运行与 --fonts 下的字体度量并不相同。 当网络被阻断时——这是默认状态，也是 CI 的运行状态——文本会使用回退字体排版，而不是 Instrument Serif 和 Geist。它是确定性的，也与机器无关，这正是 linter 所需要的；但这并不是读者最终看到的效果。若你关心真实文本是否放得进文本框，请在本地运行 --fonts --all。
什么时候加载什么
启动时，智能体只能看到技能名称和描述。当请求匹配时，它加载 SKILL.md；语义、类型和动画参考资料只会在相关时才被拉取。
| 你请求…… | 智能体加载 |
|---|---|
| “给我画一张流程图” | 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.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 + 所选类型的参考资料 |
| 常规静态图表制作（39 种视觉类型中的任意一种） | 仅 SKILL.md + 该类型的参考资料 |
无论存在多少类型，智能体只读取你需要的一个。明天新增一个类型，其他部分也不会改变。
当以下条件成立时，它就在正常工作……
- 一个常规请求（“帮我做一张流程图”）会加载
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 生成的关键。Mono 用于技术内容（端口、URL、字段类型），而不是笼统的“开发者”美学。带珊瑚色调的焦点节点会将视线引向真正重要的 1–2 件事。完整规范见 SKILL.md。
图元
- 注释标注 — 斜体 Instrument Serif + 虚线贝塞尔引线，用于位于页边的编辑性旁注。见
skills/diagram-design/references/primitive-annotation.md。 - 手绘感滤镜 — 通过 SVG turbulence + displacement map 生成手绘感变体。适合文章，不适合技术文档。见
skills/diagram-design/references/primitive-sketchy.md。 - 图标集 — 55 个单色 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。
- 任何列表 → 表格或项目符号。
- 前后对比 → 表格。
- 单形状“图表”——一个带标签的方框 → 直接写成一句话。
绘制前，请问问自己：读者从这张图里获得的，是否会比一段写清楚的段落更多？ 如果不会，就别画。
贡献
欢迎贡献——新的图表类型、import 语法支持、示例、文档和工具。查看 CONTRIBUTING.md 了解校验门禁与工作流，并查看 CODE_OF_CONDUCT.md 了解社区准则。
关于
由 Cathryn Lavery 制作——BestSelf.co 创始人。我在 littlemight.com 撰写关于 AI、创业和设计赏心悦目事物的内容——博客 + 通讯。
如果这个项目对你有帮助，欢迎 给仓库 star，并来 X 上打个招呼。