设计交付说明：AI优先，人类可读

# 设计交付说明 — AI优先，人类可读

### 结构化的交付文档，为AI实现代理（Claude Code, Cursor, Copilot）优化，同时对人类开发者保持清晰

---

## 关于此提示

**描述：** 生成一份设计交付文档，作为AI编码代理的直接实现指令。与描述设计“应有感觉”的传统交付说明不同，本文档提供机器可解析的规范，零歧义。每个值都是明确的，每个状态都已定义，每个边缘情况都有规则。文档结构使得AI代理可以从上到下阅读并实现，无需提出澄清问题——同时人类开发者也可以自然阅读。

**核心理念：** 如果AI阅读此文档后需要猜测任何内容，则文档失败。

**何时使用：** 设计定稿后，实现开始前。这取代了Figma交付、设计规范PDF以及“就让它看起来像模型图”的对话。

**谁阅读此文档：**
- 主要：AI编码代理（Claude Code, Cursor, Copilot等）
- 次要：审查或调试AI输出的人类开发者
- 第三：你（设计师），在检查实现是否符合意图时

**与CLAUDE.md的关系：** 本文档假设项目根目录中已存在CLAUDE.md设计系统文件。交付说明引用CLAUDE.md中的令牌，但不重新定义它们。如果不存在CLAUDE.md，请先运行设计系统提取提示。

---

## 提示

```
你是一名设计系统工程师，正在编写实现规范。
你的输出将主要由AI编码代理（Claude Code, Cursor）阅读，
其次由人类开发者阅读。

你的写作必须遵循一个绝对规则：
**如果读者需要猜测、推断或假设任何事情，你就失败了。**

每个值都必须是明确的。每个状态都必须被定义。每个边缘情况都必须有规则。没有“酌情”、“大约”或“类似于”。

## 项目背景
- **项目：** ${name}
- **框架：** [Next.js 14+ / React / 等]
- **样式：** [Tailwind 3.x / CSS Modules / 等]
- **组件库：** [shadcn/ui / 自定义 / 等]
- **CLAUDE.md 位置：** [路径 — 或“尚未创建”]
- **设计来源：** [上传的代码 / 实时 URL / 截图]
- **要规范的页面：** [所有 / 特定页面]

## 输出格式规则

在编写任何规范之前，请严格遵循以下格式规则：

1. **值始终是代码就绪的。**
   错误：“中等间距”
   正确：`p-6` (24px)

2. **颜色始终是令牌引用 + 备用十六进制。**
   错误：“品牌蓝”
   正确：`text-brand-500` (#2563EB) — 来自 CLAUDE.md 令牌

3. **尺寸始终使用项目的单位系统。**
   如果是 Tailwind：主要使用 Tailwind 类，px 作为注释
   如果是 CSS：主要使用 rem，px 作为注释
   错误：“在桌面端做得更大”
   正确：`text-lg` (18px) 在 ≥768px，`text-base` (16px) 在此以下

4. **条件语句使用明确的 if/else，从不使用“根据需要”。**
   错误：“酌情显示加载状态”
   正确：“如果数据获取耗时 >300ms，显示骨架屏。如果获取失败，显示错误状态。如果数据返回空数组，显示空状态。”

5. **文件路径是明确的。**
   错误：“创建一个按钮组件”
   正确：“创建 `src/components/ui/Button.tsx`”

6. **每个视觉属性都已声明，从不通过假设继承。**
   即使“显而易见”——也要声明。AI 代理没有视觉上下文。

---

## 文档结构

生成包含以下部分的交接文档：

### 第一部分：实现路线图

一个按优先级排序的表格，列出所有要构建的内容。
AI 代理应按此顺序实现，以正确解决依赖关系。

| 顺序 | 组件/部分 | 文件路径 | 依赖项 | 复杂度 | 备注 |
|-------|------------------|-----------|-------------|-----------|-------|
| 1 | 设计令牌设置 | `tailwind.config.ts` | 无 | 低 | 必须是第一个——所有其他组件都引用这些 |
| 2 | 排版组件 | `src/components/ui/Text.tsx` | 令牌 | 低 | 标题、正文、说明、标签变体 |
| 3 | 按钮 | `src/components/ui/Button.tsx` | 令牌、排版 | 中 | 3 种变体 × 3 种尺寸 × 6 种状态 |
| ... | ... | ... | ... | ... | ... |

规则：
- 任何内容都不能引用表格中靠后的组件
- 复杂度 = 组件有多少种变体 × 状态
- 备注 = 关于实现任何不明显的地方

---

### 第二部分：全局规范

这些适用于所有地方。AI 代理应在构建任何组件之前配置这些。

#### 2.1 断点
定义精确的行为边界：

```
BREAKPOINTS {
  mobile:  0px    — 767px
  tablet:  768px  — 1023px
  desktop: 1024px — 1279px
  wide:    1280px — ∞
}
```

对于每个断点，说明：
- 容器最大宽度和内边距
- 基本字体大小
- 全局间距乘数（如果更改）
- 导航模式（汉堡包 / 水平 / 等）

#### 2.2 过渡默认值
```
TRANSITIONS {
  default:    duration-200 ease-out
  slow:       duration-300 ease-in-out
  spring:     duration-500 cubic-bezier(0.34, 1.56, 0.64, 1)
  none:       duration-0
}

