DESIGN.md预览
为编码代理提供 HeroUI 的默认视觉语言与主题规范
HeroUI 提供了一份开箱即用的 DESIGN.md，专为编码代理准备。将它加入你的项目，代理生成的界面就会遵循 HeroUI 的默认主题、语义化 token、组件模式与设计原则。
加入你的项目
将最新文件下载到项目根目录：
curl -fsSL https://heroui.com/react/DESIGN.md -o DESIGN.md或者查看完整的 DESIGN.md，按需复制你的项目所需的部分。
DESIGN.md 并不是一个会被普遍自动发现的指令文件。请在 AGENTS.md、CLAUDE.md 或编辑器规则中引用它，代理才知道要去读取。AGENTS.md 说明如何使用 HeroUI 进行开发，而 DESIGN.md 定义最终结果应有的外观与体感。
接入你的代理
在提示词或项目说明中，告诉编码代理使用根目录下的 DESIGN.md：
Build this interface with HeroUI v3. Follow DESIGN.md for visual decisions and use semantic HeroUI tokens instead of hardcoded values.如需在整个项目中自动生效，请在 AGENTS.md 或等效的说明文件中加入这一行：
Follow [DESIGN.md](./DESIGN.md) for all visual and interaction decisions.包含内容
- HeroUI 默认的浅色与深色配色角色
- 语义化 Tailwind 工具类及其 CSS 变量映射
- 4px 间距节奏与默认圆角比例
- 表面、浮层、表单字段与层级深度指南
- 组件与交互约定
- 让代理生成的 UI 保持一致的实用建议（Do's and Don'ts）
该文档包含用于设计交付与视觉验收的原始主题值，但会要求代理使用 bg-background、text-foreground、bg-surface、border-separator 等语义化工具类来实现。这样同一套 UI 在浅色与深色模式下都能保持正确。
默认主题原则
| 原则 | 代理指引 |
|---|---|
| 语义化颜色 | 使用基于用途的 token，不要硬编码特定模式的颜色 |
| 清晰的层级 | 优先使用内容顺序、间距、排版与表面层级，而非装饰 |
| 有意识的强调 | 每个场景只用一个主操作，accent 仅用于有意义的强调 |
| 无障碍交互 | 保留 HeroUI 的焦点、键盘、校验与禁用行为 |
| 一致的几何形状 | 遵循 4px 间距节奏与统一的圆角比例 |
| 组合式开发 | 从 HeroUI 组件出发，组合其导出的组成部分 |
事实来源
该公开文件描述的是当前开源版本的默认主题，其取值来自 HeroUI 的默认主题变量与 Tailwind token 映射。
如果你自定义了主题，请在修改 CSS 覆盖样式的同时更新本地的 DESIGN.md，让代理拿到与用户所见一致的设计决策。完整的自定义模型请参阅主题定制与颜色。
需要的是自定义设计系统而不是默认主题？HeroUI 主题构建器可以自定义主题并导出对应的 CSS。