AI Agent设计语言DESIGN.md规范实战指南

AI Agent设计语言：DESIGN.md规范实战指南

用一份 DESIGN.md 定义 Agent 的视觉灵魂，让 AI 界面拥有统一的设计语言

目录

1. 引言：为什么 Agent 需要设计语言？
2. DESIGN.md 项目概览
3. 核心概念：Agent-Agnostic 设计
4. Design Tokens：视觉规范的基础砖石
5. 组件规范：从令牌到 UI 元素
6. 布局系统：让 Agent 界面呼吸
7. 暗色模式与主题切换
8. 动效规范：赋予 Agent 生命力
9. Agent-Agnostic 适配策略
10. 从零搭建 DESIGN.md 实战
11. 最佳实践与常见误区
12. 总结与资源

1. 引言：为什么 Agent 需要设计语言？

2025 年以来，AI Agent 从概念验证走向了生产部署。当你构建一个 Agent 应用时，面临的不仅仅是功能模块的编排——用户与 Agent 交互的每一个瞬间，都在与它的界面沟通。从对话气泡到任务面板，从思考指示器到结果输出卡，这些 UI 元素的视觉一致性直接影响用户对 Agent 的信任感和使用体验。

然而，Agent 开发团队常陷入一个困境：

• 后端工程师关注 Agent 的推理链、工具调用、上下文管理
• 前端工程师关注组件渲染、样式管理、响应式布局
• 设计师关注视觉一致性、品牌传达、交互细节

三者之间缺乏一座桥梁——一份统一的、可执行的、Agent 感知的设计规范文档。

这正是DESIGN.md诞生的背景。

1.1 什么是 DESIGN.md？

DESIGN.md 是一个9.8K+ Stars 的开源项目（GitHub:nousresearch/hermes-agent），它的核心理念极其简洁却强大：

用一份 Markdown 文件，定义 AI Agent 的完整设计系统。

这份文件不仅是给人类设计师和开发者看的文档，更是一个机器可读的规范源——它可以用自动化流水线提取、验证、转换成实际的 CSS 变量、组件代码和设计稿。

1.2 为什么选择 Markdown？

Markdown 拥有无可比拟的优势：

将设计规范以 Markdown 形式直接放在代码仓库中，与源代码同版本、同评审、同发布——这是“文档即代码”（Docs as Code）哲学在 AI Agent 领域的完美实践。

2. DESIGN.md 项目概览

2.1 项目结构

一个典型的 DESIGN.md 项目目录结构如下：

hermes-agent/ ├── DESIGN.md # 主规范文件（核心） ├── tokens/ # Design Tokens 分文件 │ ├── colors.md │ ├── typography.md │ ├── spacing.md │ └── shadows.md ├── components/ # 组件规范 │ ├── button.md │ ├── card.md │ ├── input.md │ └── dialog.md ├── patterns/ # 设计模式 │ ├── loading-states.md │ ├── error-handling.md │ └── empty-states.md ├── assets/ # 静态资源 │ ├── logo.svg │ └── icon-library/ ├── scripts/ # 工具脚本 │ ├── extract-tokens.js │ └── validate-design.js └── dist/ # 构建输出 ├── design-tokens.css └── component-library/

2.2 核心元数据

每一份 DESIGN.md 都在文件头部以 YAML front-matter 声明元数据：

--- title: "Hermes Agent Design System" version: "2.1.0" last_updated: "2026-04-29" status: "active" maintainers: ["@design-team", "@frontend-core"] designed_for: ["chat-agent", "task-agent", "multi-agent"] design_tokens_version: "1.3" components_version: "2.0" tags: ["agent-agnostic", "dark-mode", "glassmorphism"] ---

这种结构化元数据让 CI/CD 可以自动解析和验证规范的一致性。

2.3 设计原则

DESIGN.md 规范遵循五个核心设计原则：

1. Agent-Agnostic：规范独立于底层 Agent 实现（OpenAI / Claude / 本地模型）
2. 渐进增强：从基础的 Design Tokens 逐层构建到复杂组件
3. 机器可读：规范的每一个部分都可以被工具自动化处理
4. 以人为本：最终服务的是人类用户，保持可读性和可理解性
5. 可测试：每条规范都附带验证条件和测试用例

3. 核心概念：Agent-Agnostic 设计

3.1 什么是 Agent-Agnostic？

