DESIGN.md 设计规范
用结构化令牌和设计说明，让编码代理持续理解视觉系统。
工具的已述权限范围较窄：读取指定文件或标准输入并向标准输出生成报告或导出内容，没有后台代理、凭据访问或隐蔽网络传输，因此最小权限和数据流透明度证据充分。命令均由用户显式调用，导出重定向也由用户控制，但没有专门的确认机制。README清楚披露npm安装和公共注册表访问，却未系统说明运行时外部效果。diff可发现回归，但没有自动恢复或撤销功能。未讨论敏感数据处理。依赖安全证据较弱：Bun版本固定且CI执行测试，但若干开发依赖使用latest、GitHub Actions仅按主版本标签引用，材料中也没有审计或漏洞处置政策。Apache许可证、包名和Google LLC版权头提供来源线索，但发布者身份未获企业注册表验证，且没有明确个人维护者。
README中的格式、规则、命令、输出和退出码相互一致，package.json与CI也支持其CLI、构建和测试叙述，故自洽性充分。依赖可用性通过固定Bun版本、npm公共注册表安装、tarball与Windows安装冒烟流程获得支持，并提供ENOVERSIONS排查；但latest依赖、外部注册表及未展示锁文件降低了保障。错误、警告、信息级别及主要退出码有清楚说明，但没有完整列出解析失败、文件损坏或所有安装失败情形下的消息。
材料明确面向需要持久设计系统上下文的编码代理，并覆盖校验、差异比较、导出和提示注入等场景。规范区分规范性token与解释性文本，列出合法类型、组件属性、未知内容行为和命令边界。CLI触发完全显式，参数、标准输入和格式选择明确。Windows别名、PowerShell问题、Node/npm安装、Bun开发环境、Tailwind v3/v4和DTCG导出均有具体适配说明，因此本维度证据较强。
README层次清楚，包含格式、模式、规则、API、安装和命令参考；安装说明及跨平台故障排查尤其完整。示例覆盖输入、JSON输出、diff、export和程序化API，但没有独立FAQ，部分异常案例仍未覆盖。命名总体稳定并提供designmd及tailwind兼容别名，但格式仍为alpha并明确可能变化。已清楚披露Windows限制、注册表问题、alpha状态和漏洞奖励计划不适用。完整Apache-2.0许可证值得满分。版本管理仅有alpha状态，没有发布历史或变更日志；维护责任只可从Google LLC版权头和包作用域推断，没有明确维护者、支持渠道或更新承诺。
结构化JSON findings、稳定路径、严重级别、摘要、diff回归标志及多种导出格式可直接供代理和CI使用，输出可用性证据充分。将精确token与设计理由放在同一文件，并提供校验、对比和互操作导出，相对非结构化设计说明有明确增量价值。使用成本较低且可通过npx直接运行，但材料没有性能、资源消耗、规模上限或与替代方案的量化比较，因此成本收益未给满分。
主要能力声明可追溯到具体模式表、规则表、命令、参数、退出码和示例；package.json及CI从独立文件侧面印证了工作区、构建、测试、Node导入和npm安装路径。交叉佐证仍有限，因为未提供实现源码、完整规范、测试文件或测试结果。材料通常将规范要求与示例分开，但“代理将产生特定UI”的效果陈述属于未经执行支持的推断，README中的冒烟流程也只是配置证据而非本次独立运行结果。
- 该格式和CLI仍处于alpha阶段；在生产工作流中固定具体包版本，并在升级前使用diff检查模式与输出变化。
- 不要把DESIGN.md当作敏感信息隔离机制；材料未说明秘密、客户数据或其他敏感内容的处理与保留政策。
- npm安装和npx运行依赖公共注册表及其供应链；当前材料未展示锁定策略、依赖审计或漏洞响应流程。
- CI工作流和示例证明项目设计了测试路径，但本次静态审查没有执行命令，也没有验证发布包、测试结果或生成内容的正确性。
- 发布者身份未经FollowAgents企业注册表验证，且材料未提供明确维护者或支持升级渠道。
这个 Agent 能做什么，适合哪些场景？
DESIGN.md 是面向编码代理的视觉身份描述格式，而不是一个独立运行的 AI 代理。文件以 YAML 前置区保存颜色、字体、圆角、间距和组件令牌，并用 Markdown 章节解释设计依据与应用方式。仓库提供 @google/design.md CLI，可执行 lint、diff、export 和 spec 命令，默认以 JSON 输出机器可处理的结果。lint 会检查断裂引用、WCAG 对比度、孤立令牌、章节顺序等问题；diff 用于识别令牌变化和检查结果回退。export 可生成 Tailwind v3 JSON、Tailwind v4 CSS 或 W3C DTCG 格式，程序也可通过 @google/design.md/linter 调用 lint(markdownString)。它适合需要把设计系统作为版本化文件交给不同编码工作流的团队，但当前格式仍处于 alpha，采用者应预留规范变更和迁移成本。
工具读取本地 DESIGN.md 文件或从标准输入接收内容，解析顶部 YAML 令牌和按规定顺序组织的 Markdown 章节。lint 运行十一条规则，并生成包含 findings、summary 和已解析 designSystem 的报告；存在错误时退出码为 1。diff 比较两个 DESIGN.md 文件，列出 colors、typography、rounded、spacing 和 components 中新增、删除或修改的令牌，并在警告或错误增加时标记回退。export 将令牌输出为 json-tailwind、css-tailwind、tailwind 或 dtcg；spec 输出格式规范及可选的活动规则表。TypeScript 使用者还可以从 @google/design.md/linter 导入 lint，直接处理 Markdown 字符串。
- 设计系统团队需要把精确令牌与颜色、排版和交互原则保存在同一个可版本控制文件中。
- 前端团队在持续集成中检查 DESIGN.md 的断裂引用、结构错误和组件文字对比度。
- 代码审查者需要比较设计系统的两个版本，确认令牌变化是否引入更多错误或警告。
- Tailwind 项目维护者希望从同一份 DESIGN.md 生成 Tailwind v3 的
theme.extendJSON 或 Tailwind v4 的@themeCSS。 - 采用 W3C Design Tokens Format Module 的团队需要把 DESIGN.md 令牌导出为 DTCG
tokens.json。 - 构建自定义设计工具的 TypeScript 开发者希望通过
lint(markdownString)获取结构化检查报告。
这个 Agent 有哪些优点和局限？
- 在单一 Markdown 文件中结合机器可读令牌和人类可读设计依据，让精确值与使用语境保持在一起。
- CLI 默认输出结构化 JSON，并以退出码表示 lint 错误或 diff 回退，便于接入自动化流程。
- 内置十一条明确的检查规则，包括令牌引用解析、WCAG AA 对比度、章节顺序和疑似拼写错误检测。
- 同一来源可以导出 Tailwind v3、Tailwind v4 和 W3C DTCG 格式，也提供 TypeScript linter API。
- 对未知章节和合法的自定义令牌名称采取保留或接受策略，为扩展内容留出空间。
- 格式当前为 alpha，规范、令牌模式和 CLI 都在积极开发，升级时可能需要迁移文件或集成。
- 工具依赖 npm/npx 分发；直接使用 npx 或首次安装需要访问公共 npm registry，企业镜像配置可能导致
ENOVERSIONS。 - Windows 上
design.md可执行文件名可能与 Markdown 文件关联冲突，必须改用designmd别名。 - 导出成功不会因源文件中的 lint findings 自动失败；需要另行运行
lint才能用检查结果进行质量门禁。 - 来源没有记录 ChatGPT、Codex、Claude 或任何模型 API 的原生适配，团队仍需自行让编码代理读取和应用该文件。
如何安装或部署这个 Agent？
需要可运行 npm 或 npx 的命令行环境；来源未给出具体 Node.js 版本，也不要求凭据。安装命令：npm install @google/design.md。Windows 终端若会特殊处理 @，可运行 npm install "@google/design.md"。也可不预先安装，直接通过公共 npm registry 运行 npx @google/design.md lint DESIGN.md；此方式需要网络访问。若出现 ENOVERSIONS，用 npm config get registry 检查有效 registry，正常互联网安装应指向 https://registry.npmjs.org/。
如何使用这个 Agent？
先创建含 YAML 前置区和 Markdown 说明的 DESIGN.md。首次验证可运行 npx @google/design.md lint DESIGN.md；也可将内容通过 cat DESIGN.md | npx @google/design.md lint - 输入。比较版本使用 npx @google/design.md diff DESIGN.md DESIGN-v2.md。导出示例：npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json、npx @google/design.md export --format css-tailwind DESIGN.md > theme.css 或 npx @google/design.md export --format dtcg DESIGN.md > tokens.json。Windows/PowerShell 若 .md 命令名与文件关联冲突，应运行 npx -p @google/design.md designmd lint DESIGN.md；package.json 脚本也应使用 designmd 别名。
这个 Agent 与同类方案有什么区别？
与只保存令牌值的交换格式相比，DESIGN.md 还把设计理由放在 Markdown 正文中；同时可导出为 W3C Design Tokens Format Module 的 DTCG JSON。对于 Tailwind，它不是运行时替代品，而是可生成 Tailwind v3 theme.extend JSON或 Tailwind v4 @theme CSS 的上游设计来源。
常见问题
它本身是一个可以执行设计任务的 AI 代理吗？
运行时需要 API 密钥或付费服务吗？
lint 发现问题后如何影响自动化流程？
lint 在发现错误时返回退出码 1，否则返回 0。警告本身不会触发该错误退出码；diff 则在新版本增加错误或警告时返回 1。能否加入规范之外的内容？
导出命令是否会阻止有 lint 问题的文件？
lint。