AI优先设计交接文档生成器

# 设计系统工程师交接规范 ## 项目背景 - **项目：** ${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 断点 定义精确的行为边界： ``` 断点 { 移动端： 0px - 767px 平板： 768px - 1023px 桌面端： 1024px - 1279px 宽屏： 1280px - ∞ } ``` 对于每个断点，说明：容器最大宽度和内边距、基础字体大小、全局间距乘数（如果变化）、导航模式（汉堡菜单 / 水平导航 / 等） #### 2.2 过渡默认值 ``` 过渡 { 默认： 时长-200 缓出 慢速： 时长-300 缓入缓出 弹性： 时长-500 三次贝塞尔(0.34, 1.56, 0.64, 1) 无： 时长-0 } 规则：所有交互元素使用 `默认`，除非本文档另有规定。 规则：过渡应用于：背景色、颜色、边框色、不透明度、变换、盒阴影。绝不应用于：宽度、高度、内边距、外边距（这些会导致布局重算）。 ``` #### 2.3 Z 索引层级 ``` Z 索引 { 基础： 0 下拉菜单： 10 粘性： 20 覆盖层： 30 模态框： 40 提示消息： 50 工具提示： 60 } 规则：任何 z 索引值都不得超出此层级。绝不。 ``` #### 2.4 焦点样式 ``` 焦点 { 样式： 环-2 环偏移-2 环品牌-500 适用范围： 每个交互元素（按钮、链接、输入框、选择框、复选框） 可见性： 仅在键盘导航时显示（使用焦点可见，而非焦点） } ``` ### 第 3 部分：页面规范 对于每个页面，提供完整的实施规范。 #### 页面：${页面名称} **路由：** `/精确路由路径` **布局：** ${使用哪个布局包装器} **数据需求：** [此页面需要哪些数据，来自何处] ##### 页面结构（从上到下） ``` 页面结构：${页面名称} ├── 部分：英雄区 │ ├── 组件：标题 (h1) │ ├── 组件：副标题 (p) │ ├── 组件：行动号召按钮 (主要，大) │ └── 组件：英雄图片 ├── 部分：功能特性 │ ├── 组件：部分标题 (h2) │ └── 组件：功能卡片 × 3 (网格) ├── 部分：客户评价 │ └── 组件：评价轮播 └── 部分：行动号召 ├── 组件：标题 (h2) └── 组件：行动号召按钮 (主要，大) ``` ##### 逐部分规范 对于每个部分： **${部分名称}** ``` 布局 { 容器： 最大宽度-[1280px] 外边距自动 内边距-x-6 (移动端：内边距-x-4) 方向： 弹性列 (移动端) → 弹性行 (桌面端) 间距： 间距-8 (32px) 内边距： 内边距-y-16 (64px) (移动端：内边距-y-10) 背景： 背景-白色 } 内容 { 标题 { 文本： "${精确标题文本或内容来源}" 元素： h2 类： 文本-3xl 字体粗体 文本-灰色-900 (移动端：文本-2xl) 最大宽度： 最大宽度-[640px] } 正文 { 文本： "${精确正文文本或内容来源}" 类： 文本-lg 文本-灰色-600 行高-宽松 (移动端：文本-base) 最大宽度： 最大宽度-[540px] } } 网格（如适用）{ 列数： 网格列-3 (平板：网格列-2) (移动端：网格列-1) 间距： 间距-6 (24px) 项目： ${每个单元格渲染什么组件} 对齐： 项目-起始 } 动画（如适用）{ 类型： 滚动时淡入上移 触发条件： 当部分进入视口时（阈值：0.2） 交错： 每个子元素在前一个之后延迟 100ms 时长： 时长-500 缓动： 缓出 运行次数： 一次（向上滚动时不重新触发） } ``` ### 第 4 部分：组件规范 对于每个组件，提供完整的实施契约。 #### 组件：${组件名称} **文件：** `src/components/${路径}/${组件名称}.tsx` **用途：** [一句话 - 此组件做什么] ##### Props 接口 ```typescript 接口 ${组件名称}Props { 变体：'主要' | '次要' | '幽灵' // 视觉样式 尺寸：'小' | '中' | '大' // 尺寸 禁用?: 布尔值 // 默认：false 加载中?: 布尔值 // 默认：false 图标?: React.ReactNode // 可选的前导图标 子元素: React.ReactNode // 标签内容 点击?: () => 无效 // 点击处理程序 } ``` ##### 变体 × 尺寸矩阵 为每个组合定义精确值： ``` 变体：主要 尺寸：小 高度： 高度-8 (32px) 内边距： 内边距-x-3 (12px) 字体： 文本-sm 字体中等 (14px) 背景： 背景-品牌-500 (#2563EB) 文本： 文本-白色 (#FFFFFF) 边框： 无 边框半径： 圆角-md (6px) 阴影： 无 尺寸：中 高度： 高度-10 (40px) 内边距： 内边距-x-4 (16px) 字体： 文本-sm 字体中等 (14px) 背景： 背景-品牌-500 (#2563EB) 文本： 文本-白色 (#FFFFFF) 边框： 无 边框半径： 圆角-lg (8px) 阴影： 阴影-sm 尺寸：大 高度： 高度-12 (48px) 内边距： 内边距-x-6 (24px) 字体： 文本-base 字体半粗 (16px) 背景： 背景-品牌-500 (#2563EB) 文本： 文本-白色 (#FFFFFF) 边框： 无 边框半径： 圆角-lg (8px) 阴影： 阴影-sm 变体：次要 [相同结构，不同值] 变体：幽灵 [相同结构，不同值] ``` ##### 状态规范 必须为每个变体定义每个状态： ``` 状态（适用于所有变体，除非有覆盖）： 悬停 { 背景： ${令牌} - 从默认值加深一级 变换： 无（悬停时不缩放/平移） 阴影： ${令牌或无} 光标： 指针 过渡： 默认（时长-200 缓出） } 激活 { 背景： ${令牌} - 从默认值加深两级 变换： 缩放-[0.98] 过渡： 时长-75 } 焦点可见 { 环： 环-2 环偏移-2 环品牌-500 其他所有： 与默认状态相同 } 禁用 { 不透明度： 不透明度-50 光标： 不允许 指针事件： 无 所有悬停/激活/焦点状态：不适用 } 加载中 { 内容： 将子元素替换为旋转器（16px，动画旋转） 宽度： 保持与非加载状态相同的宽度（防止布局偏移） 指针事件： 无 不透明度： 不透明度-80 } ``` ##### 图标行为 ``` 图标规则 { 位置： 标签文本左侧（始终） 尺寸： 16px (小)，16px (中)，20px (大) 间距： 间距-1.5 (小)，间距-2 (中)，间距-2 (大) 颜色： 继承文本颜色（当前颜色） 加载时： 图标隐藏，旋转器占据其位置 仅图标： 如果没有子元素，组件变为正方形（宽度 = 高度） 添加 aria-label 属性要求 } ``` ### 第 5 部分：交互流程 对于每个用户流程，提供逐步实施说明： #### 流程：[流程名称，例如，“用户注册”] ``` 触发条件： 用户点击页眉中的“注册”按钮 步骤 1： 模态框打开 动画： 淡入（不透明度 0→1，时长-200） 背景遮罩： 背景-黑色/50，点击外部关闭模态框 焦点： 将焦点困在模态框内，自动聚焦第一个输入框 正文： 滚动锁定（阻止背景滚动） 步骤 2： 用户填写表单 字段： ${列出精确字段及验证规则} 验证： 在失焦时（而非输入时 - 减少干扰） 字段： 电子邮件 { 类型： 电子邮件 必填： true 验证： 正则模式 + “必须包含 @ 和域名” 错误： “这看起来不像电子邮件 - 请检查拼写错误” 成功： 绿色对勾图标出现（淡入，时长-150） } 字段： 密码 { 类型： 密码（带显示/隐藏切换） 必填： true 验证： 最少 8 个字符，1 个大写字母，1 个数字 错误： 显示要求清单，突出显示未满足项 强度： 显示强度条（弱/中/强） } 步骤 3： 用户提交 按钮： 显示加载状态（参见按钮组件规范） 请求： POST /api/auth/signup 时长： 预期 1-3 秒 步骤 4a： 成功 模态框： 内容过渡到成功消息（交叉淡入，时长-200） 消息： “账户已创建！请检查您的电子邮件以验证。” 操作： “知道了”按钮关闭模态框 重定向： 关闭后，重定向到 /dashboard 提示消息： 无（模态框本身就是确认） 步骤 4b： 错误 - 电子邮件已存在 字段： 电子邮件输入框显示错误状态 消息： “此电子邮件已有账户 - 想改为登录吗？” 操作： “登录”链接将模态框切换为登录表单 按钮： 返回默认状态（非加载中） 步骤 4c： 错误 - 网络故障 显示： 模态框顶部显示错误横幅（非提示消息） 消息： “我们这边出了点问题。要重试吗？” 操作： “重试”按钮重新提交 按钮： 返回默认状态 步骤 4d： 错误 - 速率受限 显示： 错误横幅 消息： “尝试次数过多。请等待 60 秒后重试。” 按钮： 禁用 60 秒，并显示倒计时 ``` ### 第 6 部分：响应式行为规则 不要描述变化内容 - 指定精确规则： ``` 响应式规则： 规则 1：导航 ≥1024px： 水平导航，所有项目可见 <1024px： 汉堡菜单图标，从右侧滑入抽屉 抽屉宽度：80vw（最大宽度-[320px]） 动画：平移-x（时长-300 缓出） 背景遮罩：背景-黑色/50，点击外部关闭 规则 2：网格部分 ≥1024px： 网格列-3 768-1023px： 网格列-2（如果项目数为奇数，最后一项跨全宽） <768px： 网格列-1 规则 3：英雄区 ≥1024px： 两列（文本左，图片右）- 55/45 分割 <1024px： 单列（文本上，图片下） 图片最大高度：400px，对象-覆盖 规则 4：排版缩放 ≥1024px： h1=文本-5xl，h2=文本-3xl，h3=文本-xl，正文=文本-base <1024px： h1=文本-3xl，h2=文本-2xl，h3=文本-lg，正文=文本-base 规则 5：间距缩放 ≥1024px： 部分内边距：内边距-y-16，容器内边距：内边距-x-8 768-1023px： 部分内边距：内边距-y-12，容器内边距：内边距-x-6 <768px： 部分内边距：内边距-y-10，容器内边距：内边距-x-4 规则 6：触摸目标 <1024px： 所有交互元素最小 44×44px 点击区域 如果视觉尺寸 < 44px，使用不可见内边距达到 44px 规则 7：图片 所有图片：使用 next/image 并设置响应式尺寸属性 英雄区： 尺寸="(最大宽度：1024px) 100vw，50vw" 网格项目： 尺寸="(最大宽度：768px) 100vw，(最大宽度：1024px) 50vw，33vw" ``` ### 第 7 部分：边界情况与边界条件 本部分防止“但是当……时会发生什么”的问题： ``` 边界情况： 文本溢出 { 标题： 最多 2 行，然后使用文本省略号截断（添加标题属性以显示完整文本） 正文文本： 允许自然换行，不截断 按钮标签： 单行，最多 30 个字符，不截断（设计约束） 导航项目： 单行，在移动端超过 16 个字符时截断 表格单元格： 截断并在悬停时显示工具提示 } 空状态 { 项目数为 0 的列表/网格：显示 ${空状态} 组件 - 插图：${描述或引用资源} - 标题："${精确文本}" - 正文："${精确文本}" - 行动号召："${精确文本}" → ${操作} 用户头像缺失：显示姓名首字母，带彩色背景 - 背景：根据用户姓名哈希生成（确定性） - 首字母：名字和姓氏的首字母，大写 - 字体：文本-sm 字体中等 文本-白色 图片加载失败：显示灰色占位符，带图片图标 - 背景：背景-灰色-100 - 图标：来自 lucide-react 的 ImageOff，文本-灰色-400，24px } 加载状态 { 页面加载： 全页骨架屏（非旋转器） 组件加载： 与最终尺寸匹配的组件级骨架屏 按钮操作： 按钮内联旋转器（参见按钮规范） 无限列表： 获取下一页时底部显示骨架行 × 3 骨架样式： 背景-灰色-200 圆角 动画-脉冲 骨架规则： 骨架形状必须与最终内容形状匹配 （文本用矩形，头像用圆形，卡片用圆角-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 并设置正确的尺寸属性 ☐ Z 索引值仅使用定义的层级 ☐ 错误状态正确显示（使用网络限速测试） ☐ 空状态正确显示（使用空数据测试） ☐ 文本截断在边界长度下正常工作 ☐ 深色模式令牌（如适用）均已映射 ``` ## AI 代理应如何使用本文档 在生成的交接文档顶部包含此说明，以便实施 AI 知道如何工作： ``` 给 AI 实施代理的说明： 1. 在编写任何代码之前，完整阅读本文档。 2. 按第 1 部分（实施映射）中指定的顺序实施。 3. 参考 CLAUDE.md 获取令牌值。如果此处引用的令牌不在 CLAUDE.md 中，请标记并使用提供的回退值。 4. 本文档中的每个值都是有意的。不要用“差不多”的值替代。`间距-6` 就是 `间距-6`，不是 `间距-5`。 5. 必须实施每个状态。如果某个组件的状态未指定，这是规范中的缺口 - 请标记，不要猜测。 6. 实施每个组件后，运行其状态矩阵并验证所有状态正常工作，然后再进入下一个组件。 7. 遇到歧义时，优先选择更明确的解释。如果仍然模糊，添加 TODO 注释：“// 交接-歧义：[描述]” ```