Diagram Design

给 Claude Code / Codex / Pi 用的编辑级画图 skill——38 种图表，品牌自适应，告别 Mermaid-slop

更新于 2026-09-09

一句话定位

让 AI Agent 画出设计师不会嫌弃的图

一个 Agent Skill，封装 38 种编辑级图表类型（v2.6.x 持续扩容）+ 一套品牌自适应的设计系统。装到 Claude Code / Codex / Pi 后，一句话指令就能生成自包含 HTML+SVG 图（架构图、流程图、四象限……），60 秒匹配你网站的品牌色和字体。还能把 draw.io / Mermaid 旧图重绘成同一套设计语言。适合独立开发者、技术博主、内容团队——任何需要「文配图」但不想开 Figma 的人。

核心数据

3 平台 = Claude Code / Codex / Pi。产物是纯 HTML+SVG，无构建步骤、无 JS 运行时、无外部图片依赖，双击即开。

AI 画图的三个老毛病

最高质量的动作往往是「删除」

Diagram Design 的设计哲学不是「画得多」，而是「每个节点都配得上它的位置」。

• 目标密度 4/10——一张图只用 40% 的视觉空间，留白本身就是设计
• 强调色只给 1-2 个焦点——读者第一眼该看的东西，用唯一的强调色标出来，其余全灰
• 所有坐标/间距能被 4 整除——不可妥协的栅格规则，这正是它不像 AI 生成的原因
• 1px 发丝边框，零阴影，圆角上限 10px——克制即高级

38 种图表类型矩阵（核心 27 类）

每种类型解决一类「关系」——组件、时序、层级、集合、对比、分布。按色块归类：架构类 / 层级类 / 数据类。

架构：渐进式加载

Agent 启动时只看到 skill 名和描述。请求匹配后才加载 SKILL.md；类型/语义/动画引用只在相关时才拉入——保持工作上下文紧凑。

按需加载：加类型不增上下文成本

「明天加个新类型，其余一切不变。」——关键在于 Agent 永远只读它需要的那一个引用。

不管存在多少种类型，Agent 只读它需要的那一个。39 种类型的上下文成本 = 1 种类型的成本。v2.3+ 语义模式更进一步：行为先于布局，新增行为不新增类型。

行为先于布局

2.3 版引入「语义模式」：描述行为而非布局。一个队列、策略追踪、信任边界，都可以复用最近的现有类型，而不必增加类型总数。

• 扇入队列 / 瓶颈——多源汇入单处理点（最近类型：架构图）
• 重复阶段槽位——同样的步骤跑多次（最近类型：流程图）
• 非结构化输入转换——原始数据 → 结构化输出（最近类型：数据流）
• 配对策略追踪——对比两个请求的权限路径（最近类型：流程图）
• 安全铺装路 + 治理目录 + 补偿安全层——每条都定义触发条件、原语、预算、反模式、静态回退

核心洞察：类型数 = 视觉布局数，是个有上限的设计约束；语义模式可以无限增长而
不撑爆布局空间，因为它「借用」已有类型。

60 秒匹配你的网站

默认配色是 jet-black + atomic-tangerine（截图即用）。但 60 秒 onboarding 更好——skill 抓你网站，自动映射成语义 token。

首次运行有「门禁」：若 style-guide.md 未定制，skill 会暂停询问——不会静默把默认皮肤的图发进品牌项目。

draw.io / Mermaid → 同一设计语言

点 skill 去读旧源文件，重绘成这套设计系统——同样内容，按目标场景调。关键是「适配输出」，不是「转换」。

每次导入结束附「保真度台账」：什么被合并、折叠、删除。绝不继承源的坐标/配色/字体/draw.io 的斜线连接 spaghetti——只继承组件、关系、分组、方向。

一段话讲清规范

一个强调色，每图 1-2 个焦点。

默认可访问，静态优先

• 语义命名——每个 SVG 都有 role="img"、可解析的 aria-labelledby、首子 <title>/<desc>。屏幕阅读器会朗读图的标题和描述。
• ID 前缀隔离——每图每变体前缀化，多个 SVG 内联到同一页也不会撞 accessible-name ID。
• 静态是默认——动画可选（none/reveal/step/loop）。prefers-reduced-motion 显示完整静态首帧，隐藏播放控件。
• 动画契约严格——只用 review 过的 controller，拒绝任意/修改的内联脚本、远程资源、CSS @import、可执行 HTML 属性（onclick/srcdoc）。
• 几何级标签校验——CI 跑 verify-geometry.py，标签遮罩若压到后面声明的节点就 fail（否则节点填充会裁切文字）。

适合谁用

需要权衡

• 强依赖 LLM 推理质量——选型、删减、布局全靠模型理解，弱模型可能选错类型或过度删减。skill 的「先陈述选型再画」机制部分缓解。
• 设计口味主观——「编辑级」「4/10 密度」是作者个人审美。不喜欢这种克制风格的人，定制 style-guide 成本在可接受范围，但本质仍是这套范式。
• 导出 PNG 需 Playwright——pip install playwright && playwright install chromium，首次有环境搭建成本（SVG 导出零依赖）。
• 27 类型需学习成本——新手可能不知道「飞轮」用 Loop、「双轴定位」用 Quadrant。好在 Agent 会自动选型，但理解类型语义能更好指挥。

三步开跑

# 1. 装到你的 Agent（任选其一）
pi install https://github.com/cathrynlavery/diagram-design     # Pi
codex plugin marketplace add cathrynlavery/diagram-design   # Codex
# Claude Code: /plugin marketplace add cathrynlavery/diagram-design

# 2. 品牌自适应（可选，60 秒）
「onboard diagram-design to https://yoursite.com」→ 确认 → 写入 style-guide.md

# 3. 自然语言画图
「画个我应用的架构图：frontend、backend、database、Redis cache」
「画个四象限，Q2 项目按 impact vs effort」
「画个带 401 token 刷新的 bearer 调用时序图」
「把这个 .drawio 文件重画成我演讲用的图」

或直接打开 skills/diagram-design/assets/index.html 浏览全部 38 种 × 3 变体（light/dark/full-editorial）的实样画廊。

未来空间

35.5k stars（8 个月翻倍不止）验证了「AI 文配图」是真实刚需。它把「设计品味」工程化成可复用的 Agent skill，是这个赛道少见的非通用、有强审美主张的产物。语义模式（行为≠布局）的解耦设计是关键巧思——让类型数有上限而能力无限延伸。若作者持续维护选型指南和导入管线，有望成为内容创作者生态的默认画图工具。