阶段 3：UI - 设计界面与原型

UI 是 Agent App Factory 流水线的第三阶段，负责将 PRD 中的功能描述转化为清晰的界面结构（UI Schema）和可预览的原型。这个阶段决定了最终应用的外观和交互体验，是连接产品需求和技术实现的关键桥梁。

学完你能做什么

将 PRD 转化为符合标准的 ui.schema.yaml 文件
使用 ui-ux-pro-max 技能生成专业的设计系统（样式、配色、字体）
创建可在浏览器中预览的原型（HTML + CSS + JS）
理解 UI Agent 的职责边界（设计视觉，不涉及技术实现）
避免常见的 AI 设计陷阱（如滥用紫色渐变、Inter 字体）

你现在的困境

你可能有一个清晰的 PRD，但不知道如何开始设计界面：

"PRD 写好了，但我想不出适合的 UI 风格"（缺乏设计系统知识）
"不知道该用什么颜色、字体、布局"（依赖个人审美而非专业规范）
"设计出来的原型和 PRD 对不上"（界面结构与功能需求脱节）
"怕设计太丑或太花哨，不符合产品定位"（缺乏行业设计经验）

这种设计盲区会导致后续 Code 阶段缺乏明确的视觉规范，最终生成的应用可能外观混乱、交互不一致。

什么时候用这一招

当你的 PRD 已经完成，并且满足以下条件时：

有清晰的 PRD 文档（包含用户故事、功能列表、非目标）
还没开始设计界面（UI 是第一个设计阶段）
还没决定技术栈（技术实现细节在 Tech 阶段）
希望控制设计范围，避免过度设计（UI 阶段限制不超过 3 页）

🎒 开始前的准备

前置条件

在开始 UI 阶段前，请确保：

✅ 已完成 PRD 阶段，artifacts/prd/prd.md 已生成
✅ 已安装 ui-ux-pro-max 插件（推荐方式：执行 factory init 会自动安装）
✅ 已了解 7 阶段流水线概览
✅ 已准备好 AI 助手（推荐 Claude Code）

核心思路

什么是 UI 阶段？

UI 阶段 是连接产品需求和技术实现的桥梁，它的唯一职责是将 PRD 中的功能描述转化为界面结构和视觉规范。

不是前端开发

UI Agent 不是前端开发工程师，它不会写 React 组件或 CSS 代码。它的任务是：

分析 PRD 中的功能需求
确定界面信息架构（页面和组件）
生成设计系统（颜色、字体、间距、圆角）
创建可预览的原型（HTML + CSS + JS）

它不会决定"用什么框架实现"，只会决定"长什么样"。

为什么需要设计系统？

想象一下，没有设计系统的房子装修：

❌ 无设计系统：客厅用极简风、卧室用复古风、厨房用工业风，整体混乱
✅ 有设计系统：全屋统一色调、统一风格、统一材质，协调一致

UI 阶段通过 ui-ux-pro-max 技能生成的就是这种"全屋装修指南"，确保后续 Code 阶段生成的所有界面都遵循统一的视觉规范。

输出文件结构

UI 阶段会生成三个文件：

文件	内容	作用
ui.schema.yaml	设计系统配置 + 页面结构定义	Tech 阶段读取此文件设计数据模型，Code 阶段读取此文件生成界面
preview.web/index.html	可在浏览器中预览的原型	让你提前看到界面效果，验证设计是否符合预期
design-system.md（可选）	持久化的设计系统文档	记录设计决策，方便后续调整

跟我操作

第 1 步：确认 PRD 已完成

在启动 UI 阶段前，确保 artifacts/prd/prd.md 已存在且内容完整。

检查点 ✅：

目标用户是否明确？
- ✅ 有具体画像（年龄/职业/技术能力）
- ❌ 模糊："所有人"
核心功能是否列出？
- ✅ 有 3-7 个关键功能
- ❌ 太多或太少
非目标是否充分？
- ✅ 至少列出 3 项不做的功能
- ❌ 缺失或太少

如果 PRD 不完整

先回到 PRD 阶段修改，确保设计有明确的输入。

第 2 步：启动流水线到 UI 阶段

在 Factory 项目目录中执行：

bash

