---
id: <ID>
kind: ui-spec
title: <标题> · UI 规格
prd: docs/process/prd/<ID>.md
design: docs/process/prd/<ID>-design.md
status: draft # draft / confirmed / terminated
gate1: pending
---

# <ID> <标题> · UI 规格

> **本文件是什么**：把《设计与说明》里**触及 UI 的条目**翻译成**可验收的 UI 规格** —— 界面由哪些组件构成、有哪些交互状态、用户可见文案是什么。它是 test 写 UI 断言的**判据来源**。
> **本文件不是什么**：不是 PRD（判据在 PRD 的 `AC`）、不是契约（字段与签名在 `contracts/<ID>.md`）；**不写生产实现细节**（组件内部结构 / 状态管理选型 / 生产文件路径 / 接口调用细节）。HTML 原型里的 class 名只是设计载体，不是对 dev 的生产类名要求。
> **交付主件是 HTML 原型**：`prototypes/<ID>/index.html` + `styles.css` + `handoff.md`。dev 打开就能看到真实 DOM / CSS / 状态；本件 §八 再把颜色 / 间距 / 字号字距 / 圆角写成**字面值**。**本角色不产出 PNG / PSD**；只有图、没有可打开 HTML = 未交付。
> **权威来源**：需求核对件的裁定表（`R-NN`）与《设计与说明》。**不得在此发明新业务口径** —— 需要新口径时回流 PRD 待确认事项，由人裁定。
> **送审时机**：**随 Gate1 一并审**。它是判据来源，判据必须有人审过，故不另设停点、也不在 Gate1 之后补写。
> `status` 是 ui-spec 自有的次级状态位（`confirmed` = Gate1 已过 / 本件已定稿），**不是** PRD 状态机的值；权威状态位只在 `prd/<ID>.md`。
> **适用性**：仅**核对件声明 `uiDesign: required`** 的包需要本文件；`not-needed`（或未声明）的包不产生。那份「要不要做 UI 设计」的判断由**人在 Gate0** 做出（见 `input/_CHECK_TEMPLATE.md`），不由主控推断。

## 当前状态一览

> 一屏内可读完，只写"现在是什么状态"，不留沿革；随每次交付就地更新。

- 规格条数：`UI-NN` 共 __ 条（可断言 __ / 不可断言 __）
- 组件判定：复用 __ / 改既有 __ / 新增 __
- 状态矩阵：交互点 __ 个，留空 __ 个
- 原型入口：`prototypes/<ID>/index.html`；样式来源 `<styles.css / 内联>`
- 交接：`handoff.md` 覆盖 __ / __ 条 `UI-NN`（§8.3）
- 浏览器核对：`<浏览器 + 版本 + 视口>` ／ `未核对（原因：…）`
- 视觉数值：颜色 __ 项 / 间距 __ 项 / 字号字距 __ 项（§8.2）
- 阻塞项：<有则列出 / 无>
- 最后更新轮次：<rN>

---

## 一、UI 规格清单（必填，Gate1 逐条核）

> 每条必须能追到来源（`R-NN` / `AC-N` / 《设计与说明》条目），并写成**用户可观察行为**。
> 写不出可观察判据的条目 = **不合格**，退回 pm 修《设计与说明》，**不要自己补一个能测的切面**。

| 编号 | 中文短名（6–12 字） | 可观察判据句 | 来源 | 所属端 / 页面 | 组件判定 | 状态 |
| --- | --- | --- | --- | --- | --- | --- |
| `UI-01` | <短名> | <元素出现 / 文案关键字 / 跳转 / 禁用态 / 字段取值 / 空态提示> | `R-01` · `AC-01` | `<端>` / <页面> | `reuse:<组件>` | 已落实 / 偏差 / 未落实 |
| `UI-02` | <短名> | <…> | `AC-02` | `<端>` / <页面> | `new` | 已落实 |

---

## 二、组件判定表（必填）

> **复用优先**。无理由的 `new` 视为不合格。