规则：除非本文档另有规定，否则每个交互元素都使用 `default`。
规则：过渡应用于：background-color、color、border-color、opacity、transform、box-shadow。绝不应用于：width、height、padding、margin（这些会导致布局重新计算）。
```

#### 2.3 Z-Index 范围
```
Z-INDEX {
  base:       0
  dropdown:   10
  sticky:     20
  overlay:    30
  modal:      40
  toast:      50
  tooltip:    60
}

规则：绝不允许使用此范围之外的 z-index 值。
```

#### 2.4 焦点样式
```
FOCUS {
  style:      ring-2 ring-offset-2 ring-brand-500
  applies-to: 每个交互元素（按钮、链接、输入框、选择框、复选框）
  visible:    仅在键盘导航时可见（使用 focus-visible，而不是 focus）
}
```

---

### 第 3 节：页面规范

为每个页面提供完整的实现规范。

#### 页面：${page_name}
**路由：**`/exact-route-path`
**布局：**${which_layout_wrapper_to_use}
**数据要求：**[此页面需要哪些数据，从何处获取]

##### 页面结构（从上到下）

```
页面结构：${page_name}
├── 部分：英雄区
│   ├── 组件：标题 (h1)
│   ├── 组件：副标题 (p)
│   ├── 组件：CTA 按钮 (primary, lg)
│   └── 组件：英雄图片
├── 部分：功能区
│   ├── 组件：部分标题 (h2)
│   └── 组件：功能卡片 × 3 (网格)
├── 部分：用户评价
│   └── 组件：用户评价滑块
└── 部分：CTA
    ├── 组件：标题 (h2)
    └── 组件：CTA 按钮 (primary, lg)
```

##### 各部分规范

对于每个部分：

**${section_name}**

```
布局 {
  容器:    max-w-[1280px] mx-auto px-6 (移动端: px-4)
  方向:    flex-col (移动端) → flex-row (桌面端)
  间距:          gap-8 (32px)
  内边距:      py-16 (64px) (移动端: py-10)
  背景:   bg-white
}

内容 {
  标题 {
    文本:       "${exact_heading_text_or_content_source}"
    元素:    h2
    类名:      text-3xl font-bold text-gray-900 (移动端: text-2xl)
    最大宽度:  max-w-[640px]
  }
  正文 {
    文本:       "${exact_body_text_or_content_source}"
    类名:      text-lg text-gray-600 leading-relaxed (移动端: text-base)
    最大宽度:  max-w-[540px]
  }
}

网格 (如果适用) {
  列:      grid-cols-3 (平板: grid-cols-2) (移动端: grid-cols-1)
  间距:          gap-6 (24px)
  项目:        ${what_component_renders_in_each_cell}
  对齐:    items-start
}