“Agent-Agnostic” 是 DESIGN.md 最核心的设计哲学。它的含义是：

你的设计规范不绑定任何特定的 Agent 框架、模型提供商或运行时环境。

同一种视觉语言，可以在以下场景无缝复用：

• OpenAI Assistants API
• Anthropic Claude Message API
• 本地运行的 Llama / Qwen 模型
• 多 Agent 协作系统（如 CrewAI、AutoGen）
• 自定义 Agent Runtime

3.2 为什么需要 Agent-Agnostic？

在实际生产中，Agent 技术栈迭代极快。今天你用 OpenAI，明天可能切换到 Claude，后天可能会加入本地模型做 fallback。如果你的设计规范与某个 Agent SDK 深度耦合，每次技术栈切换都意味着界面重构。

┌─────────────────────────────────────────────────────┐ │ DESIGN.md │ │ (统一规范层) │ ├──────────┬──────────┬──────────┬───────────────────┤ │ OpenAI │ Claude │ 本地模型 │ 多 Agent 编排 │ │ Agent │ Agent │ Agent │ 系统 │ └──────────┴──────────┴──────────┴───────────────────┘ ↑ ↑ ↑ ──────┴────────────┴─────────────┴── 同一份规范

3.3 抽象层次设计

DESIGN.md 将设计规范分为三个抽象层次：

第1层: 设计令牌 (Design Tokens) ├── 颜色、字体、间距、阴影、圆角 ├── 完全抽象，无任何 Agent 依赖 └── 可直接编译为 CSS 自定义属性 第2层: 组件规范 (Components) ├── Button、Card、Input、Dialog、Loading ├── 定义视觉行为和状态，而非实现细节 └── 可映射到任意 UI 框架（React/Vue/Svelte） 第3层: Agent 模式 (Agent Patterns) ├── 思考指示器、工具调用卡片、结果展示 ├── 定义 Agent 特有的交互模式 └── 通过组合第2层组件实现，不绑定 Agent API

这种分层设计确保了底层变化不影响上层规范——当 Agent 提供商变更时，你只需要更新第3层的模式映射，而不需要重写整个设计系统。

4. Design Tokens：视觉规范的基础砖石

Design Tokens 是设计系统中最细粒度的视觉原子。它们定义了**“这条边距应该是多少”、“这个颜色应该是什么”**这类最基础的问题。

4.1 颜色系统

语义化颜色命名

## Colors ### Primary Brand Colors | Token | Value | Usage | |-------|-------|-------| | --color-primary | #6366F1 | 主要品牌色，CTA 按钮，链接 | | --color-primary-hover | #4F46E5 | 主要交互悬停状态 | | --color-primary-active | #4338CA | 主要交互激活状态 | | --color-primary-subtle | rgba(99,102,241,0.1) | 主要色弱化背景 | ### Semantic Colors | Token | Value | Usage | |-------|-------|-------| | --color-success | #10B981 | 成功状态、完成提示 | | --color-warning | #F59E0B | 警告状态、注意提示 | | --color-error | #EF4444 | 错误状态、失败提示 | | --color-info | #3B82F6 | 信息提示、帮助文本 | ### Neutral Colors | Token | Light | Dark | Usage | |-------|-------|------|-------| | --color-surface | #FFFFFF | #1E1E2E | 主表面背景 | | --color-surface-elevated | #F9FAFB | #2A2A3E | 升高的卡片背景 | | --color-border | #E5E7EB | #3A3A4E | 边框和分割线 | | --color-text-primary | #111827 | #F3F4F6 | 主要文本 | | --color-text-secondary | #6B7280 | #9CA3AF | 次要文本 | | --color-text-disabled | #D1D5DB | #4B5563 | 禁用状态文本 |

最佳实践

# ✅ 正确：语义化命名--color-primary--color-success# ❌ 错误：直接描述值--color-purple-600--color-green-500

语义化命名的优势在于，当你替换品牌色时，只需要修改 token 的值，所有引用--color-primary的地方自动更新。

4.2 间距系统

使用4px 网格基准（Pixel Perfect 原则），所有间距都是 4 的倍数：

## Spacing Scale | Token | Value | Example Usage | |-------|-------|--------------| | --spacing-1 | 4px | 图标与文字间距 | | --spacing-2 | 8px | 标签内部间距 | | --spacing-3 | 12px | 按钮内部间距 | | --spacing-4 | 16px | 卡片内边距 | | --spacing-5 | 20px | 组件间间距 | | --spacing-6 | 24px | 段落间距 | | --spacing-8 | 32px | 区块间距 | | --spacing-10 | 40px | 大区块间距 | | --spacing-12 | 48px | 页面级间距 | | --spacing-16 | 64px | 极限间距 |

