DESIGN.md 开源贡献入门Google CLA 签署与 PR 评审完整流程【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.mdDESIGN.md 是一个面向 AI 编码代理coding agent的设计系统Design System格式规范用机器可读的设计令牌描述视觉身份并附带人类可读的设计理由。本文将从零带你走通完整的开源贡献流程——如何签署 Google CLA 贡献者许可协议、如何熟悉 DESIGN.md 仓库结构、如何写好 PR 并通过评审。30 秒速览签署 Google CLA → 阅读 CONTRIBUTING.md 贡献指南 → 本地跑通测试 → 提交 PR → 通过代码评审。认识 DESIGN.md一个值得贡献的设计系统项目DESIGN.md 文件由两层组成YAML front matter承载颜色、字体、圆角、间距、组件等设计令牌Markdown 正文用散文解释这些值为什么存在、如何应用。项目同时提供命令行工具内置 11 条 lint 规则如断链检测、WCAG 对比度检查并支持导出 Tailwind / W3C DTCG 格式。仓库自带 3 个即开即用的设计系统示例写 DESIGN.md 前不妨先读它们示例设计风格文件Atmospheric Glass玻璃拟态天气应用examples/atmospheric-glass/DESIGN.mdPaws Paths宠物出行应用examples/paws-and-paths/DESIGN.mdTotality Festival暗黑沉浸式日食音乐节examples/totality-festival/DESIGN.md第一步签署 Google CLA 贡献者许可协议提交任何贡献之前必须先完成 CLAContributor License Agreement签署详见 CONTRIBUTING.md。为什么需要 CLA你或你的雇主保留贡献内容的版权CLA 只是授予项目方使用与再分发你贡献的许可。这是 Google 开源生态的标准做法。签署三步走访问 Google CLA 官方页面入口链接就在 CONTRIBUTING.md 中登录并查看已签署协议列表——如果你或雇主曾为其他项目签过 Google CLA通常无需重复签署若无记录点击新签协议确认签署人姓名与你的 PR 提交身份一致⚠️新手最常踩的坑CLA 签署人信息必须与你的 commit / PR 账号身份匹配否则自动校验不通过PR 会被卡住无法进入评审。第二步阅读社区准则项目遵循 Google 开源社区行为准则Community Guidelines要点很朴素尊重对事不对人评审代码不攻击个人聚焦一个 PR 解决一个问题透明在 PR 描述中讲清楚解决什么问题、如何验证原文参见 CONTRIBUTING.md。第三步快速熟悉 DESIGN.md 仓库结构项目是Bun Turbo管理的 monorepo目录职责一目了然目录 / 文件职责docs/spec.mdDESIGN.md 格式完整规范由生成器产出PHILOSOPHY.md设计哲学散文prose优先于令牌packages/cli/核心 CLIlint/diff/export/spec四个子命令packages/cli/src/linter/rules/11 条 lint 规则每条规则一个独立文件packages/cli/src/commands/CLI 子命令实现examples/3 个官方设计系统示例turbo.json / tsconfig.base.json构建与 TypeScript 配置新手贡献的 4 个常见入口新增示例在 examples/ 下添加一套设计系统附design_tokens.json与tailwind.config.js新增/修复 lint 规则修改 packages/cli/src/linter/rules/ 并补充同名测试改进文档注意 docs/spec.md 由spec:gen从源码生成改生成器源码而非产物修复 CLI 缺陷修改 packages/cli/src/commands/ 下的实现并附回归测试第四步从克隆到提交第一个 PR先克隆仓库并搭建本地环境git clone https://gitcode.com/GitHub_Trending/de/design.md cd design.md bun install本地验证最快方法在仓库根目录运行对应 package.json 中定义的脚本bun run test # 运行全部测试turbo test bun run lint # 类型检查tsc --noEmit bun run cli # 启动本地 CLI 手动体验✅经验之谈每条 lint 规则都配有同名.test.ts测试文件如 broken-ref.ts 与 broken-ref.test.ts。改规则前先读测试一次通过评审的概率最高。PR 书写最佳实践小而聚焦一个 PR 只做一件事标题清晰一句话描述变更动机与结果附验证证据测试输出、修改前后的 JSON 对比等描述完整问题背景 解决方案 验证方式三段式最稳妥第五步PR 评审关注什么项目的评审立场非常明确所有提交都必须经过代码评审项目成员本人的提交也不例外见 CONTRIBUTING.md。评审时维护者通常关注这些点评审维度关注内容规范符合性令牌字段、章节顺序是否符合 docs/spec.md测试覆盖新规则/新功能是否带对应.test.ts退出码语义lint报错返回 1、diff检出回归返回 1不可随意变更文档同步格式变化是否同步更新了spec:gen生成源兼容性未知内容遵循保留、不报错的消费方行为原则⏳ 提交后请等待评审反馈逐条回应评论、以新 commit 追加修改不要强行合并也不要重复开 PR。常见问题Q我是纯新手从哪里开始最稳A先读 PHILOSOPHY.md 和 README.md然后从新增示例或文档完善类小任务入手风险低、反馈快。Q之前为别的项目签过 Google CLA还需要重签吗A不需要。CLA 与具体项目无关只要签署记录存在即可直接使用。Q可以绕过 PR 直接推送吗A不可以。所有贡献必须走 Pull Request 评审流程。现在就开始贡献✅ 签署 Google CLA约 3 分钟✅ 通读 CONTRIBUTING.md 与社区准则✅ 克隆仓库并跑bun run test确认基线全绿✅ 挑一个小 issue建分支提交你的第一个 PRDESIGN.md 目前处于alpha阶段规范、令牌模式与 CLI 都在积极开发中——一个示例、一条规则或一段文档的改进都是社区真正需要的贡献。【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考