| # | 组件 | 判定 | 依据 / 影响面 |
| --- | --- | --- | --- |
| `C-1` | <组件名> | `reuse` | 与既有 `props` 对齐结论：<完全对齐 / 需传哪些既有参数> |
| `C-2` | <组件名> | `change` | **改既有组件对外行为** —— 影响面：还有谁在用 <列出>；兼容性结论 <…> |
| `C-3` | <新组件名> | `new` | **为什么既有组件不可复用**：<理由> |

---

## 三、交互状态矩阵（必填）

> 每个交互点逐列填写。**不适用写「不适用 + 原因」，禁止留空** —— 留空 = 未规格化，test 无法据此判红。
> 每个状态都必须在 HTML 原型里**可到达**（`?state=` 或页面内切换器）。

| 交互点 | 默认 | 加载 | 空 | 错误 | 无权限 | 禁用 |
| --- | --- | --- | --- | --- | --- | --- |
| <页面 / 操作> | <显示什么> | <显示什么> | <显示什么> | <显示什么，是否可重试> | <显示什么> | <何时禁用 / 不适用+原因> |

---

## 四、用户可见文案定稿（必填）

> 在 PRD 口径内拟稿，给**最终字符串**（供 test 断言关键字）。**不得**借文案夹带新口径或修改判据语义。原型必须逐字使用。

| # | 位置 | 最终文案 | 来源 |
| --- | --- | --- | --- |
| `W-1` | <按钮 / 标题 / 提示 / 错误> | `<逐字定稿>` | `UI-01` / `AC-01` |

---

## 五、响应式 / 多端（按需）

> 凡 `PROJECT.md` §1 声明了移动端或响应式断点，**断点行为必须显式写**，并在原型里可验证；未写 = 未规格化。

| 断点 / 端 | 布局与行为变化 | 涉及 `UI-NN` |
| --- | --- | --- |
| <如 `<768px` / 移动端> | <变化> | `UI-01` |

---

## 六、偏差与未落实项

> 与《设计与说明》有出入、或落实不了的，**必须在此单列并说明** —— 不得静默略过、不得默默按自己判断改口径。

| # | 对应来源 | 偏差 / 未落实内容 | 原因 | 影响面 | 建议处置 |
| --- | --- | --- | --- | --- | --- |
| `UD-1` | `R-NN` / `UI-NN` | <内容> | <原因> | <影响面> | <建议> |

---

## 七、回流 PRD 的新口径清单

> 你在规格化过程中发现的**新业务口径**（方案里没定、但实现必须定）—— 一律回流 PRD 待确认事项由人裁定，**不得自行拍定**。
> 没有就写「无」。

| # | 触发处 | 需要人裁定的口径 | 为什么不能自定 |
| --- | --- | --- | --- |
| `UQ-1` | `UI-NN` | <口径> | <原因> |

---

## 八、HTML 原型 · 视觉数值 · 交接（`uiDesign: required` 时必填）

### 8.0 技术与手段

> **交付格式固定为静态 HTML/CSS**（原生、无构建、无外部网络）。手写、编辑器、生成器都可以；工具不绑定，但 **HTML/CSS 作为交付载体是硬要求**。
> **不产出 PNG / PSD / 截图文件**：它们不能替代可打开的 HTML，也不作为 dev 交接源。Gate1 的实物是 `index.html`。

| 项 | 值 |
| --- | --- |
| 原型入口 | `prototypes/<ID>/index.html`（可直接打开；必填） |
| 样式来源 | `prototypes/<ID>/styles.css` 或内联；令牌来源：项目令牌 `<路径>` ／ 通用默认 `docs/process/ui/tokens.md` |
| 状态切换 | `?state=default\|loading\|empty\|error\|disabled`，或页面内可见切换器（写具体方式） |
| 浏览器核对 | `<浏览器 + 版本 + 视口>` ／ `未核对（原因：…）` |
| 测试钩子 | `<data-ui / data-testid 约定>` |

### 8.1 HTML 原型（交付主件）

> **主件 = `index.html` + `styles.css` + `handoff.md`。** 落点 `prototypes/<ID>/`；双击或静态服务器可直接打开，无构建、无外部 CDN、无真实接口。

| 文件 | 内容 | 是否必留 |
| --- | --- | --- |
| `index.html` | **HTML 原型入口**；含 doctype、viewport、所有 `UI-NN` 的 `data-ui` | **必留** |
| `styles.css` | 原型样式；颜色 / 间距 / 字号 / 圆角用字面值或项目令牌变量 | **必留**（内联样式则在 §8.0 说明） |
| `handoff.md` | **dev 交接表**：`UI-NN → 选择器 → 组件判定 → 状态 → 令牌 → 文案 → 测试钩子` | **必留** |
| `app.js` | 可选，仅状态切换 / 静态交互；**不得**接真实 API、不得写业务逻辑 | 按需 |

> **HTML 硬要求**：每个 `UI-NN` 有 `data-ui="UI-NN"`（建议同时 `data-testid="ui-nn"`）；状态矩阵的每个状态都能在原型里到达；文案逐字；响应式断点可验证；无外部网络；本地 `href/src` 目标真实存在。
> **多屏**：一个包通常不止一屏；用多个 HTML 或在同一入口用屏幕切换器，均在 `handoff.md` 列清。**「一包一图」不是常态。**

### 8.2 视觉数值（**dev 直接取用，不要靠肉眼对图**）

> 令牌优先级：**项目自己的令牌 > 通用默认值**（`docs/process/ui/tokens.md`）。
> 下面每一项都写**字面值**；写“深灰”“稍大”这类描述性词 = **不合格**。
> 取值必须与 `styles.css` / HTML **一致**。

| 类别 | 令牌 / 位置 | 字面值 | 用在哪 |
| --- | --- | --- | --- |
| 颜色 | `bg` | `#0d1117` | 页面底色 |
| 颜色 | `surface` / `border` / `text` / `muted` / `accent` / `success` / `warn` / `danger` | `<#rrggbb>` | <…> |
| 间距 | 卡片内边距 / 区块间距 / 内容区外边距 | `<N>px` | <…> |
| 字号 | 标题 / 正文 / 标签 / 辅助 | `<N>px` | <…> |
| 字距 | 按字号给（中文字距见 `tokens.md` 映射表） | `<N>`（1/1000 em） | <…> |
| 圆角 / 控件高 | 卡片 / 按钮 / 胶囊 / 输入框 | `<N>px` | <…> |

> **用了通用默认令牌就必须在此写明**（例如“本次采用 `docs/process/ui/tokens.md` 默认令牌，未使用项目专有令牌”）—— 让人知道这不是项目既有的视觉语言。
> **单位纪律**：HTML/CSS 一律用 `px`。

### 8.3 dev 交接表（`handoff.md` 必填结构）

> **交接表是 HTML 与生产实现之间的桥**。没有它，dev 仍要自己猜选择器、状态和可改范围。

```markdown
# <ID> UI 交接

## 入口与状态
- 入口：prototypes/<ID>/index.html
- 状态：?state=default / loading / empty / error / disabled
- 浏览器核对：<浏览器+版本+视口 / 未核对+原因>

## UI-NN 交接表
| UI-NN | 选择器 | 组件判定 | 状态 | 令牌 | 文案 | 测试钩子 |
| --- | --- | --- | --- | --- | --- | --- |
| UI-01 | `[data-ui="UI-01"]` | reuse: <组件> | default / disabled | `--accent` #xxxxxx | `<逐字文案>` | `ui-01` |

## dev 必须保留 / 可自由替换
- 必须保留：<文案 / 视觉层级 / 状态语义 / 可点区>
- 可替换：<DOM 结构 / 框架组件 / 数据来源 / 动画实现>
- 偏差登记：<dev 若改视觉口径，必须回写本表并报主控>
```

### 8.4 UI 还原核对（dev 实现后、UAT 前）

> 由 ui-designer 在 dev 实现完成、L2 包验证通过后执行；报告落 `reports/ui-review/<ID>.md`，结论 `pass` / `conditional` / `fail`。**不通过打回 dev；通过后才进 UAT。** 具体方法见 `skills/ui-designer/SKILL.md` 的「UI 还原核对」。
