架构图别再千篇一律：diagram-design 从官网抽色出编辑级图表

写技术博客或产品文档时，最容易翻车的往往不是文字，而是图。问 Agent「画一张架构图」，回来的经常是一堆圆角方块、随机配色、和站点完全不搭的字体——设计师看一眼就摇头，自己又懒得开 Figma 抠半小时。源微信页触发了验证码拦截，本文以官方仓库 cathrynlavery/diagram-design（MIT，约 40k Star）与其 README / onboarding 文档为准，不臆造未公开能力。

核心卖点可以压成一句话：把官网（或本地设计令牌）丢给技能，60 秒抽出纸色、墨色、强调色和字体，之后每一张图都按你的品牌皮肤出 HTML+SVG。 不是又画一张 Mermaid，也不是导出一堆位图糊进文档。

一、它解决什么：模板货图表 vs 可进文档的编辑级图

作者在 littlemight.com / BestSelf.co 写稿时遇到的痛点很具体：每次要架构草图、流程图、优先级金字塔，Claude 吐出来的都是「通用圆角盒子」，既不像站点，也不像设计系统。两条出路——跟 Figma 耗半小时，或者干脆不配图。

diagram-design 的回答是：

默认皮肤是 jet-black + atomic-tangerine（白烟灰纸色、墨黑、橘强调、蓝灰弱化、银发丝线），截图已经能用；真正拉开差距的是 onboarding——让「纸色 = 官网背景、强调色 = CTA」。

官方设计哲学：最高质量的操作往往是删除。 每个节点都要挣得自己的位置；强调色只留给读者该先看的 1–2 处；目标视觉密度约 4/10。

二、安装：Claude Code 市场一装，多端同一套技能

Claude Code 推荐走插件市场：

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

装完建议在 /plugin → Marketplaces → diagram-design 打开 Enable auto-update（第三方市场默认关自动更新）。需要立刻刷新时执行 /reload-plugins。

同一仓库也覆盖 Codex、GitHub Copilot、Factory Droid、Pi、Kiro、OpenCode 等 Agent Skills 宿主。若你打算长期改 references/style-guide.md，官方建议可编辑安装：clone 后把 skills/diagram-design 软链到 ~/.claude/skills/（或其他宿主的 skills 目录），避免托管更新覆盖你的皮肤。

git clone https://github.com/cathrynlavery/diagram-design.git ~/code/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

在 Claude Code 里可以说自然语言：「给我画一张前后端 + Redis 的架构图」「按影响力×工作量做个象限」「Bearer 调用遇 401 刷新令牌的时序图」。Agent 会选图型、写 HTML、落盘；也可以直接从模板起步：

cp skills/diagram-design/assets/template.html my-diagram.html        # 极简浅色
cp skills/diagram-design/assets/template-full.html my-diagram.html   # 含摘要卡片的编辑版
cp skills/diagram-design/assets/template-motion.html my-diagram.html # 可选无障碍动效

本地预览全部 39 种图型（浅色 / 深色 / 全编辑三套变体）：

xdg-open skills/diagram-design/assets/index.html   # Linux
# 或浏览 https://cathrynlavery.github.io/diagram-design/

三、品牌 onboarding：给个网址，令牌落到 style-guide

这是源标题真正指向的能力。对话里说：

onboard diagram-design to https://yoursite.com

Agent 会：抓首页 → 抽主色与字族 → 映射到语义角色 → 出示 diff → 写入 skills/diagram-design/references/style-guide.md。你确认后，后续每张图继承同一皮肤。

写入前会做 WCAG AA 对比度检查：若站点色在图内 9–12px 字号下不合格，技能会提议调整值并说明原因。品牌匹配还会给出 fidelity receipt（采样 URL、角色色、字族与字重、字体源、回退策略），公开站字体尽量直接使用并在渲染后校验，而不是悄悄换成系统默认字体。

多客户并行：onboarding 一次可存成命名 profile；项目根放 .diagram-design 标记文件写上 profile: <name>，工作区直接读 ~/.diagram-design/profiles/<name>.md，不会互相覆盖安装目录里的共享 style-guide.md。Claude Code 可用 /diagram-design:profile，Pi / Droid 用 /profile。

首次门禁：新项目若还没改过 style-guide，技能不会默默用默认皮出图，而会停下来问——跑 onboarding、手贴令牌，还是坚持默认？

也可手改 style-guide.md 表格；下游 39 种图、注释原语、画廊全部读语义角色名（写 accent，不写死 #eb6c36）。

