References:Figma Developer Handoff Guide、figr.design Developer Handoff Playbook
Use Cases
- Handing designs to frontend after completion
- Syncing after design changes
- Design handoff for cross-team collaboration
Core Principles
"Design handoff is where most product work breaks down."
设计交接是项目失败的高发区。
Avoid:
- Designer throws it over and forgets about it
- Frontend asks questions while building
- Key decisions not communicated
- Missing states/responsiveness/accessibility
## 交接三要素
```text
1. 产物（Artifact）
- Figma 文件 / 设计说明文档 / Design Tokens
- 可直接使用的格式
2. 上下文（Context）
- 设计意图（为什么这样做）
- 决策背景（哪些是硬要求，哪些可灵活）
- 已知约束
3. 验收标准（Acceptance）
- 前端如何判断实现符合设计意图
- 哪些状态必须实现
- 不合格时的退回机制
Complete Handoff Checklist
Page Level
□ 页面清单（每个页面的目标和入口）
□ 用户流程（页面间跳转逻辑）
□ 路由说明（URL 设计）
□ 进入条件（权限 / 登录状态）
Component Level
□ 组件清单（按 Atomic Design 分层）
□ 每个组件的状态（来自 component-states）
- 默认/悬停/聚焦/禁用/加载/错误/空/权限
□ 组件变体（primary/secondary/danger...）
□ 复用关系（哪些组件多页面共用）
Visual Level
□ Design Tokens（JSON 文件或 Figma Variables）
- 颜色 / 字体 / 间距 / 圆角 / 阴影
□ 视觉风格说明（来自 visual-style）
□ 图标资源（SVG 优先）
□ 图片资源（含 retina @2x/@3x）
Interaction Level
□ 交互规则（点击/悬停/拖拽行为）
□ 动画说明（时长 / 缓动函数）
□ 反馈机制（Toast / 对话框 / 内联提示）
□ 键盘交互（快捷键 / Tab 顺序）
Responsive Level
□ 断点说明（来自 responsive-design）
□ 每个断点的布局变化
□ 内容降级策略
□ 触控目标尺寸（移动端）
Accessibility Level
□ ARIA 属性要求（aria-label/role 等）
□ 键盘导航顺序
□ 焦点状态
□ 对比度报告
□ 屏幕阅读器要求
Data Level
□ 字段需求（每个组件需要的数据）
□ 数据格式（日期/数字/货币）
□ 空值处理（缺失字段如何展示）
□ 数据来源（API / 本地状态）
Handoff Documentation Template
# 设计交接：[功能/页面名]
## 基本信息
- 设计版本：v1.2
- 交接日期：YYYY-MM-DD
- 设计文件：[Figma 链接]
- Design Tokens：[JSON 文件链接]
- 联系人：UI/UX 设计工作流
## 1. 页面清单
| 页面 | 路由 | 目标 | 入口 | 权限 |
|------|------|------|------|------|
| 用户列表 | /users | 管理用户 | 顶部导航 | admin |
| 用户详情 | /users/:id | 查看/编辑 | 列表点击 | admin |
## 2. 用户流程
[Mermaid 流程图]
## 3. 组件清单
### Atoms
- Button（primary/secondary/danger/text）
- Input（default/disabled/error）
- Badge（success/warning/danger）
### Molecules
- SearchBox（搜索框）
- FormField（表单字段）
### Organisms
- DataTable（数据表格）
- LoginForm（登录表单）
### 复用
- DataTable 在 [用户列表/订单列表/商品列表] 复用
## 4. 状态清单
[每个组件的完整状态表]
## 5. 设计 Tokens
[JSON 文件或链接]
## 6. 响应式
[断点 + 布局变化]
## 7. 可访问性
[ARIA / 键盘 / 对比度要求]
## 8. 交互动画
| 元素 | 触发 | 动画 | 时长 |
|------|------|------|------|
| 模态框 | 打开 | 淡入 + 缩放 | 200ms |
| Toast | 显示 | 从右滑入 | 300ms |
## 9. 待确认问题
- [ ] Q1: 表格行内编辑保存后是否显示成功提示？
- [ ] Q2: 移动端是否支持表格行操作？
## 10. 验收标准
- [ ] 所有页面状态完整实现（默认/加载/错误/空）
- [ ] 响应式在 320px / 768px / 1440px 验证
- [ ] 可访问性通过 axe DevTools
- [ ] Tokens 与设计一致
Figma DevMode Practices
启用 DevMode：
- 给前端提供"开发者模式"视图
- 可复制 CSS / 距离 / 颜色
- 可标注组件 status（Ready for Dev / In Progress）
最佳实践：
- 每个页面打"Ready for Dev"标签
- 关键交互写注释（不是 sticky note）
- 使用 Variables 而不是硬编码颜色
- 使用 Auto Layout（接近真实布局）
- 组件命名清晰（Button/Primary 而非 Rectangle 36）
Workflow
1. 设计完成 + 通过可用性评审
2. 按交接清单逐项准备产物
3. 写交接说明文档
4. 列出待确认问题
5. 与前端工作流走一遍交接（解释决策）
6. 前端按验收标准检查
7. 不合格 → 退回修复
8. 合格 → 前端开始实现
Quality Self-Check
□ 页面清单完整
□ 组件清单按 Atomic 分层
□ 每个组件有完整状态
□ Design Tokens 已输出
□ 响应式规则明确
□ 可访问性要求列出
□ 待确认问题已标注
□ 验收标准可执行
Common Pitfalls
- Only dropping the Figma file——no context, frontend has to guess
- Missing states——only the default state was designed
- Responsiveness not specified——frontend imagines it on their own
- No accessibility requirements——only found out after launch during an audit
- Open questions not listed——frontend discovers issues halfway through
- No acceptance criteria——after finishing, no way to know if it's right
- Tokens are in Figma but not in the documentation——frontend can't use them
Supporting Templates
templates/design-handoff-template.md— Handoff documentation + handoff checklist
Collaboration with Other Skills
上游：
所有设计 skills 完成后
下游：
转交前端工程师 → 实现页面
转交 API 设计 → 字段需求
转交 QA → 测试输入