# {{PRODUCT_NAME}} 界面与体验设计文档

## 上游前置审查

- 需求文档是否清晰：
- 技术架构是否清晰：
- 高频真实需求是否清晰：
- 真实使用流程是否清晰：
- 待确认问题：

## 上游同步记录

- 本阶段是否改变页面清单、交互路径、字段、状态、技术约束或验收标准：
- 已同步回写的上游文档：
- `workflow-state.json` notes 记录：

## UI 硬规则

- 页面可见文案、按钮、导航、空状态和提示语禁止使用 emoji。
- 图标必须使用图标库、SVG 或图片资源，不用 emoji 代替。
- 通用 Web 和移动端正文、表单、按钮、列表文本默认不小于 16px。
- B 端网页、后台、运营台、管理系统和 SaaS 产品优先遵循 B 端设计规范的文字、间距和控件参数，不强行套用移动端 16px 起规则。

## B 端规范引用记录

- 是否识别为 B 端网页：
- 判断依据：
- 章节索引检查：`rg -n "^##|^###" references/b-end-ui-design-spec.md`
- 本阶段已按需读取的规范章节：
- 已落入原型的规则：
- 未采用或偏离规范的原因：

| 阶段门禁 | 已引用章节 | 采用规则 | 对应设计动作 | 状态 |
|---|---|---|---|---|
| 识别和边界 | `使用原则` | 待补充 | 判断是否默认应用 B 端规范，记录偏离原因 | 待确认 |
| 风格和配色 | `配色流程与色彩系统规则` | 待补充 | 先明确品牌调性和产品风格，再做灰度和色彩 token | 待确认 |
| 画布和密度 | `画布与适配`、`页面基础参数`、`栅格与间距`、`B 端适配与响应式规则` | 待补充 | 按 `1440x900` 设计并校验 `1280x800` 核心内容 | 待确认 |
| 页面清单和信息架构 | `格式塔设计原则`、`视觉动线与页面布局模型规则` | 待补充 | 按页面类型选择动线，组织分组、对齐和重复结构 | 待确认 |
| 页面模式和布局骨架 | `基础组件体系与布局参数规则`、`后台数据页面补充规则` | 待补充 | 确定页面模式、固定区、自适应区、表格和筛选骨架 | 待确认 |
| 组件和视觉表现 | `文本参数`、`图标参数`、`按钮参数`、`输入框参数`、`视觉层级与组件表现规则`、`后台界面质感细节规则` | 待补充 | 收敛字号、间距、控件高度、层级和质感细节 | 待确认 |
| 交互流程和状态 | `交互效率与认知负荷规则`、`尼尔森可用性原则补充规则`、`包容性与可理解性补充规则` | 待补充 | 补齐反馈、防错、错误修正、权限异常、加载超时和帮助入口 | 待确认 |
| 原型自审和修正 | 问题对应章节的 `禁止事项` 和 `验收标准` | 待补充 | 根据截图问题反查规范并修正 | 待确认 |

## 设计方向候选

| 方向 | 主题资产 | 视觉气质 | 适合理由 | 预览路径 |
|---|---|---|---|---|
| 方案 A | 待补充 | 待补充 | 待补充 | 待补充 |
| 方案 B | 待补充 | 待补充 | 待补充 | 待补充 |
| 方案 C | 待补充 | 待补充 | 待补充 | 待补充 |

## 首页 Demo 预览

| 方向 | Demo 路径 | 展示重点 | 是否可打开 |
|---|---|---|---|
| 方案 A | prototype/directions/option-a.html | 首屏、核心入口、关键状态、视觉气质 | 待确认 |
| 方案 B | prototype/directions/option-b.html | 首屏、核心入口、关键状态、视觉气质 | 待确认 |
| 方案 C | prototype/directions/option-c.html | 首屏、核心入口、关键状态、视觉气质 | 待确认 |

预览索引：`prototype/directions/index.html`

## 已选方向

- 选择：
- 选择原因：
- 不采用方向：

## 页面清单

| 页面 | 原型路径 | 入口来源 | 覆盖功能编号 | 对应高频流程步骤 | 页面目标 |
|---|---|---|---|---|---|
| 首页/入口 | prototype/index.html | 直接打开 | M1-F1 | 待补充 | 待补充 |

## 页面访问逻辑

| 高频流程步骤 | 用户动作 | 页面/模块 | 入口 | 下一步 | 减少跳转/理解成本的设计 |
|---|---|---|---|---|---|
| 待补充 | 待补充 | 待补充 | 待补充 | 待补充 | 待补充 |

## 页面任务卡

在正式编写完整业务页面原型代码前，必须把本节内容提交给用户确认。每个页面只定义一个最核心的用户任务，先想清用户为什么来、要操作什么、哪些内容不属于本页。

| 页面 | 入口来源 | 用户进入原因 | 当前上下文对象 | 页面核心任务 | 用户操作流程 | 主操作 | 辅助模块 | 本页不做什么 | 跳转边界和上下文边界 |
|---|---|---|---|---|---|---|---|---|---|
| 首页/入口 | 直接打开 | 待补充 | 待补充 | 待补充 | 待补充 | 待补充 | 待补充 | 待补充 | 待补充 |

## 模块准入表

模块必须直接服务页面核心任务，不能因为“可能有用”就放进当前页。低频、审计、全局配置、跨上下文审核等能力应删除、折叠或后置到更合适页面。

| 页面 | 模块 | 服务的页面核心任务 | 模块类型 | 保留/折叠/后置/删除 | 原因 |
|---|---|---|---|---|---|
| 首页/入口 | 待补充 | 待补充 | 主流程/辅助判断/低频信息/跨上下文能力 | 待补充 | 待补充 |

## 原型开发前确认

- 确认状态：待确认
- 状态取值：只能是 `待确认` / `需修正` / `已确认`
- 确认时间：
- 用户意见：
- 修正记录：
- 门禁要求：未确认不得进入原型实现。

| 确认项 | 内容摘要 | 状态 |
|---|---|---|
| 页面任务卡 | 每个页面的入口来源、用户进入原因、当前上下文对象、页面核心任务、用户操作流程、主操作、辅助模块、本页不做什么、跳转边界和上下文边界已明确 | 待确认 |
| 模块准入表 | 每个模块的保留、折叠、后置或删除理由已明确 | 待确认 |
| 页面边界 | 不把配置、审核、报表、审计等无关能力塞进不匹配页面 | 待确认 |
| 修正闭环 | 用户指出的边界问题已回写本设计文档并重新确认 | 待确认 |

## 核心页面布局

### prototype/index.html

- 页面目标：
- 区块结构：
- 复用布局：
- 核心元素：
- 交互逻辑：
- 状态设计：

## 复用布局清单

| 布局 | 路径 | 适用页面 | 结构职责 | 可复用规则 |
|---|---|---|---|---|
| 待补充 | prototype/layout/待补充.html | 待补充 | 待补充 | 待补充 |

## 模块整合与减负记录

| 原候选页面/模块 | 整合后位置 | 整合原因 | 对用户成本的影响 |
|---|---|---|---|
| 待补充 | 待补充 | 避免页面堆叠、重复入口或低频能力前置 | 待补充 |

## 需求到界面映射

| 功能编号 | 页面/路径 | 控件/组件 | 用户动作 | 高频流程位置 | 状态覆盖 | 原型路径 |
|---|---|---|---|---|---|---|
| M1-F1 | 待补充 | 待补充 | 待补充 | 待补充 | 成功/失败/空/加载 | prototype/index.html |

## 组件清单

| 组件 | 使用位置 | 状态 | 行为 |
|---|---|---|---|
| 待补充 | 待补充 | 默认/悬停/禁用/加载/错误 | 待补充 |

## 用户流程

```mermaid
flowchart TD
  A[开始] --> B[待补充]
```

## 原型结构

```text
prototype/
  directions/
  index.html
  pages/
  layout/
  components/
  assets/
```

| 路径 | 职责 | 产物要求 |
|---|---|---|
| `prototype/directions/` | 设计方向首页 demo | 每个候选方向必须有一个可打开的首页 demo；`index.html` 汇总 2-3 个预览入口，供用户选择方向。 |
| `prototype/index.html` | 原型入口、全局导航、关键流程起点 | 必须能进入所有 P0 原型路径；多页面系统必须链接到 `pages/` 中的具体页面。 |
| `prototype/pages/` | 独立业务页面 | 多页面系统的每个主要页面单独存放；页面结构必须引用或遵循 `layout/` 中的复用布局。 |
| `prototype/layout/` | 可复用页面结构 | 沉淀应用外壳、导航、页头、侧栏、内容网格、表单页骨架、状态页骨架等结构，保证后续开发能稳定复现。 |
| `prototype/components/` | 可复用界面组件和交互片段 | 存放按钮组、表单控件、卡片、列表、弹窗、状态块等组件示例，并标注使用场景和状态。 |
| `prototype/assets/` | 公共资源 | 存放样式、脚本、图片、图标、示例数据等资源；页面不得依赖散落在目录外的资源。 |

页面原型必须优先复用 `prototype/layout/` 的结构，不要只在单个页面里临时拼装。

## 质量检查记录

- 已修正：
- 未采纳：

## 原型自审

- 自审报告：`docs/prototype-review.md`
- 截图目录：`prototype/review/screenshots/`
- Impeccable 上下文：Codex 使用 `.agents/context/PRODUCT.md`, `.agents/context/DESIGN.md`；Claude Code 使用 `.claude/context/PRODUCT.md`, `.claude/context/DESIGN.md` 或沿用 `.agents/context/`

| 审查项 | 要求 | 状态 |
|---|---|---|
| Playwright 截图 | 候选 demo 和完整原型页面覆盖 desktop/tablet/mobile | 待确认 |
| 原型开发前确认 | 页面任务卡、模块准入表和页面边界达到 `已确认`；未确认不得进入原型实现 | 待确认 |
| B 端适配截图 | B 端项目至少覆盖 `1280x800` 和 `1440x900` 核心路径 | 待确认 |
| B 端规则落地 | 已采用规则必须体现为真实布局、字号、间距、控件高度、状态和响应式实现 | 待确认 |
| Impeccable critique | 审美、视觉层级、信息架构、AI 味、认知负荷 | 待确认 |
| Impeccable audit | 可访问性、性能、响应式、语义结构、反模式 | 待确认 |
| Impeccable adapt | 桌面、平板、移动适配 | 待确认 |
| Impeccable polish | 最终综合打磨 | 待确认 |
