project-dashboard高级技巧：自定义项目视图与筛选功能
2026/8/14 8:53:23
用 Claude Code 技能库告别 Mermaid：diagram-design 的设计哲学与实用价值
核心观点
这是一个由独立开发者 Cathryn Lavery 为 Claude Code 构建的「图表生成技能」，解决的核心问题不是"AI 能不能画图"，而是"AI 能不能画出设计师不觉得丢人的图"。它提供 29 种图表类型，输出纯 HTML + SVG，零依赖，开箱即读，支持 60 秒内将你网站的品牌色/字体全量应用到所有图表。这个项目在 2026 年 8 月 11 日单日新增 1,612 个 GitHub Star，进入 GitHub Trending 总榜——这个传播速度本身就说明它踩中了一个真实痛点。
技术定位：不是范式突破，是精准填坑
先放进历史脉络里看：AI 辅助图表生成经历了三个阶段：
- 文本渲染时代：用 PlantUML / Mermaid 写 DSL，让工具渲染，AI 只负责写 DSL 字符串。优点是布局稳定、无需坐标，缺点是视觉天花板很低——渐变、阴影、品牌色基本做不到。
- 代码生成图表时代：让 AI 直接写 SVG / Canvas 代码，理论上视觉无限制，但 AI 对坐标的空间推理能力弱，复杂图 100% 会出现元素错位。
- 模板约束 + AI 填充：diagram-design 选择了第三条路——人工设计好 29 种高质量图表模板（样式、布局、语义角色），让 AI 只负责往模板里填数据和描述，不做坐标计算。
这不是范式突破，是工程化填坑。它的聪明之处在于：把"AI 不擅长的事"（精确坐标计算、品牌配色决策）提前由人做掉，留给 AI 的只是"AI 擅长的事"（理解用户意图、提取品牌信息、选择合适图表类型）。
关键机制：语义角色与模板分离
整个系统最核心、最值得深想的设计是语义模式（Semantic Patterns）与布局模板解耦。
作者的方案是：用有限的 29 种图表类型，通过"语义系统模式"覆盖更多场景——比如「队列」「策略追踪」「信任边界」这些概念，不需要单独建立图表类型，只需把它们的行为描述映射到最接近的现有类型即可。这控制了复杂度（类型数量不会爆炸），又保留了表达能力。
品牌 onboarding 的机制也同样精巧：
输入：你的网站 URL → 自动抓取主页 → 提取主色/背景色/字体族 → 映射到语义 token（paper / ink / muted / accent / link） → 写入 style-guide.md → 所有 27 个图表模板从同一份 token 文件读取下游全部读语义角色名（accent），而不是硬编码颜色值（#eb6c36）。这意味着你改一次style-guide.md，29 张图全部更新——这是正确的架构设计，不是取巧。
对比 Mermaid 和手写 SVG 的真实权衡
交叉验证来自 ClassMethod（日本云计算咨询公司）的工程师于 2026 年 7 月发布的独立技术评测（见下方交叉验证节）。他们对比了三种方案：
| 维度 | Mermaid CLI | 手写 SVG | diagram-design 式模板 |
|---|---|---|---|
| 视觉天花板 | 低（无渐变/阴影） | 高（理论无限） | 中高（模板边界） |
| 布局稳定性 | 高（自动引擎） | 低（AI 坐标易错） | 高（模板固定） |
| 节点上限 | 无硬限 | ~12 节点 | 取决于模板 |
| 品牌定制 | 弱 | 强 | 强 |
| 外部依赖 | 需 Node.js | 无 | 无（纯 HTML/SVG） |
diagram-design 的核心牺牲是图表类型的扩展灵活性——你只能在 29 种既有类型里选，碰到极其特殊的表达需求，你得自己改模板或接受语义映射的近似表达。
可访问性设计：一个常被忽略的加分项
项目对无障碍访问的处理相当规范：每个内联 SVG 都有role="img"、aria-labelledby以及<title>+<desc>插槽，ID 按图表和变体加前缀以避免同页多图冲突。装饰性图标对辅助技术隐藏。这不是营销语言——这在大多数 Mermaid/AI 生成图中根本看不到。
交叉验证
信源一：ClassMethod 工程师独立评测（dev.classmethod.jp，2026-07-11）
这篇文章从独立角度评估了 Claude Code 中手写 SVG vs Mermaid CLI vs Excalidraw 三种路线，与 diagram-design 的设计判断高度吻合：
- 认同：SVG 视觉质量确实优于 Mermaid，Mermaid 的布局稳定性确实更强——这与 diagram-design 选择固定模板而非裸写 SVG 坐标的原因一致。
- 补充：手写 SVG 超过 12 节点时 AI 容易出坐标错误，印证了模板化策略的合理性。
- 关键洞察一致：「AI 写代码的成本不重要，决策标准是输出质量」——这和 diagram-design 放弃 Mermaid、转向更高质量模板的逻辑完全吻合。
信源二：AI Product Hub 产品评测（aiproducthub.cn，2026-08-11）
这是中文媒体的独立评测，记录了该项目进入 GitHub Trending 总榜的时间节点，并验证了核心功能描述与原文一致。评测特别指出 GitHub 单日 +1,612 Star 的传播数据，侧面佐证了这个工具解决的是开发者中普遍存在的痛点，而非小众需求。
边界与局限——不能无条件称赞的地方
29 种类型是硬上限：语义模式虽然能做近似映射，但非常规图表（比如自定义甘特图变体、复杂网络拓扑）只能妥协。没有 Mermaid 那种"自由写 DSL"的开放性。
模板质量参差不平：目前项目是个人维护，29 种类型中复杂度较高的（如 DP security matrix、IT current-state）的模板成熟度不如 architecture / flowchart 这类核心类型，尚缺独立的用户生产环境反馈。
品牌 onboarding 依赖网站可抓取性：如果你的网站有反爬、字体是私有文件、或者颜色通过 JS 动态注入，自动提取可能失败或精度不足，需要手动覆盖。
Claude Code / Codex 专属：虽然技能文件本身是通用的 Agent Skills 格式，但安装流程假设你在用 Claude Code 或 Codex 生态，纯 API 或其他 Agent 框架需要手动改造。
组织级部署有门槛：Claude Cowork 组织级部署要求镜像到私有/内部仓库，自动同步只在 PR 合并时触发，直接 push 不行——这个细节容易踩坑。
个人启发：对不同读者的行动建议
对技术文档写作者/开发者博主：这个工具最直接的价值——如果你在用 Claude Code，现在就可以装上并跑 onboarding，成本是 60 秒。它消灭的是那种"临时想加一张架构图但不想打开 Figma"的摩擦感，这个摩擦感是真实的，它导致很多文章最终没有图。
对工程团队：组织级部署路径确实存在，但要评估私有镜像维护成本。如果团队已经在标准化技术文档流程，这个工具可以作为"图表规范"的执行工具——style-guide.md充当品牌 token 约束，防止不同人产出风格各异的架构图。
对工具链决策者：不要把它和 draw.io 或 Lucidchart 放在同一竞争维度。它解决的是"AI 辅助写作流中的图表"问题，而不是"专业图表设计"问题。如果你的场景是精密的系统设计评审图，draw.io 仍然更合适。
延伸思考
「模板约束 + AI 填充」是不是 AI 辅助内容生成的普适最优解？这个项目实质上是用人工预设的高质量约束来弥补 AI 在空间/视觉推理上的局限。这个策略在多大范围内适用？文本排版？PPT 生成？数据可视化？还是说随着多模态模型视觉能力提升，未来 AI 终究可以直接做精确坐标布局，届时模板层会变得冗余？
style-guide.md作为"品牌 token 单一真相源"的模式，能否被推广到更大的 AI 辅助创作工作流？比如 AI 写代码时也从一份类似文件读取命名规范、注释风格、技术选型约束——一个文件统管所有下游 Agent 的输出风格，这背后是"约束文件即配置"的架构思想，值得更广泛的探讨。开源个人项目如何可持续维护 29 种模板的质量？单人维护、多类型、频繁版本迭代（2.0 → 2.3 已出现在 README 中），社区贡献机制是否健全？对于打算在生产环境依赖此工具的团队，应该如何评估维护风险并制定退出策略（editable install 正是为此设计的）？
📚 参考来源
- GitHub - cathrynlavery/diagram-design: 29 editorial diagram types for Claude Code. Self-contained HTML + SVG. No shadows, no Mermaid-slop. · GitHub