动画 (如果适用) {
  类型:         滚动时淡入上滑
  触发器:      当区块进入视口时 (阈值: 0.2)
  交错:      每个子元素比前一个延迟 100ms
  持续时间:     duration-500
  缓动:       ease-out
  运行:         一次 (向上滚动时不重新触发)
}
```

---

### 第 4 节：组件规范

对于每个组件，提供完整的实现契约。

#### 组件: ${componentname}
**文件:** `src/components/${path}/${componentname}.tsx`
**目的:** [一句话 — 此组件的功能]

##### Props 接口
```typescript
interface ${componentname}Props {
  variant: 'primary' | 'secondary' | 'ghost'     // 视觉样式
  size: 'sm' | 'md' | 'lg'                        // 尺寸
  disabled?: boolean                                // 默认值: false
  loading?: boolean                                 // 默认值: false
  icon?: React.ReactNode                           // 可选的前置图标
  children: React.ReactNode                         // 标签内容
  onClick?: () => void                              // 点击事件处理器
}
```

##### 变体 × 尺寸矩阵
为每种组合定义精确值：

```
VARIANT: primary
  SIZE: sm
    height:           h-8 (32px)
    padding:          px-3 (12px)
    font:             text-sm font-medium (14px)
    background:       bg-brand-500 (#2563EB)
    text:             text-white (#FFFFFF)
    border:           none
    border-radius:    rounded-md (6px)
    shadow:           none

  SIZE: md
    height:           h-10 (40px)
    padding:          px-4 (16px)
    font:             text-sm font-medium (14px)
    background:       bg-brand-500 (#2563EB)
    text:             text-white (#FFFFFF)
    border:           none
    border-radius:    rounded-lg (8px)
    shadow:           shadow-sm

  SIZE: lg
    height:           h-12 (48px)
    padding:          px-6 (24px)
    font:             text-base font-semibold (16px)
    background:       bg-brand-500 (#2563EB)
    text:             text-white (#FFFFFF)
    border:           none
    border-radius:    rounded-lg (8px)
    shadow:           shadow-sm

VARIANT: secondary
  [结构相同，值不同]

VARIANT: ghost
  [结构相同，值不同]
```

##### 状态规范
每种状态都必须为每个变体定义：

```
STATES（除非被覆盖，否则适用于所有变体）：

  hover {
    background:     ${token} — 比默认颜色暗一个色阶
    transform:      none (悬停时无缩放/平移)
    shadow:         ${token_or_none}
    cursor:         pointer
    transition:     default (duration-200 ease-out)
  }

  active {
    background:     ${token} — 比默认颜色暗两个色阶
    transform:      scale-[0.98]
    transition:     duration-75
  }

  focus-visible {
    ring:           ring-2 ring-offset-2 ring-brand-500
    all other:      与默认状态相同
  }

  disabled {
    opacity:        opacity-50
    cursor:         not-allowed
    pointer-events: none
    ALL hover/active/focus states: 不适用
  }

  loading {
    content:        用 spinner 替换子元素 (16px, animate-spin)
    width:          保持与非加载状态相同的宽度 (防止布局偏移)
    pointer-events: none
    opacity:        opacity-80
  }
```

##### 图标行为
```
ICON RULES {
  position:       标签文本左侧 (始终)
  size:           16px (sm), 16px (md), 20px (lg)
  gap:            gap-1.5 (sm), gap-2 (md), gap-2 (lg)
  color:          继承文本颜色 (currentColor)
  when loading:   图标隐藏，spinner 占据其位置
  icon-only:      如果没有子元素，组件变为正方形 (width = height)
                  添加 aria-label 属性要求
}
```

---

### 第 5 节：交互流程

对于每个用户流程，提供分步实现：

#### 流程：[流程名称，例如，“用户注册”]
```
TRIGGER:     用户点击头部“注册”按钮

步骤 1： 模态框打开
             动画： 渐入（不透明度 0→1，持续时间 200 毫秒）
             背景： bg-black/50，点击外部关闭模态框
             焦点： 将焦点限制在模态框内，自动聚焦第一个输入框
             主体： 滚动锁定（防止背景滚动）

步骤 2： 用户填写表单
             字段： ${list_exact_fields_with_validation_rules}
             验证： 失去焦点时验证（而不是改变时验证 — 减少干扰）
             
             字段： email {
               类型： email
               必填： true
               验证： 正则表达式模式 + “必须包含 @ 和域名”
               错误： “这看起来不像电子邮件 — 检查是否有拼写错误”
               成功： 绿色对勾图标出现（渐入，持续时间 150 毫秒）
             }
             
             字段： password {
               类型： password（带显示/隐藏切换）
               必填： true
               验证： 最小 8 个字符，1 个大写字母，1 个数字
               错误： 显示要求清单，突出显示未满足的要求
               强度： 显示强度条（弱/中/强）
             }

步骤 3： 用户提交
             按钮： 显示加载状态（参见 Button 组件规范）
             请求： POST /api/auth/signup
             持续时间： 预计 1-3 秒

步骤 4a： 成功
             模态框： 内容过渡到成功消息（交叉淡入，持续时间 200 毫秒）
             消息： “账户已创建！请检查您的电子邮件进行验证。”
             操作： “知道了”按钮关闭模态框
             重定向： 关闭后，重定向到 /dashboard
             提示： 无（模态框即是确认）

步骤 4b：错误 — 邮箱已存在
             字段：邮箱输入框显示错误状态
             消息：“此邮箱已有账户 — 要登录吗？”
             操作：“登录”链接将模态框切换到登录表单
             按钮：返回默认状态（未加载）

步骤 4c：错误 — 网络故障
             显示：模态框顶部显示错误横幅（非浮动提示）
             消息：“我们这边出了点问题。再试一次？”
             操作：“再试一次”按钮重新提交
             按钮：返回默认状态

步骤 4d：错误 — 频率限制
             显示：错误横幅
             消息：“尝试次数过多。请等待 60 秒后重试。”
             按钮：禁用 60 秒，并显示倒计时

```

---

### 第 6 节：响应式行为规则

不要描述变化，请指定确切的规则：

```
响应式规则：

规则 1：导航
  ≥1024px：水平导航，所有项目可见
  <1024px：汉堡图标，从右侧滑入式抽屉
              抽屉宽度：80vw (max-w-[320px])
              动画：translate-x (duration-300 ease-out)
              背景：bg-black/50，点击外部关闭

规则 2：网格部分
  ≥1024px：grid-cols-3
  768-1023px：grid-cols-2（如果项目数为奇数，则最后一个项目占满整行）
  <768px：grid-cols-1

规则 3：英雄部分
  ≥1024px：两列（文本左，图片右）— 55/45 分割
  <1024px：单列（文本上，图片下）
              图片最大高度：400px，object-cover

规则 4：排版缩放
  ≥1024px：h1=text-5xl, h2=text-3xl, h3=text-xl, body=text-base
  <1024px：h1=text-3xl, h2=text-2xl, h3=text-lg, body=text-base

```

规则 5：间距缩放
  ≥1024px： section-padding: py-16, container-padding: px-8
  768-1023px：section-padding: py-12, container-padding: px-6
  <768px：    section-padding: py-10, container-padding: px-4

规则 6：触摸目标
  <1024px：所有交互元素最小点击区域为 44×44px
              如果视觉尺寸 < 44px，使用不可见填充达到 44px

规则 7：图片
  所有图片：使用 next/image 并带有响应式 sizes 属性
  英雄图：    sizes="(max-width: 1024px) 100vw, 50vw"
  网格项：    sizes="(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 33vw"
```

---

### 第 7 节：边缘情况和边界条件

本节旨在解决“那会发生什么……”的问题：

```
边缘情况：

文本溢出 {
  标题：     最多 2 行，然后用 text-ellipsis 截断（添加 title 属性显示完整文本）
  正文：    允许自然换行，不截断
  按钮标签： 仅单行，最多 30 个字符，不截断（设计约束）
  导航项：   单行，移动端超过 16 个字符则截断
  表格单元格：悬停时显示工具提示截断
}

空状态 {
  列表/网格无项目：显示 ${emptystate} 组件
    - 插图： ${describe_or_reference_asset}
    - 标题： "${exact_text}"
    - 正文： "${exact_text}"
    - CTA： "${exact_text}" → ${action}
  
  用户头像缺失：在彩色背景上显示首字母
    - 背景：根据用户名哈希生成（确定性）
    - 首字母：姓氏和名字的首字母，大写
    - 字体：text-sm font-medium text-white
  
  图片加载失败：显示带有图片图标的灰色占位符
    - 背景：bg-gray-100
    - 图标：来自 lucide-react 的 ImageOff，text-gray-400，24px
}

加载状态 {
  页面加载: 全屏骨架屏 (非加载转圈)
  组件加载: 组件级骨架屏，尺寸与最终内容匹配
  按钮操作: 按钮内嵌加载转圈 (参见按钮规范)
  无限列表: 底部显示 3 行骨架屏，同时获取下一页数据
  
  骨架屏样式: bg-gray-200 rounded animate-pulse
  骨架屏规则: 骨架屏形状必须与最终内容形状匹配
                  (文本为矩形，头像为圆形，卡片为圆角矩形)
}

错误状态 {
  API 错误 (500): 显示内联错误横幅，带重试按钮
  网络错误: 顶部显示“您似乎已离线”横幅 (重新连接时自动消失)
  404 内容: 显示自定义 404 组件 (非 Next.js 默认)
  权限拒绝: 重定向到 /login，带返回 URL 参数
  表单验证: 内联字段级验证 (参见流程规范)，绝不使用 alert()
}

数据极端情况 {
  用户名 1 个字符: 正常显示
  用户名 50 个字符: 导航栏截断为 20 个字符，个人资料页显示完整
  价格 $0.00: 显示“免费”
  价格 $999,999.99: 确保布局不中断 (使用格式化数字测试)
  列表有 1 项: 布局与多项相同 (无特殊情况)
  列表有 500 项: 每页 20 项，显示“加载更多”按钮
  日期今天: 显示“今天”而非具体日期
  日期今年: 显示“3 月 13 日”而非“2026 年 3 月 13 日”
  日期其他年份: 显示“2025 年 3 月 13 日”
}
```

---

### 第 8 节：实施验证清单

实施后，AI 代理（或人工开发者）应验证：

```
验证:

□ 每个组件都与变体 × 尺寸矩阵精确匹配
□ 所有状态（悬停、激活、焦点、禁用、加载）都正常工作
□ Tab 键顺序在所有页面上都遵循视觉顺序
□ 焦点可见环在键盘导航时出现，而不是在鼠标点击时出现
□ 所有过渡都使用指定的持续时间和缓动（而不是浏览器默认值）
□ 页面加载期间没有布局偏移（检查 CLS）
□ 骨架状态与最终内容尺寸匹配
□ 处理了第 7 节中的所有边缘情况
□ 移动断点上的触摸目标 ≥ 44×44px
□ 在任何断点都没有水平滚动
□ 所有图像都使用 next/image 并带有正确的 sizes 属性
□ Z-index 值只使用定义的比例
□ 错误状态显示正确（使用网络限流测试）
□ 空状态显示正确（使用空数据测试）
□ 文本截断在边界长度处起作用
□ 暗模式令牌（如果适用）都已映射
```

---

## AI 代理应如何使用此文档

将此指令包含在生成的交接文档顶部，以便实施 AI 知道如何使用它：

```
AI 实施代理指令：

1. 在编写任何代码之前，请完整阅读本文档。
2. 按照第 1 节（实现图）中指定的顺序进行实现。
3. 参考 CLAUDE.md 获取 token 值。如果此处引用的 token
   不在 CLAUDE.md 中，请标记它并使用提供的备用值。
4. 本文档中的每个值都是有意的。不要用“差不多”的值代替。
   `gap-6` 就是 `gap-6`，而不是 `gap-5`。
5. 必须实现每个状态。如果某个组件未指定状态，
   那是规范中的一个空白——请标记它，不要猜测。
6. 在实现每个组件后，运行其状态矩阵并验证所有状态
   都正常工作，然后再转到下一个组件。
7. 遇到歧义时，优先选择更明确的解释。
   如果仍然模棱两可，请添加 TODO 注释：“// HANDOFF-AMBIGUITY: [描述]”
```
```

---

## 自定义说明

**如果您不使用 Tailwind：** 将提示中所有 Tailwind 类引用替换为您系统中的等效项。结构保持不变——只有值格式发生变化。告诉 Claude：“使用 CSS 自定义属性作为主要，px 值作为注释。”

**如果您要交给特定的 AI 工具：** 添加工具特定的说明。例如，对于 Cursor：“生成实现时，以对现有文件的逐步编辑形式，而不是完整的文件重写。” 对于 Claude Code：“将每个组件创建为一个完整的文件，测试它，然后转到下一个。”

**如果 CLAUDE.md 尚不存在：** 告诉提示在交接文档顶部生成一个最小的 token 部分，仅涵盖本次交接所需的 token。它不会是一个完整的设计系统，但可以防止硬编码值。

**对于多页项目：** 每个页面运行一次提示词，但第 1 节（实现地图）和第 2 节（全局规范）仅在首次运行时包含。后续页面引用相同的全局变量。