TokenToSea提示词广场
English 控制台

面向 AI 的设计交接文档

编程开发·任务模板

在聊天中使用

生成供 AI 编码代理直接实现的设计交接文档，所有值和状态都明确定义。

填写变量

填写后，下方提示词与复制内容会同步替换。

# Design Handoff Notes — AI-First, Human-Readable

### 一份结构化交接文档，专为 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）阅读，其次是人类开发者。

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

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

## 项目上下文
- **项目：** {{project_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 代理没有视觉上下文。

---

## 文档结构

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

### 第 1 部分：实现地图

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

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

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

---

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

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

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

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

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

#### 2.2 过渡默认值
```
TRANSITIONS {
慢速：duration-300 ease-in-out
弹簧：duration-500 cubic-bezier(0.34, 1.56, 0.64, 1)
无：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}
├── 部分：Hero
│   ├── 组件：标题 (h1)
│   ├── 组件：副标题 (p)
│   ├── 组件：CTA 按钮 (primary, lg)
│   └── 组件：HeroImage
├── 部分：Features
│   ├── 组件：SectionHeading (h2)
│   └── 组件：FeatureCard × 3 (grid)
├── 部分：Testimonials
│   └── 组件：TestimonialSlider
└── 部分：CTA
    ├── 组件：标题 (h2)
    └── 组件：CTA 按钮 (primary, lg)
```

##### 逐部分规范

为每个部分提供：

**${section_name}**

```
布局 {
  container:    max-w-[1280px] mx-auto px-6 (移动端: px-4)
  direction:    flex-col (移动端) → flex-row (桌面端)
  gap:          gap-8 (32px)
  padding:      py-16 (64px) (移动端: py-10)
  background:   bg-white
}

内容 {
  heading {
    text:       "${exact_heading_text_or_content_source}"
    element:    h2
    class:      text-3xl font-bold text-gray-900 (移动端: text-2xl)
    max-width:  max-w-[640px]
  }
  body {
    text:       "${exact_body_text_or_content_source}"
    class:      text-lg text-gray-600 leading-relaxed (移动端: text-base)
    max-width:  max-w-[540px]
  }
}

网格（如适用） {
  columns:      grid-cols-3 (平板: grid-cols-2) (移动端: grid-cols-1)
  gap:          gap-6 (24px)
  items:        ${what_component_renders_in_each_cell}
  alignment:    items-start
}

动画（如适用） {
  type:         fade-up on scroll
  trigger:      当部分进入视口时触发（阈值: 0.2）
  stagger:      每个子元素在前一个之后延迟 100ms
  duration:     duration-500
  easing:       ease-out
  runs:         一次（在向上滚动时不重新触发）
}
```

---

### 第 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                              // 点击处理程序
}
```

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

```
变体：primary
  尺寸：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

  尺寸：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

  尺寸：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

变体：secondary
  [相同结构，不同值]

变体：ghost
  [相同结构，不同值]
```

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

```
状态（适用于所有变体，除非被覆盖）：

  hover {
变换：      无（悬停时不缩放/平移）
阴影：       ${token_or_none}
光标：       指针
过渡：       默认（duration-200 ease-out）
}

激活状态 {
背景：       ${token} — 比默认值加深两级
变换：       scale-[0.98]
过渡：       duration-75
}

焦点可见状态 {
环：         ring-2 ring-offset-2 ring-brand-500
其他：       与默认状态相同
}

禁用状态 {
不透明度：    opacity-50
光标：       不允许
指针事件：   无
所有悬停/激活/焦点状态：不适用
}

加载状态 {
内容：       用旋转器替换子元素（16px，animate-spin）
宽度：       保持与非加载状态相同的宽度（防止布局偏移）
指针事件：   无
不透明度：    opacity-80
}
```

##### 图标行为
```
图标规则 {
位置：       始终在标签文本左侧
大小：       16px（小），16px（中），20px（大）
间距：       gap-1.5（小），gap-2（中），gap-2（大）
颜色：       继承文本颜色（currentColor）
加载时：     图标隐藏，旋转器占据其位置
仅图标：     若无子元素，组件变为正方形（宽度 = 高度）
             添加 aria-label 属性要求
}
```

---

### 第 5 部分：交互流程

为每个用户流程提供逐步实现：

#### 流程：[流程名称，例如“用户注册”]
```
触发：       用户点击页头中的“注册”按钮

步骤 1：     模态框打开
             动画：      淡入（opacity 0→1，duration-200）
             背景：       bg-black/50，点击外部关闭模态框
             焦点：       将焦点锁定在模态框内，自动聚焦第一个输入框
             主体：       滚动锁定（防止背景滚动）

步骤 2：     用户填写表单
             字段：       ${list_exact_fields_with_validation_rules}
             验证：       在失去焦点时（而非变化时 — 减少噪音）
             
             字段：电子邮件 {
               类型：       email
               必填：       true
               验证：       正则表达式模式 + “必须包含 @ 和域名”
               错误：       “这看起来不像电子邮件 — 检查是否有拼写错误”
               成功：       绿色勾号图标出现（淡入，duration-150）
             }
             
             字段：密码 {
               类型：       密码（带显示/隐藏切换）
               必填：       true
               验证：       至少 8 个字符，1 个大写字母，1 个数字
               错误：       显示需求清单，突出未满足项
               强度：       显示强度条（弱/中/强）
             }

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

步骤 4a：    成功
             模态框：     内容过渡到成功消息（交叉淡入，duration-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
```
  ≥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}"
    - 行动号召："${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
  骨架屏规则：骨架屏形状必须与最终内容形状匹配
              （文本为矩形，头像为圆形，卡片为 rounded-lg）
}

错误状态 {
  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 获取令牌值。如果此处引用的令牌不在 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 节（全局规范）。后续页面引用相同的全局规范。

相关推荐

更多