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 14（App 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.md，Claude 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视觉一致性的最实用方法之一。从一种组件类型开始——按钮是一个好的测试用例——确认一致性保持，然后将其应用于你的完整组件库。

原文链接: How to Use Google Stitch's Design.md File with Claude Code for Consistent UI

汇智网翻译整理，转载请标明出处