# 从 PRD 阶段继续（如果 PRD 阶段刚完成）
factory continue

# 或直接指定从 ui 开始
factory run ui

CLI 会显示当前状态和可用阶段。

第 3 步：AI 助手读取 UI Agent 定义

AI 助手（如 Claude Code）会自动读取 agents/ui.agent.md，了解其职责和约束。

Agent 职责

UI Agent 只能：

读取 artifacts/prd/prd.md
写入 artifacts/ui/
使用 ui-ux-pro-max 技能生成设计系统
创建不超过 3 页的原型

它不能：

读取其他文件
写入其他目录
决定技术栈（这些在 Tech 阶段）
使用 AI 默认风格（紫色渐变、Inter 字体）

第 4 步：强制使用 ui-ux-pro-max 设计系统（关键步骤）

这是 UI 阶段的核心步骤。AI 助手必须先调用 ui-ux-pro-max 技能，即使你认为设计方向很明确。

ui-ux-pro-max 技能的作用：

自动推荐设计系统：根据产品类型、行业领域自动匹配最佳样式
提供 67 种 UI 样式：从极简主义到新布鲁塔利斯主义
提供 96 种调色板：按行业和风格预设计
提供 57 种字体组合：避免常见的 AI 风格（Inter、Roboto）
应用 100 条行业推理规则：确保设计符合产品定位

AI 助手会做什么：

从 PRD 中提取关键信息：产品类型、行业领域、目标用户
调用 ui-ux-pro-max 技能获取完整设计系统推荐
将推荐的设计系统应用到 ui.schema.yaml 和原型中

跳过此步骤会被拒绝

Sisyphus 调度器会验证是否使用了 ui-ux-pro-max 技能。如果没有，UI Agent 生成的产物会被拒绝，需要重新执行。

设计系统包含什么？

yaml

design_system:
  style: "Glassmorphism"           # 选择的样式（如玻璃态、极简主义）
  colors:
    primary: "#2563eb"             # 主色（用于主要操作）
    secondary: "#64748b"           # 辅助色
    success: "#10b981"             # 成功色
    warning: "#f59e0b"             # 警告色
    error: "#ef4444"               # 错误色
    background: "#ffffff"          # 背景色
    surface: "#f8fafc"            # 表面色
    text:
      primary: "#1e293b"           # 主要文本
      secondary: "#64748b"         # 次要文本
  typography:
    font_family:
      headings: "DM Sans"          # 标题字体（避免 Inter）
      body: "DM Sans"              # 正文字体
    font_size:
      base: 16
      lg: 18
      xl: 20
      2xl: 24
  spacing:
    unit: 8                        # 间距基准（8px 网格）
  border_radius:
    md: 8
    lg: 12
  effects:
    hover_transition: "200ms"      # hover 过渡时间
    blur: "backdrop-blur-md"       # 磨砂玻璃效果

第 5 步：设计界面结构

AI 助手会根据 PRD 中的功能需求，设计界面信息架构（页面和组件）。

界面结构示例（来自 ui.schema.yaml）：

yaml

pages:
  - id: home
    title: "首页"
    type: list
    description: "展示所有项目列表"
    components:
      - type: header
        content: "我的应用"
      - type: list
        source: "api/items"
        item_layout:
          - type: text
            field: "title"
            style: "heading"
          - type: text
            field: "description"
            style: "body"
        actions:
          - type: "navigate"
            target: "detail"
            params: ["id"]

  - id: detail
    title: "详情"
    type: detail
    params:
      - name: "id"
        type: "number"

  - id: create
    title: "创建"
    type: form
    fields:
      - name: "title"
        type: "text"
        label: "标题"
        required: true
    submit:
      action: "post"
      endpoint: "/api/items"
      on_success: "navigate:home"

页面类型：

list：列表页（如首页、搜索结果）
detail：详情页（如查看项目详情）
form：表单页（如创建、编辑）

第 6 步：创建预览原型

AI 助手会使用 HTML + CSS + JS 创建可预览的原型，展示关键交互流程。

原型特点：

使用原生技术（不依赖框架）
应用设计系统推荐的配色、字体、效果
所有可点击元素有 hover 状态和 cursor-pointer
移动优先设计（在 375px 和 768px 响应式正确）
使用 SVG 图标（Heroicons/Lucide），不用 emoji

