---
name: frontend-first-workflow
description: AI Frontend First Development Workflow
---

# AI 前端先行开发工作流

> 目标：通过"早期 AI 生图反哺需求 → 规格图 → 前端代码 → API契约 → 后端实现"的流程，减少返工，确保前后端一致性

## 流程概览

```mermaid
flowchart TD
    A[需求初稿] --> B[页面清单初稿]
    B --> C[需求-界面轻量追溯矩阵]
    C --> D[页面规章草案]
    D --> E[Early AI Image Brief]
    E --> F[第一轮 AI 界面方向图]
    F --> G{Early UI Review}
    G -->|不通过| E
    G -->|通过| H[反哺 PRD/页面/状态/字段]
    H --> I[完整需求与测试追溯]
    I --> J[前置难点研究]
    J --> K[Design Brief + CSS/Token 规范]
    K --> L[第二轮 AI 多状态规格图]
    L --> M{UI Image Review}
    M -->|不通过| L
    M -->|通过| N[图片转前端规格]
    N --> O[前端代码 + Mock 数据]
    O --> P[提取 API 契约]
    P --> Q[后端设计与实现]
    Q --> R[前后端联调]
    R --> S{功能评审}
    S -->|不通过| N
    S -->|通过| T[完成]
```

## 早期视觉闸门

UI-facing feature 不能等完整 PRD、测试矩阵和 Design Brief 都完成后才第一次生图。只要满足以下条件，就必须先进入第一轮 AI 生图：

- 产品目标、非目标、范围和角色已有初稿。
- P0 页面清单已有初稿。
- 每条 P0/P1 需求至少映射到页面、区域、字段、操作和状态。
- 已写出 `docs/design/page-rules-draft.md`，包含页面类型、信息密度、基础视觉方向、关键组件、状态要求和禁止事项。

第一轮图片是"方向图"，用于暴露需求、页面和信息架构问题；第二轮图片是"规格图"，用于锁定状态、组件、响应式和可编码细节。

## 审美急救包 Skill 路由

UI-facing feature 进入本流程时，按任务类型组合以下 skill：

| 阶段 | 必用/可选 Skill | 作用 |
|------|-----------------|------|
| 需求映射 | `requirements-design-template` | 在需求阶段记录品牌参照、反参照、设计方差、动效强度、信息密度 |
| 设计方向 | `impeccable` + `design-taste-frontend` | 建立整体审美、信息架构、视觉层级、token 和 anti-slop 约束 |
| 品牌风格 | `brand-design-md` | 用户要求 Apple/Stripe/Notion/Linear/Claude 等风格时拉取 DESIGN.md |
| UI 工程基线 | `baseline-ui` | 约束 Tailwind、组件 primitive、状态覆盖、响应式和加载骨架 |
| 图标 | `better-icons` | 搜索并提取真实 SVG 图标，避免低质量自绘图标 |
| 动效 | `motion-ai-kit`（如已安装）或 `fixing-motion-performance` | 规划动画并检查性能、reduced motion、layout thrashing |
| 可访问性 | `fixing-accessibility` | 键盘、焦点、ARIA、语义、表单标签 |
| 页面交付 | `fixing-metadata` | title/meta/OG/social card/favicon |

## Frontend Skill Intake 闸门

写 `docs/design/early-ai-image-brief.md` 之前，必须先完成 Frontend Skill Intake，不能只拿页面清单直接写生图提示词。

最低必读 skill：

- `ui-ux-pro-max`：行业/产品类型、设计风格、信息密度和视觉参照。
- `impeccable`：审美判断、anti-slop、信息层级和视觉完整度。
- `design-taste-frontend`：布局、比例、留白、字体、颜色、组件质感。
- `baseline-ui`：响应式、状态覆盖、可访问性、组件稳定尺寸。
- `frontend-design`：页面组织、组件层级和可实现性。
- `better-icons`：图标体系和按钮图标策略。
- `fixing-accessibility`：关键表单、导航、焦点和语义约束。
- `fixing-motion-performance`：动效强度、reduced motion 和性能禁区。

