Diagram Design 这个项目最近比较火，我来给大家解读下。AI工程师、架构师、内容创作者都会用到。它主要把自然语言制图请求转成品牌化、自包含的 HTML/SVG 图表...
| 版本 | 视觉类型 | 导入格式 | 主输出 | 通用上限 | 导出约束 |
|---|---|---|---|---|---|
| v2.6 · MIT | 45 种 | draw.io · Mermaid · Excalidraw | HTML · SVG · PNG | 9 节点 / 12 连接 | 用户提出后才导出 |
10 秒看懂
- 适合谁：AI 工程师、架构师、技术写作者，以及需要把 Mermaid、draw.io 或白板图整理成可发布图表的团队。
- 解决什么：把图型选择、品牌样式、信息密度、连线可读性和交付验收纳入同一条制图流程，避免只换配色却保留难读布局。
- 何时触发：用户要求创建架构图、流程图、数据图或其他图表；或者要把 draw.io、Mermaid、Excalidraw 内容重绘成更清晰的成品。
- 可复用：把语义模式与图形布局分层；让项目样式通过 profile/marker 稳定解析；导入内容先抽取再重绘；用明确的连接器、复杂度和 SVG 可访问性合同约束输出。
- 原项目 ：cathrynlavery/diagram-design
身份：一套把图型选择与制图质量写成规则的 Skill
diagram-design 面向图表创作与重绘，覆盖 45 种视觉类型。它将语义模式、布局语法、品牌皮肤和可验收的 SVG 输出分层处理；Skill 本身不是渲染器，而是由 Agent 执行的制图方法与文件工具箱。
diagram-design · v2.6
名称与版本
MIT 许可；仓库由 cathrynlavery 发布。输入可以是自然语言图表需求，也可以是已有图表文件。
创建图表或整理旧图
触发
架构、流程、时序、状态、ER、统计图等；也响应 draw.io、Mermaid、Excalidraw 的重绘请求。
让关系可读、输出可验收
使命
基于语义、读者和目标尺寸组织信息，交付可浏览、可复核、可移植的 HTML/SVG。
01 · 先删，再画
节点只代表独立概念，连线需要承载关系；通常保持 9 个以内节点、12 条以内连接，超出就拆成总览与细节。
02 · 语义先于布局
行为、状态、治理或风险是重点时，先选一个语义模式，再用最接近的视觉类型承载它。
03 · 保留意思，重做外形
导入图只作为内容来源；保留组件、关系、分组和方向，不继承源图的坐标、颜色和形状样式。
工作流：先判断是否该画，再路由到类型与输出
主干从样式解析、表达方式判断、语义/图型路由到生成和验收。导入、动画与导出是按输入和交付请求打开的条件分支。
01 · 解析项目皮肤与有效 profile
条件触发 --- 优先检查项目 .diagram-design marker；没有有效 marker 时读取当前 style-guide，判断是否为已定制样式。
- 输入 ：项目根目录的
.diagram-design、profile 文件库和 Skill 当前的references/style-guide.md。 - 输出：本次绘图采用的 effective style guide。有效 marker 直接选对应 profile；无效 marker 不作为路径或指令执行。
- 文件 ：
references/profiles.md、references/style-guide.md；marker 是项目侧可选配置。
02 · 首次默认皮肤时等待用户选方案
必须确认 --- 只在没有 marker、样式仍是出厂默认值时触发；用户可以接入品牌、选择已安装技能/本地设计系统、粘贴 token，或保留默认。
- 决策：style guide 仍全是 shipped defaults → 展示六个选择；已有定制 token → 跳过首次 gate，可建议保存为 profile。
- 输出：用户批准后的 style guide diff，或明确选用默认皮肤。写入品牌 token 前要先展示改动并取得确认。
- 文件 ：
references/onboarding.md负责从 URL、Skill、文件夹或手动 token 取样；references/profiles.md负责 profile 保存/载入。
03 · 判断图形是否比文字或表格更有效
条件触发 --- 如果读者从图里学不到更多，就改用段落、表格或列表，不为了"有图"而造图。
- 输入：读者需要理解的主题、关系、数量、决策逻辑或变化过程。
- 决策：架构、路径、状态或量化关系能被视觉布局更清晰地表达时继续；简单列表和单一事实直接写文字。
- 输出：采用图表，或将任务转向更轻量的文本/表格表达。
04 · 先选语义模式，再选 45 种图型之一
自动推进 --- 如果状态、行为、风险或控制关系承载含义，先选一个主要模式，再映射到最合适的布局；否则直接选视觉类型。
- 输入：图表要回答的问题、关系结构、读者熟悉度以及是否存在行为或治理语义。
- 路由：例如有限容量/排队 → Data flow；生命周期状态 → State Machine；信任边界 → Architecture；不匹配模式时直接选图型。
- 文件 ：
references/semantic-patterns.md、对应的references/type-*.md；具体候选来自SKILL.md §3。
05 · 加载布局参考，确定尺寸、细节与计划
条件触发 --- 选定类型后读取对应 type reference；导入图还需定格式、尺寸、细节档位和受众。渲染前简述类型、尺寸与预算裁剪；请求已锁定这些内容时可省略确认。
- 输入：图型与语义模式、目标载体（文档/幻灯片/社交/打印）、复杂度和用户对保真程度的要求。
- 决策：导入时选 HTML/SVG/PNG/HTML+PNG，尺寸 preset、faithful/balanced/simplified、engineer/mixed/executive；若请求已锁定这些内容，可跳过方案暂停。
- 文件 ：
references/output-spec.md和references/layout-budget.md；具体图型的引用文件提供布局语法。
◇ 是否有现成图表要导入重绘？ 新创作直接消费用户 brief；有源文件则先抽取中间结构。
- New diagram · 从需求与关系开始：沿用用户给的事实、范围与品牌；不需要导入解析脚本。
- draw.io · 提取节点与连接 ：
drawio_extract.py解析 XML / 压缩 payload，报告分组、方向、中心节点和复杂度。 - Mermaid / Excalidraw · 语法解析成结构摘要：分别运行抽取脚本；标签、链接、指令和 metadata 只作为不可信内容处理。
06 · 按需抽取导入图，登记 fidelity ledger
条件触发 --- 仅在导入时执行。只解析结构，不执行内容或加载其中的链接；再决定哪些节点合并、压缩或保留。
- 输入 ：
.drawio*、.mmd、含 Mermaid fence 的 Markdown 或.excalidraw。 - 输出：包含节点、边、分组、方向、结构线索与预算标记的 Markdown 摘要或 JSON IR；重绘前报告保留、合并、折叠和丢弃项。
- 文件 ：
references/import-drawio.md、import-mermaid.md、import-excalidraw.md及各自scripts/*_extract.py。
07 · 用所选模板和 SVG 原语重新绘制
自动推进 --- 输出单文件 HTML；静态为默认，按需使用 motion。导入场景只继承内容语义，不保留源图坐标与视觉主题。
- 实现：用最相近的 light/dark/full 模板，替换 eyebrow、标题与 SVG；应用已解析的 token、图型语法及 4px 几何网格。
- 连线：只用正交直角路径；标签要留出 6--10px 空隙并有遮罩；避免重叠、共用挂点和穿过非端点节点。
- 可选：动画仅在用户要求或明显能解释有序变化时启用；不动画时不需要脚本，动画版仍须包含完整静态含义。
08 · 执行 Taste Gate 与 SVG 技术检查
自动推进 --- 检查删减、层级、复杂度、连线几何、字体、移动端溢出、SVG 标题/描述和脚本安全。
- 设计：默认最多 9 节点、12 条连接、2 个强调色节点和 2 个注释；超限时拆成总览与细节图。
- 可访问性 ：SVG 用
role="img"与aria-labelledby连接唯一的 title/desc；标题先于 defs，移动端宽图局部滚动。 - 文件 ：已安装 Skill 可运行
scripts/self_check.py（无第三方依赖）；仓库贡献另有几何、动效与皮肤检查脚本。
09 · 交付 HTML，只有被要求时再导出
条件触发 --- 普通请求的最终文件是单个 HTML。用户要求保存、光栅化或转换时，才调用 SVG/PNG 导出路径。
- HTML：内嵌 CSS 与 SVG，无外部图片；默认静态。仅允许按 style guide 引用 Google Fonts，用户要求离线时切换系统字体。
- SVG 导出 ：
export_svg.py输出可独立打开和内嵌的 SVG，处理 scoped CSS 与 definition IDs；不需要第三方包。 - PNG 导出 ：
export_png.py使用 Playwright Chromium 截取 SVG，需安装 Playwright 和 Chromium；画面尺寸依据 viewBox 与 scale。
**路由判断：**语义模式描述"系统在做什么"，45 种视觉类型描述"信息如何排布"。两者共享一条图，不再叠加两套布局语法。
文件：入口规则、参考库、模板和小型解析脚本
文件树远超 30 项，因此先列工作流主干；45 种图型说明、模板示例和专项 reference 折叠在后面。
| 路径 | 类型 | 用途 | 步骤 |
|---|---|---|---|
| 入口与配置 | |||
SKILL.md |
router / spec | 定义风格 gate、意图判断、语义与图型路由、模板用法、导入/导出分支与质量合同。 | 1--9 |
.diagram-design |
project config | 可选 marker，以严格的 profile: <slug> 形式选择本项目皮肤。 |
1--2 |
| 参考文档 | |||
references/profiles.md |
reference | 解析 marker 与 profile，定义 save/load/list/update/reset/delete 的边界。 | 1--2 |
references/onboarding.md |
reference | 从网站、已安装 Skill、本地设计系统或手动 token 建立皮肤，并在写入前预览。 | 2 |
references/style-guide.md |
design tokens | 定义颜色语义、节点样式、字体角色、默认皮肤与字体来源。 | 1--2 · 7 |
references/semantic-patterns.md |
routing | 描述 9 类行为/治理模式及其必备元素、限制、反模式和静态回退方式。 | 4 |
references/type-*.md（45 个） |
layout grammar | 每种图的布局语法、类型特有预算、易错项和示例。 | 4--7 |
references/layout-budget.md |
layout rules | 4px 几何网格、45 类的局部复杂度上限和页面布局规则。 | 5 · 7--8 |
references/primitives-core.md |
SVG rules | 核心 SVG 节点、箭头、标签、图例和可访问性结构；细化六条连接器硬规则。 | 7--8 |
references/output-spec.md |
output spec | 尺寸预设、字体阶梯，以及导入时 format / size / detail / audience 四个决策轴。 | 5--6 · 9 |
references/import-*.md |
import flow | 分别规定 draw.io、Mermaid、Excalidraw 的触发条件、解析边界与重绘流程。 | 6 |
references/animation.md、export.md |
conditional reference | 用户要求动效或导出 SVG/PNG 时读取；静态与 HTML 仍是默认。 | 7 · 9 |
| 脚本 | |||
scripts/drawio_extract.py |
Python CLI | 解析 draw.io / 内嵌 mxfile，输出节点、边、分组和结构线索。 | 6 |
scripts/mermaid_extract.py、excalidraw_extract.py |
Python CLI | 将 Mermaid 文本或 Excalidraw scene 归一为相同形状的结构摘要，不执行源内容。 | 6 |
scripts/self_check.py |
validator | 检查 SVG 可访问性、单文件安全、viewBox 内容与动画结构；使用 Python 标准库。 | 8 |
scripts/export_svg.py、export_png.py |
export | 按用户请求导出独立 SVG 或 raster PNG；PNG 路径依赖 Playwright Chromium。 | 9 |
| 资源 | |||
assets/template*.html |
template | 最小浅色、暗色、完整编辑式与可选 motion 起始模板。 | 7 |
assets/example-*.html |
example | 45 种类型及 dark/full 等变体示例，供布局与标记实现参考。 | 4 · 7 |
专项 references、45 种图型名录和扩展资源
其他 references： doctor.md（诊断/修复）、export-registry.md（导出规格登记）、primitive-annotation.md、primitive-icons.md、primitive-sketchy.md、primitive-terminal.md（注释、图标、手绘与终端原语）。
45 个 type references： type-architecture.md、type-architecture-delta.md、type-it-state.md、type-flowchart.md、type-sequence.md、type-state.md、type-er.md、type-timeline.md、type-swimlane.md、type-quadrant.md、type-radar.md、type-polar.md、type-loop.md、type-nested.md、type-tree.md、type-org-chart.md、type-layers.md、type-exploded.md、type-axonometric-plan.md、type-venn.md、type-pyramid.md、type-bar.md、type-waterfall.md、type-treemap.md、type-heatmap.md、type-line.md、type-gantt.md、type-scatter.md、type-high-level.md、type-process.md、type-medallion.md、type-data-flow.md、type-dp-integration.md、type-dp-security-matrix.md、type-sankey.md、type-fishbone.md、type-wardley.md、type-kanban.md、type-journey.md、type-service-blueprint.md、type-deployment.md、type-dependency.md、type-uml-class.md、type-story-map.md、type-db-schema.md。
Assets： template.html、template-dark.html、template-full.html、template-motion.html、template-terminal.html、icons.html 与按图型命名的 examples；dark/full/terminal/animated 仅为适用时的变体。
仓库级贡献检查： SKILL.md 另提到 verify-geometry.py、verify-motion.py、lint-skin.py。它们是仓库贡献门禁，不等同于已安装版随附的 self_check.py。
依赖：核心创作轻量，导出与样式接入按需启用
读取 Skill 和手工生成 HTML/SVG 不依赖 MCP 服务；脚本与浏览器依赖只在导入校验、PNG 导出等分支出现。
- Runtime · 浏览器 + 可选 Python 3
- 最终 HTML/SVG 在现代浏览器中打开。
- 导入抽取和 self-check 使用 python3。
- 默认静态输出无需 Node.js 或服务端。
- Packages · 无核心第三方包
- 抽取脚本和
self_check.py以 Python 标准库为主。 export_svg.py无第三方依赖。- PNG 导出使用 Python Playwright 包。
- 抽取脚本和
- System tools · Chromium 仅用于 PNG
- 普通 HTML/SVG 创作只需浏览器预览。
- PNG 导出要安装 Playwright 与其 Chromium 浏览器。
- 用户要求离线时，字体走系统字体配置。
- External APIs · 无固定外部 API：在线字体是可选样式资源。品牌 onboarding 可抓取 URL，但需先确认用户信任；本地设计系统和手动 token 不需要外网抓取。
- MCP / cross-skill · 没有强制 MCP 或跨 Skill 依赖：由当前 Agent 读取文档、组织 SVG 并执行 Python 脚本。需要图片或额外设计系统能力时，由宿主环境提供即可，不是安装前提。
**运行边界：**输出被设计成可独立打开的 HTML 文件；默认不引入脚本、远程图片或服务端。只有在要求 PNG、启用动画或接入在线品牌来源时，依赖才随分支增加。
输出：HTML 是主交付，SVG / PNG 是显式请求的派生产物
原生制图和导入重绘都以可读、可迁移的 HTML 成品为默认；导出只在用户要求时执行。
| 类别 | 产物 | 说明 |
|---|---|---|
| 主交付 | 单文件 HTML | 内嵌 CSS 与 SVG，静态优先。Google Fonts 是可允许的例外；离线要求下使用系统字体。 |
| 导出 | SVG | 可独立打开或嵌入其他文档；导出脚本会保留图形样式并处理 defs ID。 |
| 导出 | PNG | 由 Playwright Chromium 对 SVG 截图；按 viewBox 尺寸和 scale 输出透明背景栅格图。 |
| 中间产物 | Markdown / JSON IR | 导入解析阶段的结构摘要，含节点、边、分组、方向、预算提示及必要时的完整 JSON。 |
**边界与失败恢复：**图超过预算时拆成 overview + detail；无法解析的源文件按脚本错误停下，不要把原始绘图当作指令执行。动画输出必须保留完整静态语义，并在 reduced-motion 环境隐藏或停用播放控制。
可复用的设计模式
- 先问图是否比段落或表格更有解释力，再决定是否绘制。
- 当状态、风险或规则行为承载含义时，先选一个语义模式，再映射到视觉图型。
- 用 profile 与项目 marker 把品牌样式同 Skill 安装目录分离，降低升级覆盖风险。
- 导入图只保留节点、关系、分组和方向；重新布局并报告合并、压缩或丢弃项。
- 把复杂度上限、正交连线和 SVG title/desc 变成可检查的输出合同。