四、39 种图型 + 语义模式：先行为、后排版

图型覆盖架构、IT 现状、流程图、时序、状态机、ER、时间线、泳道、象限、雷达、飞轮 Loop、嵌套、树、组织、分层、韦恩、金字塔/漏斗、柱/线/散点、Treemap、甘特、高层栈、多角色流程、Medallion、数据流、权限矩阵、Sankey、鱼骨、Wardley、看板、用户旅程、部署、依赖图、UML 类图、故事地图、库表、极坐标、瀑布等。每种有 light / dark / full-editorial 三套静态变体，无构建、无外置 JS、无外部图片依赖（字体可走 Google Fonts）。

行为复杂时，技能先选 语义模式（8 类：汇聚队列、重复阶段槽、非结构化输入变换、成对策略轨迹、安全铺路、治理目录、补偿安全层、可追踪块分解），再选最近的视觉图型。动效是可选层（none / reveal / step / loop），默认 none；prefers-reduced-motion 下只保留完整静态帧。

渐进披露控制上下文：日常「画个流程图」只加载 SKILL.md + type-flowchart.md；提到 onboard / import / animate 才追加对应 references。图再多，Agent 也只读你需要的那一份。

五、从 draw.io / Mermaid / Excalidraw 重绘，而不是「格式转换」

已有 .drawio、.mmd / Markdown 里的 mermaid 围栏、.excalidraw 草图时，可以让技能按本设计系统 重绘：

/diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:import-mermaid README.md --diagram=all
/diagram-design:import-excalidraw whiteboard.excalidraw --size=slide-16x9 --detail=simplified

四个旋钮决定「去哪用」：

每次导入结束有 fidelity ledger：合并了什么、折叠了什么、丢掉了什么。绝不继承源坐标、源配色、源字体、draw.io 对角线意大利面、Mermaid 自动布局或 Excalidraw 手绘几何——只继承组件、关系、分组与方向。

导出用 /diagram-design:export-diagram（或自然语言），SVG 抽出节点并注入字体；PNG 默认靠 Playwright 2× 光栅。可追溯块分解模式还可加 --registry 吐出 .registry.json。

六、实战自检：环境探测与「算工作正常」清单

配套脚本 practice/check_diagram_design_env.sh 会探测：git、可选 clone、技能目录、style-guide.md、画廊 assets/index.html、以及 self_check.py 是否存在。在已安装或可编辑 checkout 的机器上跑一遍，能快速确认技能包是否落盘。

官方「算它在工作」的验收标准很硬：

1. 例行请求只加载 SKILL.md + 一个 type 参考。

2. 动笔前 Agent 先陈述所选图型、模式、尺寸与计划删减，再渲染。

3. 产出是单个 .html，双击离线可开（除可选 Google Fonts 外无外网请求）。

4. 读屏能读到标题与描述；减弱动效偏好下是完整静态帧。

5. python3 skills/diagram-design/scripts/self_check.py <file> 打印 OK。

6. 品牌 onboarding 之后，新图使用你的 paper / ink / accent / fonts，并带 fidelity receipt。

不适合的场景也写清楚：需要交互式数据探查仪表盘、需要实时协作白板、或必须 1:1 保留源文件几何时——换别的工具。本技能盯的是 可进文档、可进幻灯片、像设计系统一部分的静态编辑级图。

七、排坑与边界

• 托管安装会覆盖手改的 style-guide：要长期换肤，用 clone + symlink，或依赖 profile + .diagram-design 标记。
• 首次门禁：别惊讶被拦住；先 onboard 或明确「用默认皮」。
• PNG 导出依赖 Playwright Chromium：一次性 pip install playwright && playwright install chromium。
• 自动更新默认关：Claude Code 第三方市场要手动 Enable auto-update。
• 动效 HTML 拒绝任意脚本：只允许审过的 controller；远程资源、CSS @import、可执行属性会被 lint 打回。
• 源站验证码：本文源微信链路上遇到过 verify.html；写稿以 GitHub 官方文档为准，命令与令牌名以仓库当前 README 为准。

一张能进文档的图，价值往往高于再多写两段正确但无感的说明。把官网交给 diagram-design，让强调色只打在真正重要的节点上——这比再调一轮「再圆润一点」的提示词靠谱得多。

参考链接

1. cathrynlavery/diagram-design

2. 在线画廊

3. Onboarding 规范

4. Cookbook 操作菜谱