按项目条件补读：

- 有指定品牌或风格时读 `brand-design-md`。
- 已确定 Vue/Arco、React、Next.js 等栈时读对应框架 skill。
- 有后台/表格/运营工具时读 `frontend-patterns` 和 `state-management`。

Frontend Skill Intake 必须产出 `docs/design/frontend-skill-intake.md`，至少包含：

- `skill_sources`：已读取的 skill 名称和使用原因。
- `visual_principles`：整体视觉原则、反参照和禁用风格。
- `density_rules`：移动端、后台、表单、表格的信息密度。
- `component_rules`：导航、卡片、表格、筛选、详情抽屉、表单、弹窗、底部栏等组件约束。
- `state_rules`：正常、空、加载、错误、权限、业务异常状态。
- `responsive_rules`：移动端/桌面端断点、固定比例和不允许挤压的区域。
- `copy_rules`：关键中文文案、短句规则和禁止乱码。
- `prompt_enrichment_matrix`：每个页面的视觉层级、组件、状态、字段、操作、约束和禁止项。

`early-ai-image-brief.md` 和后续 `ai-image-brief.md` 必须引用 `frontend-skill-intake.md`，并把 `prompt_enrichment_matrix` 写进每个页面的生图 prompt。缺少该 intake 时，不进入 AI 生图。

## 阶段产出物

| 阶段        | 产出物                 | 评审点                     |
| ----------- | ---------------------- | -------------------------- |
| 1. 需求骨架 | `prd-lite.md` 初稿 + `page-inventory.md` 初稿 + 轻量 `requirement-interface-matrix.md` | 是否足以生第一轮方向图 |
| 2. 页面规章 | `docs/design/page-rules-draft.md` | 信息密度、基础视觉方向、关键组件、状态和禁止事项是否明确 |
| 2.5 前端 Skill Intake | `docs/design/frontend-skill-intake.md` | 是否已把前端 skills 约束转成页面级 prompt enrichment matrix |
| 3. 早期 AI 生图 | `early-ai-image-brief.md` + `artifacts/ai-images/early/` | 页面方向、信息架构和布局是否能支撑需求 |
| 4. 早期图片评审 | `early-ui-review.md` | 图片是否暴露需求缺口，并已反哺 PRD/页面/状态/字段 |
| 5. 完整需求映射 | 页面清单 + 需求-界面追溯矩阵 + 测试追溯 | 每条需求是否覆盖到界面、状态、字段、接口和验收 |
| 6. 难点研究 | difficulty-research | 高风险问题是否已在编码前研究 |
| 7. 设计规范 | Design Brief + CSS/Token 规范 | 第二轮生图输入是否足够精确 |
| 8. 规格 AI 生图 | 多状态界面设计图 | 状态是否完整、细节是否充分 |
| 9. 图片评审 | ui-image-review | 需求、状态、CSS 是否匹配 |
| 10. 图转规格 | image-to-frontend-spec | 图片是否转成可编码前端规格 |
| 11. 前端开发 | 前端代码 + Mock 数据 | 交互是否符合预期 |
| 12. API 契约 | OpenAPI/接口文档 | 字段命名、数据结构是否一致 |
| 13. 后端开发 | 后端代码 + 真实 API | 接口是否符合契约 |
| 14. 联调验收 | 完整功能 | 端到端流程是否通畅 |

## 常见问题与解决方案