预览方式：用浏览器打开 artifacts/ui/preview.web/index.html，即可查看原型。

第 7 步：确认 UI 输出

UI Agent 完成后，你需要检查输出文件。

检查点 ✅：

ui.schema.yaml 是否存在？
- ✅ 文件在 artifacts/ui/ 目录下
- ❌ 缺失或路径错误
设计系统是否使用了 ui-ux-pro-max 技能？
- ✅ 在输出或 schema 中明确说明
- ❌ 自行选择的设计系统
页面数量是否不超过 3 页？
- ✅ 1-3 页（MVP 聚焦核心功能）
- ❌ 超过 3 页
原型是否可在浏览器中打开？
- ✅ 用浏览器打开 preview.web/index.html 正常显示
- ❌ 无法打开或显示错误
是否避开了 AI 默认风格？
- ✅ 没有紫色/粉色渐变
- ✅ 没有使用 Inter 字体
- ✅ 使用了 SVG 图标（不用 emoji）
- ❌ 出现上述 AI 风格
所有可点击元素是否有交互反馈？
- ✅ 有 cursor-pointer 和 hover 状态
- ✅ 过渡平滑（150-300ms）
- ❌ 无交互指示或瞬间变化

第 8 步：选择继续、重试或暂停

确认无误后，CLI 会显示选项：

bash

请选择操作：
[1] 继续（进入 Tech 阶段）
[2] 重试（重新生成 UI）
[3] 暂停（稍后继续）

建议先预览原型

在 AI 助手中确认前，先用浏览器打开原型，验证设计是否符合预期。一旦进入 Tech 阶段，修改设计成本会更高。

踩坑提醒

坑 1：未使用 ui-ux-pro-max 技能

错误示例：

AI 助手自行选择了玻璃态风格、蓝色配色

后果：Sisyphus 调度器会拒绝产物，要求重新执行。

建议：

AI 助手必须先调用 ui-ux-pro-max 技能，获取推荐的设计系统

坑 2：使用了 AI 默认风格

错误示例：

紫色/粉色渐变背景
Inter 或 Roboto 字体
emoji 作为 UI 图标

后果：设计不专业，容易被识别为 AI 生成，影响产品形象。

建议：

从 ui-ux-pro-max 推荐的 57 种字体组合中选择
使用 SVG 图标库（Heroicons/Lucide）
避免滥用渐变和霓虹色

坑 3：页面数量超过 3 页

错误示例：

生成了 5 页：首页、详情、创建、编辑、设置

后果：MVP 范围失控，Tech 和 Code 阶段工作量大增。

建议：控制在 1-3 页，聚焦核心使用路径。

坑 4：原型缺少交互反馈

错误示例：

按钮没有 hover 状态，链接没有 cursor-pointer

后果：用户体验差，原型不真实。

建议：所有可点击元素都添加 cursor-pointer 和 hover 状态（150-300ms 过渡）。

坑 5：亮色模式对比度不足

错误示例：

玻璃卡片背景色 bg-white/10（太透明），文本颜色 #94A3B8（太浅）

后果：亮色模式下内容不可见，可访问性不达标。

建议：

玻璃卡片亮色模式用 bg-white/80 或更高
文本对比度 >= 4.5:1（WCAG AA 标准）

坑 6：原型和 schema 不一致

错误示例：

schema 中定义了 2 个页面，原型中却展示了 3 个页面

后果：Tech 阶段和 Code 阶段会困惑，不知道以哪个为准。

建议：确保原型和 schema 完全一致，页面数量、组件结构必须对应。

本课小结

UI 阶段的核心是设计系统：

输入：清晰的 PRD 文档（artifacts/prd/prd.md）
过程：AI 助手通过 ui-ux-pro-max 技能生成专业设计系统
输出：ui.schema.yaml（设计系统 + 界面结构）+ preview.web/index.html（可预览原型）
验证：检查设计系统是否专业、原型是否可预览、是否避开 AI 默认风格

关键原则

❌ 不做什么：不决定技术栈、不写前端代码、不使用 AI 默认风格
✅ 只做什么：生成设计系统、设计界面结构、创建可预览原型

