Diagram Design开源贡献教程从提交PR到通过12道验证门禁【免费下载链接】diagram-design29 editorial diagram types for Claude Code. Self-contained HTML SVG. No shadows, no Mermaid-slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-designDiagram Design 是一个为 Claude Code 设计的开源图表设计技能库内置 27 种编辑级图表类型全部输出为自包含的 HTML SVG 文件。本文是一份面向新手的开源贡献教程带你走完从提交第一个 PR 到通过全部 12 道验证门禁的完整流程让你第一次贡献就能顺利合入 main 分支不再被 CI 红灯卡住。为什么这个项目值得你贡献先认识它Diagram Design 的核心价值在于不需要 Figma不需要花 30 分钟调颜色一条指令就能产出排版考究、符合品牌风格的架构图、流程图、时序图、泳道图等 27 种图表。项目是文档优先架构skills/diagram-design/SKILL.md是技能总索引每种图表类型都有独立的参考文件提取器脚本负责把 draw.io 和 Mermaid 源文件转成结构化中间表示。正因为是文档优先、脚本验证驱动的项目它对贡献者的门槛反而很低文档更新、示例改进、导入路径修复都是受欢迎的贡献方向。你不需要是图形学专家只要愿意认真跑一遍验证脚本就能提交有价值的 PR。贡献前的 3 个准备工作第一步克隆仓库并创建分支首先克隆项目到本地注意不要直接在 main 分支上开发git clone https://gitcode.com/GitHub_Trending/di/diagram-design git checkout -b feat/my-first-contribution第二步先开 issue 再动手项目在 CONTRIBUTING.md 中明确要求任何非平凡的改动新增图表类型、行为变更、导入语法工作都要先创建 issue小的修复和文档改动可以直接提 PR。同时保持一个 PR 只做一件事把新图表类型和文档重写混在一起会拖慢评审。第三步准备 Python 3.10 环境所有开发脚本都依赖 Python 3.10CI 会在 Linux、Windows、macOS 三平台跑 3.11 和 3.12 两个版本。本地开发请保持一致。提交 PR 前的第一道坎同步版本号这是新手最容易踩的坑即使你的 PR 只改文档或 CI 配置也必须同步递增插件版本号。因为每个 PR 都会改变分发的插件包。python3 scripts/bump-plugin-version.py # patch 版本默认 python3 scripts/bump-plugin-version.py --minor # minor 版本 python3 scripts/bump-plugin-version.py --major # major 版本这个辅助脚本会同时更新 Claude 和 Codex 两份插件清单.claude-plugin/plugin.json与.codex-plugin/plugin.json如果两边版本已经不一致它会拒绝运行。如果 main 上先合入了别人的发布记得先 rebase 再重新 bump保证你的版本始终大于新基线。图解 12 道验证门禁每道门在检查什么CI 配置在 .github/workflows/ci.yml本地与 CI 跑的是同一套脚本。下面按执行顺序拆解这 12 道门禁门禁验证脚本检查内容1. 插件包测试scripts/test-plugin-package.py版本 bump 助手与对抗性打包用例2. 插件包同步scripts/verify-plugin-package.py双清单版本同步递增、市场路径合法、技能打包完整3. SVG 无障碍契约scripts/test-lint-a11y.py每个图表的 SVG 是否满足可访问性规范4. 语义模式文档scripts/verify-semantic-motion.py --markdown-only语义模式路由与 SKILL.md 字节上限40,000 字节5. 动画示例结构scripts/verify-semantic-motion.py --example-only动画示例的结构与可访问性6. 动画契约scripts/verify-motion.py --shipped每个发布的动画模板/示例的降级、控制、预算、确定性7. 皮肤一致性scripts/lint-skin.py --all --baseline所有示例的颜色、字体、a11y、资源、脚本合规8. 时序图文档scripts/verify-sequence-oauth.py时序图文档一致性ATL 片段与预算9. draw.io 导入路径scripts/verify-drawio-import.py真实提取器 vs 夹具 文档同步10. Mermaid 导入路径scripts/verify-mermaid-import.py语法、对抗输入、资源上限、文档同步11. 文档与路由同步scripts/verify-docs-sync.py描述钩子、画廊可达性、README 目录树12. 标签几何验证scripts/verify-geometry.py --all标签遮罩永不被后绘制的节点裁剪除此之外还有scripts/test-verify-motion.py、scripts/test-self-check.py、scripts/test-verify-geometry.py等配套自检脚本。完整清单都维护在 CONTRIBUTING.md 的验证门禁表格里。一键跑通全部门禁本地验证命令合集在推送之前把下面这条命令链完整执行一遍CONTRIBUTING.md 提供就能在本地复现 CI 的绝大部分检查python3 scripts/test-plugin-package.py \ python3 scripts/verify-plugin-package.py origin/main \ claude plugin validate . --strict \ python3 scripts/test-lint-a11y.py \ python3 scripts/verify-semantic-motion.py --markdown-only \ python3 scripts/verify-semantic-motion.py --example-only \ python3 scripts/verify-motion.py --shipped \ python3 scripts/lint-skin.py --all --baseline \ python3 scripts/verify-sequence-oauth.py \ python3 scripts/verify-drawio-import.py \ python3 scripts/verify-mermaid-import.py \ python3 scripts/test-verify-motion.py \ python3 scripts/verify-docs-sync.py \ python3 scripts/test-self-check.py \ python3 scripts/verify-geometry.py --all \ python3 scripts/test-verify-geometry.py 小技巧先单独跑你改动相关的脚本全部通过后再跑完整命令链能更快定位问题。例如新增了示例文件就先用python3 scripts/lint-skin.py skills/diagram-design/assets/example-my-type.html单独检查。门禁失败时的 5 个常见场景与修复方法场景一verify-plugin-package.py失败大概率是版本号没有递增。运行 bump 辅助脚本即可如果打包校验失败保持两个市场指向仓库根目录共享技能保持在skills/diagram-design/SKILL.md。场景二lint-skin.py报颜色或字体违规失败信息会明确指出文件、行号和类别color、font-family、a11y、external-asset、pure-black、script。颜色必须来自 style-guide.md 的调色板字体必须在允许列表内且禁止远程资源、CSSimport、事件处理器、srcdoc和多余脚本。场景三verify-*.py不匹配说明提取器的真实行为与夹具或文档不一致。正确做法是修复源头而不是放宽测试来绕过失败。场景四verify-geometry.py报标签被裁剪标签遮罩与后声明的节点重叠导致渲染时节点填充盖住了标签。把标签移到连接线上空闲的线段保持与描边 6–10px 的间距不要靠缩小遮罩蒙混过关。场景五图标资源过期你改了scripts/vendor/icons/或scripts/build-icons.py生成文件变旧了。重新运行python3 scripts/build-icons.py并提交重新生成的文件即可。⚠️ 注意千万不要把文件加进scripts/lint-skin-baseline.txt来逃避检查。这个基线只服务于 2.0 之前的遗留示例而且仍然要接受 a11y 检查。新手最容易忽略的 3 个隐藏门禁SKILL.md 的 40KB 字节上限SKILL.md每次调用技能都会加载进 Agent 上下文必须保持精简。上限由scripts/verify-semantic-motion.py强制执行详见 ADR-0004。接近上限时把细节挪进references/但永远不要删 description 里的路由词汇——那是 Agent 决定是否加载技能的唯一依据。SVG 可访问性契约a11y每个图表的svg都必须满足契约roleimg配合aria-labelledby、title必须是svg的第一个子元素、ID 必须按slug-title/slug-desc前缀命名。契约实现在 lint-skin.py 中由 test-lint-a11y.py 做单元测试。拿不准就直接模仿现有示例。文档与路由必须同步verify-docs-sync.py会检查三件事SKILL.md 的 description 是否覆盖选择表中所有图表类型、画廊 index.html 是否可达每个发布示例、README 目录树引用的文件是否真实存在。新增图表类型时必须同时更新 type-xxx.md 参考文件、SKILL.md 选择表和画廊。设计决策文档贡献前值得一读的 ADR项目把已定的策略沉淀在 docs/adr/ 目录贡献前读一遍能避免踩雷ADR-0001静态输出为默认单一固定控制器ADR-0002语义模式不扩充 27 种类型分类ADR-0003reveal 是唯一允许的自动播放方式ADR-0004SKILL.md 字节上限与触发型描述ADR-0005标签几何通过验证而非人工评审提交与 PR 规范让你的合入更顺畅提交信息遵循 Conventional Commits 规范type(scope): summary例如fix(import): support current Mermaid syntax、docs(onboarding): clarify the URL flow。一个合格的 PR 应该具备✅ 标题清晰描述说明改了什么和为什么改✅ 说明你本地跑过哪些验证门禁✅ 生成文件与源文件保持一致提取器 验证器 参考文档 命令一次改全✅ 基于 main 分支 rebaseCI 全绿结语从第一个 PR 开始Diagram Design 的 12 道验证门禁看似严格实际上每一道都在守护同一个承诺编辑器级的图表质量。对于新手来说这是绝佳的练手项目——文档优先、脚本验证、规范清晰。克隆仓库、创建分支、跑通门禁、提交 PR你的第一个贡献可能只是一份文档修正但它已经让这个开源图表设计项目变得更好。如果遇到问题可以在 issue 里发起讨论涉及安全问题的请走 SECURITY.md 中的私有上报渠道。期待看到你的第一个绿色 PR 【免费下载链接】diagram-design29 editorial diagram types for Claude Code. Self-contained HTML SVG. No shadows, no Mermaid-slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考