| 问题         | 表现                             | 解决方案             | 模板文件                                     |
| ------------ | -------------------------------- | -------------------- | -------------------------------------------- |
| 界面状态不全 | 只有正常态，缺空态/加载态/错误态 | 强制使用状态覆盖清单 | #[[file:templates/page-spec-template.md]]    |
| 细节不够     | 缺字段校验、操作反馈、数据格式   | 强制填写字段规格表   | #[[file:templates/page-spec-template.md]]    |
| 前后不一致   | 命名/状态值/数据结构不一致       | 建立一致性检查清单   | #[[file:templates/consistency-checklist.md]] |
| 需求没落界面 | 写完需求后不知道在哪个页面实现 | 需求-界面追溯矩阵 | `requirement-interface-matrix.md` |
| 编码时才研究 | 到实现阶段才发现难点 | 前置难点研究 | `difficulty-research.md` |
| 图片不能编码 | 图好看但缺 CSS/组件/状态规格 | 图转前端规格 | `image-to-frontend-spec.md` |
| 生图过晚 | PRD/测试/接口写完后才发现页面承载不了 | 早期 AI 生图 + early-ui-review 反哺需求 | `early-ai-image-brief.md`, `early-ui-review.md` |

## 相关模板

使用时请引用对应模板：

| 模板           | 用途                   | 引用方式                   |
| -------------- | ---------------------- | -------------------------- |
| 页面规格模板   | 定义单个页面的完整规格 | `#page-spec-template`    |
| 一致性检查清单 | 评审时检查前后端一致性 | `#consistency-checklist` |
| AI生图提示词   | 生成界面设计图的提示词 | `#ai-ui-prompts`         |
| API契约模板    | 从前端提取后端接口规范 | `#api-contract-template` |
| 需求-界面矩阵 | 需求到界面、状态、字段、接口、验收的追溯 | `requirement-interface-matrix.md` |
| 难点研究模板 | 编码前研究高风险难点 | `difficulty-research.md` |
| 图转规格模板 | 把通过评审的图片转成前端实现规格 | `image-to-frontend-spec.md` |

## Early UI Review 检查清单

- [ ] 每条 P0/P1 需求都能在第一轮方向图中找到页面证据。
- [ ] 页面数量、导航路径和主任务没有明显过长或过载。
- [ ] 首页、详情、购物车/结算、订单/售后、后台列表/表单/详情等关键页面的信息密度合理。
- [ ] 后台表格列、筛选、批量操作、详情抽屉、审计入口能承载运营工作。
- [ ] 移动端底部导航、支付中断、无网络、库存不足、认证失效等关键状态有位置。
- [ ] 图片没有新增 Product Spec 没有的功能。
- [ ] 评审结论已回填到 PRD、页面清单、状态矩阵和需求-界面追溯矩阵。

## 评审检查清单

### 界面评审 ⚠️ 必查

- [ ] 所有必要状态都有设计图（正常/空/加载/错误）
- [ ] 每条 P0/P1 需求都能在界面图中找到证据
- [ ] 边界场景都有处理方案（超长/超多/为空）
- [ ] 字段规格完整（类型/格式/校验/错误提示）
- [ ] 操作反馈明确（成功/失败/确认）
- [ ] 权限视图区分清晰
- [ ] CSS / Token 与 Design Brief 一致
- [ ] 图片没有新增需求之外的功能

### 一致性评审 ⚠️ 必查

- [ ] 命名一致性：同一概念在所有页面使用相同名称
- [ ] 状态值一致性：前后端状态值映射明确
- [ ] 交互一致性：相同操作在所有页面行为一致

### API契约评审 ⚠️ 必查

- [ ] 字段命名与前端一致
- [ ] 数据类型与前端一致
- [ ] 错误码定义完整

## 返工原因 Top5

| 排名 | 返工原因            | 预防措施             |
| ---- | ------------------- | -------------------- |
| 1    | 缺少空态/错误态设计 | 强制填写状态覆盖清单 |
| 2    | 字段校验规则不明确  | 强制填写字段规格表   |
| 3    | 前后端命名不一致    | 建立命名一致性表     |
| 4    | 操作反馈不明确      | 强制填写操作反馈表   |
| 5    | 权限控制遗漏        | 强制填写权限视图表   |