4.3 字体与排版

## Typography ### Font Family - --font-body: 'Inter', 'PingFang SC', 'Microsoft YaHei', sans-serif - --font-heading: 'Inter', 'PingFang SC', 'Microsoft YaHei', sans-serif - --font-mono: 'JetBrains Mono', 'Fira Code', monospace ### Font Sizes | Token | Value | Line Height | Usage | |-------|-------|-------------|-------| | --text-xs | 12px | 16px | 标注、辅助文本 | | --text-sm | 14px | 20px | 次要信息、元数据 | | --text-base | 16px | 24px | 正文、对话内容 | | --text-lg | 18px | 28px | 小标题 | | --text-xl | 20px | 28px | 中等标题 | | --text-2xl | 24px | 32px | 大标题 | | --text-3xl | 30px | 36px | 页面标题 | | --text-4xl | 36px | 40px | 特大标题 | ### Font Weights - --font-normal: 400 - --font-medium: 500 - --font-semibold: 600 - --font-bold: 700

4.4 阴影与层级

Agent UI 中，阴影用于表达深度和 z-index 层级：

## Shadows & Elevation | Token | Value | Elevation | Usage | |-------|-------|-----------|-------| | --shadow-sm | 0 1px 2px rgba(0,0,0,0.05) | 1 | 普通卡片 | | --shadow-md | 0 4px 6px rgba(0,0,0,0.07) | 2 | 弹出菜单 | | --shadow-lg | 0 10px 15px rgba(0,0,0,0.1) | 3 | 模态对话框 | | --shadow-xl | 0 20px 25px rgba(0,0,0,0.15) | 4 | 通知 Toast | | --shadow-glow | 0 0 20px rgba(99,102,241,0.3) | 5 | Agent 思考指示器 |

4.5 圆角边界

## Border Radius | Token | Value | Usage | |-------|-------|-------| | --radius-sm | 4px | 输入框、标签 | | --radius-md | 8px | 按钮、卡片 | | --radius-lg | 12px | 对话框、面板 | | --radius-xl | 16px | 大卡片 | | --radius-full | 9999px | 头像、药丸形标签 |

5. 组件规范：从令牌到 UI 元素

有了 Design Tokens 作为基础，接下来定义 Agent UI 中的具体组件。

5.1 Button 按钮规范

## Component: Button ### Variants | Variant | Background | Text | Border | Hover | |---------|-----------|------|--------|-------| | primary | --color-primary | #FFFFFF | none | --color-primary-hover | | secondary | transparent | --color-primary | 1px solid --color-primary | bg: rgba(99,102,241,0.05) | | ghost | transparent | --color-text-secondary | none | bg: rgba(0,0,0,0.05) | | danger | --color-error | #FFFFFF | none | filter: brightness(0.9) | ### Sizes | Size | Padding | Font Size | Icon Size | |------|---------|-----------|-----------| | sm | 6px 12px | --text-sm | 14px | | md | 8px 16px | --text-base | 16px | | lg | 12px 24px | --text-lg | 18px | ### States - **Default**: 标准显示 - **Hover**: 背景色加深，可能伴随轻微上移（2px） - **Active/Pressed**: 背景色进一步加深，transform: scale(0.98) - **Focus**: 2px 轮廓环，颜色 --color-primary - **Disabled**: opacity 0.5, cursor not-allowed - **Loading**: 显示旋转指示器，禁用交互 ### Animation - 过渡: all 150ms ease-out - Hover 上移: transform 200ms cubic-bezier(0.34, 1.56, 0.64, 1)

代码示例：CSS 实现

/* 从 DESIGN.md 生成的 Button 样式 */.btn{display:inline-flex;align-items:center;justify-content:center;gap:var(--spacing-2);border:none;border-radius:var(--radius-md);font-family:var(--font-body);font-weight:var(--font-medium);cursor:pointer;transition:all 150ms ease-out;user-select:none;white-space:nowrap;}.btn--primary{background:var(--color-primary);color:#ffffff;}.btn--primary:hover{background:var(--color-primary-hover);transform:translateY(-1px);box-shadow: