Design.md：智能体专用设计文件

使用AI编写前端代码最令人沮丧的部分之一是它很快就会忘记你的设计是什么样子。你在提示词中描述你的调色板生成一个按钮组件然后要求创建一个卡片——突然间间距、颜色和字重都完全不同了。问题不在于AI不擅长编写代码。问题在于除非你给它一些结构化的东西来参考否则AI编码代理对你的设计系统没有持久的认知。Google Stitch的design.md文件就是为了解决这个问题而构建的。它在一个AI代理可以读取并持续应用于整个代码库的Markdown文档中捕捉你的整个设计系统——颜色、排版、间距、组件模式。本指南涵盖了design.md文件里面的内容如何从Google Stitch获取它以及如何将其与Claude Code连接起来让你的生成UI从第一个组件到最后一个组件都保持在系统规范内。1、Google Stitch实际做什么Google Stitch是Google实验室推出的AI驱动设计工具使用Gemini从文本描述或上传的参考图像生成UI设计。你描述你想要什么——“一个SaaS分析产品的仪表盘外观干净、简约使用深蓝色和白色调色板”——Stitch就会生成界面、组件和支持它们的完整设计系统。Stitch与简单的模型生成器的区别在于它的输出格式。除了视觉设计之外Stitch还生成一个design.md文件一个纯文本文档以结构化、机器可读的格式捕捉所有设计决策。这不是偶然的。design.md格式是专门为被AI编码代理消费而设计的。想法是你将这个文件交给任何编写代码的代理——Claude Code、Cursor、GitHub Copilot Workspace或自定义代理——它就拥有生成与你设计匹配的UI所需的一切而不需要在每个提示词中详细说明规格。为什么Markdown适用于设计系统Markdown是纯文本。任何AI都可以原生读取它不需要特殊的解析。它是可版本控制的易于编辑并且足够紧凑可以在不占用太多空间的情况下放入上下文窗口。设计token传统上存在于JSON文件中或专有工具内部。design.md方法更简单人类和AI都能读取不需要特殊工具并且位于你的项目仓库中与你的代码并排。2、design.md文件里面有什么Google Stitch生成的design.md文件本质上是以优化AI消费的格式编写的规格。一个典型的文件包括颜色系统主要、次要和强调色带有精确的十六进制值中性色和灰度值语义颜色分配成功、错误、警告、信息背景和表面颜色排版字体家族主要和次要字号比例H1-H6标题大小、正文、小字、说明文字系统中使用的字重行高和字间距值间距比例基本单位通常是4px或8px命名间距值——xs、sm、md、lg、xl、2xl——带有像素值布局和网格容器最大宽度列网格规范响应式断点组件常见元素的视觉模式按钮、输入框、卡片、导航交互状态——悬停、激活、禁用、聚焦变体——主要、次要、幽灵、破坏性边框半径和阴影按组件类型划分的圆角值盒子阴影定义和使用上下文一个生成良好的design.md读起来几乎像人类设计师编写的规格。区别在于它是专门为LLM能够可靠地解析和应用而结构化的。3、开始之前你需要什么在设置这个工作流之前请准备好以下内容Google Stitch访问权限— 可通过Google Labs获得。只需要一个Google账户。已安装Claude Code— Anthropic的基于终端的编码代理。通过npm安装npm install -g anthropic-ai/claude-code。一个前端项目— React、Next.js、Vue、纯HTML/CSS — 该工作流适用于任何技术栈。Node.js— Claude Code运行所需。你不需要了解CSS-in-JS或任何特定的组件库。Claude Code可以针对你的项目使用的任何样式方法——Tailwind、CSS Modules、纯CSS、styled-components。4、完整工作流4.1 在Google Stitch中生成你的设计打开Google Stitch并描述你想要构建的UI。请具体说明产品类型“一个项目管理Web应用”视觉风格“干净、简约、专业——深海军蓝和灰白色调色板”你需要的界面或组件“仪表盘、侧边栏、数据表格、设置页面”Stitch将生成UI模型和支持的设计系统。你还可以上传参考图像——现有产品的截图或粗略草图——如果你想让Stitch匹配特定的美学风格。查看输出并迭代。你的design.md质量取决于Stitch设计的开发程度。在导出之前在这里花时间。4.2 导出design.md文件设计定稿后从Google Stitch导出design.md。它将包含所有设计token和系统规范。将其保存到项目目录的根目录为design.md。将其放在根目录可以确保Claude Code无论在哪个子目录工作都能找到它。4.3 创建或更新你的CLAUDE.md文件Claude Code读取项目根目录中名为CLAUDE.md的文件作为持久上下文。这在每次会话开始时加载使其成为告诉Claude Code关于你设计系统的合适位置。在项目根目录创建CLAUDE.md——或更新你已有的——包含类似以下内容# 项目上下文 ## 设计系统 本项目使用定义在项目根目录design.md中的设计系统。 生成或修改任何UI组件时始终参考此文件。 - 仅使用design.md中定义的颜色、字体和间距值。 - 不要发明新值或使用任何框架的默认值。 - 将组件状态悬停、聚焦、激活、禁用与design.md中的模式匹配。 - 遵循design.md中的排版比例和字重分配。 ## 技术栈 - 框架Next.js 14App Router - 样式带自定义配置的Tailwind CSS - 组件自定义组件不使用UI库调整技术栈部分以匹配你的实际项目。关键部分是明确告诉Claude Code参考design.md且不要偏离它。4.4 启动Claude Code会话在项目根目录的终端中运行claude。Claude Code将加载你的CLAUDE.md并在整个会话中携带这些指令。通过询问验证它是否正在读取设计系统这个项目的design.md中定义的主色是什么它应该返回你的design.md中的确切十六进制值而不是猜测。4.5 生成组件现在用plain language构建UI组件请求“使用design.md中的设计系统构建一个主要按钮组件。”“创建一个定价卡片组件遵循项目设计系统中定义的间距和排版。”“添加一个顶部导航栏使用design.md中指定的颜色和字体。”因为CLAUDE.md指向design.mdClaude Code每次都会引用该文件而不是发明值。4.6 审查和纠正生成每个组件后根据你的Stitch设计进行检查颜色值完全匹配浏览器DevTools颜色选择器有帮助字体大小和字重正确间距遵循design.md中的比例交互状态已实现如果有什么不对直接纠正“按钮背景与design.md中的主色不匹配。使用该文件中确切的十六进制值修复它。”5、获得一致结果的技巧5.1 在主要提示词中提及设计系统即使加载了CLAUDE.md在新组件的提示词中明确引用设计系统也有帮助。使用design.md中的设计系统构建一个用户资料卡片组件。这能让模型的注意力锚定在规格上。5.2 将design.md翻译到你的CSS框架配置中如果你使用Tailwind将你的design.md值翻译成tailwind.config.js。这创建了第二个强制执行层——即使提示词稍有偏离Tailwind的工具类也会将输出限制在你实际的token值上。让Claude Code一次性完成“读取design.md并生成一个tailwind.config.js将所有颜色、间距和排版值映射到自定义Tailwind token。”这个一次性步骤在之后生成的每个组件上都有回报。5.3 运行定期一致性审计构建一批组件后让Claude Code检查偏差“审查/components中的组件找出任何使用design.md中未定义的颜色、间距或排版值的组件。”这在问题积累成更大问题之前发现不一致。5.4 将design.md提交到版本控制像对待源代码一样对待design.md。将其提交到你的仓库这样团队中的每个人都从相同的设计上下文工作。当设计演变时更新文件并提交更改。6、应避免常见错误未将design.md提交到仓库如果文件只存在于你的本地机器上其他开发者和未来会话将没有它。它必须是代码库的一部分。技术栈变化时忘记更新CLAUDE.md如果你添加了新库、切换了样式方法或引入了组件框架请更新CLAUDE.md以反映它。Claude Code的行为取决于该文件所说的内容。假设Claude Code总会遵循设计系统而没有偏差它是一致的但不是万无一失的。根据Stitch设计审查生成的组件可以及早发现偶尔的错误。在导出前让Stitch设计保持模糊如果你在完全开发Stitch设计之前导出design.md文件会有空白——占位符颜色、默认间距、缺失的组件状态。Claude Code只能用它有的内容工作。在导出之前彻底完善设计。指向design.md而不说明如何使用它该文件提供上下文而不是行为。你的CLAUDE.md应该告诉Claude Code如何使用design.md——而不仅仅是它存在。要明确“始终使用这些值永远不要偏离。”7、常见问题7.1 什么是Google Stitch的design.md文件design.md文件是Google Stitch在其UI设计旁边生成的结构化Markdown文档。它以AI编码代理可以读取和应用编写代码的格式记录完整的设计系统——颜色、排版、间距、组件、视觉模式。它充当机器可读的设计规格。7.2 我可以将design.md文件与Claude Code以外的AI编码工具一起使用吗可以。因为design.md是纯Markdown任何接受文件上下文的AI编码工具都可以使用它。Cursor、Aider、GitHub Copilot Workspace以及使用LangChain或CrewAI构建的自定义代理都可以引用该文件。CLAUDE.md机制是Claude Code特有的但将AI编码代理指向设计系统文件的模式适用于任何LLM支持的工具。7.3 如果我已有设计系统Google Stitch还能工作吗Google Stitch主要用于从零开始生成新UI。如果你现有的设计系统在Figma或其他工具中你有两个选择将参考截图导入Stitch并让它推导匹配的设计系统或手动编写记录你现有token的design.md。目前没有直接的Figma到design.md导出路径尽管社区已开始朝这个方向构建工具。7.4 当设计演变时我如何保持design.md的最新返回Google Stitch更新设计然后重新导出design.md文件。替换项目中的旧文件并提交更新。Claude Code在每次会话开始时都会重新读取文件因此它会自动使用新值。对于连接到此文件的MindStudio工作流更新工作流的源引用以指向新版本。7.5 这个工作流适用于React Native或移动开发吗概念可以转移但需要一些调整。Claude Code可以使用design.md文件中的设计token生成React Native组件。然而Google Stitch专注于Web UI因此生成的规格将是面向Web的——你可能需要在使用它进行移动开发之前手动添加移动特定模式安全区域处理、平台导航约定、触摸目标大小。7.6 如果Claude Code一直忽略design.md的部分内容我该怎么办这通常可以追溯到模糊的CLAUDE.md指令或过于笼统的组件提示词。加强指令永远不要使用design.md中未明确定义的任何颜色、间距或字体值。在组件提示词中直接命名文件遵循design.md中的确切规格构建一个次要按钮变体。运行构建后审计也有助于识别偏差发生的位置以便你可以收紧指令。8、结束语Google Stitch的design.md文件以机器可读的格式捕捉你的完整设计系统无需在每个AI提示词中重新描述设计规格。Claude Code的CLAUDE.md功能让你在项目级别嵌入持久的设计指令因此每次会话都以加载的设计系统开始。工作流是在Stitch中生成 → 导出design.md → 添加到项目 → 配置CLAUDE.md → 使用Claude Code生成组件。将design.md token翻译成你的CSS框架配置Tailwind、CSS Modules创建第二个一致性层捕捉任何提示词级别的偏差。这是目前可用于维护AI生成UI视觉一致性的最实用方法之一。从一种组件类型开始——按钮是一个好的测试用例——确认一致性保持然后将其应用于你的完整组件库。原文链接Design.md智能体专用设计文件 - 汇智网