下一课预告

下一课我们学习 阶段 4：Tech - 设计技术架构。
你会学到：
如何根据 PRD 和 UI Schema 设计技术架构
如何选择合适的技术栈（Express + Prisma + React Native）
如何设计最小可行的数据模型（Prisma Schema）
为什么 Tech 阶段不能涉及 UI 实现细节

附录：源码参考

点击展开查看源码位置

更新时间：2026-01-29

功能	文件路径	行号
UI Agent 定义	`agents/ui.agent.md`	1-98
UI Skill	`skills/ui/skill.md`	1-430
流水线定义（UI 阶段）	`pipeline.yaml`	34-47
调度器定义	`agents/orchestrator.checkpoint.md`	1-100+

关键约束：

强制使用 ui-ux-pro-max 技能：ui.agent.md:33, 53-54
禁止 AI 风格配色：ui.agent.md:36
禁止 emoji 图标：ui.agent.md:37
必须添加 cursor-pointer 和 hover 状态：ui.agent.md:38
原型页面不超过 3 页：ui.agent.md:34
使用原生 HTML/CSS/JS：ui.agent.md:35

退出条件（pipeline.yaml:43-47）：

ui.schema.yaml 存在
页面数量不超过 3
预览页面可在浏览器中打开
Agent 已使用 ui-ux-pro-max 技能生成设计系统

UI Skill 内容框架：

思维框架：目的、基调、差异化、信息架构
设计系统生成工作流：分析需求 → 生成设计系统 → 补充搜索 → 获取技术栈指南
67 种 UI 样式：极简主义、新拟态、玻璃态、布鲁塔利斯主义等
行业推理规则：100 条规则，按产品类型自动推荐设计系统
设计系统指南：颜色体系、排版系统、间距系统、组件规范
交付前检查清单：视觉质量、交互、亮/暗模式、布局、可访问性
决策原则：目的驱动、移动优先、可访问性、简洁有限、预览一致、工具优先
不要做 (NEVER)：AI 风格字体/配色、emoji 图标、低对比度、超过 3 页等

阶段 3：UI - 设计界面与原型 ​

学完你能做什么 ​

你现在的困境 ​

什么时候用这一招 ​

🎒 开始前的准备 ​

核心思路 ​

什么是 UI 阶段？ ​

为什么需要设计系统？ ​

输出文件结构 ​

跟我操作 ​

第 1 步：确认 PRD 已完成 ​

第 2 步：启动流水线到 UI 阶段 ​

第 3 步：AI 助手读取 UI Agent 定义 ​

第 4 步：强制使用 ui-ux-pro-max 设计系统（关键步骤） ​

第 5 步：设计界面结构 ​

第 6 步：创建预览原型 ​

第 7 步：确认 UI 输出 ​

第 8 步：选择继续、重试或暂停 ​

踩坑提醒 ​

坑 1：未使用 ui-ux-pro-max 技能 ​

坑 2：使用了 AI 默认风格 ​

坑 3：页面数量超过 3 页 ​

坑 4：原型缺少交互反馈 ​

坑 5：亮色模式对比度不足 ​

坑 6：原型和 schema 不一致 ​

本课小结 ​

下一课预告 ​

附录：源码参考 ​

阶段 3：UI - 设计界面与原型

学完你能做什么

你现在的困境

什么时候用这一招

🎒 开始前的准备

核心思路

什么是 UI 阶段？

为什么需要设计系统？

输出文件结构

跟我操作

第 1 步：确认 PRD 已完成

第 2 步：启动流水线到 UI 阶段

第 3 步：AI 助手读取 UI Agent 定义

第 4 步：强制使用 ui-ux-pro-max 设计系统（关键步骤）

第 5 步：设计界面结构

第 6 步：创建预览原型

第 7 步：确认 UI 输出

第 8 步：选择继续、重试或暂停

踩坑提醒

坑 1：未使用 ui-ux-pro-max 技能

坑 2：使用了 AI 默认风格

坑 3：页面数量超过 3 页

坑 4：原型缺少交互反馈

坑 5：亮色模式对比度不足

坑 6：原型和 schema 不一致

本课小结

下一课预告

附录：源码参考