> For the complete documentation index, see [llms.txt](https://cc-code.rongyeliu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cc-code.rongyeliu.com/templates/ux.md).

# 交互与界面规格 (ux.md)

> **L2 表现层** · 由 \[PM] 角色维护 · Dev 必须 1:1 还原，严禁自行发挥排版与颜色 · QA 据此验交互。 本文件由原 `flow.md`（交互状态矩阵）+ `front.md`（前端交接规格）合并 —— 同一个页面的「长什么样」和「点了怎么变」放在一起，才不用左右横跳。 📐 **写什么**：视觉规格 + 交互状态流转。 🚫 **不写什么**：业务规则（→ `prd.md`）、接口参数（→ `api.md`）、字段类型（→ `data.md`）。

### ⛔ 写入纪律（active = 最新 + 最完整 + 最纯净）

| 纪律          | 说明                                                            |
| ----------- | ------------------------------------------------------------- |
| **就地收敛**    | 增量变更**直接改写对应页面/元素小节**，⛔ 禁新开 `## 增量 F-n` 章节。同一个元素在本文件永远只有一处描述  |
| **过程外置**    | 需求清单 / 现状态原型 / 裁决过程 → `docs/plans/F-n-<需求名>.md`；本文件只留「现在长什么样」 |
| **台账留痕**    | 每次增量在文末「变更台账」追加一行（F 号 / 日期 / 改了什么 / 裁决 / 详情链接）                |
| **历史靠 git** | 旧版本不在本文件留存，`git log -p` 即完整历史                                 |

***

## 一、全局设计系统

| 项         | 值                                |
| --------- | -------------------------------- |
| 风格定位      | \[待填写]                           |
| 品牌主色      | \[待填写]                           |
| 背景色       | \[待填写]                           |
| 辅助色 / 语义色 | \[待填写]（成功 / 警告 / 危险 / 信息）        |
| 圆角        | \[待填写]                           |
| 阴影        | \[待填写]                           |
| 字体        | \[待填写]                           |
| 图标库       | \[待填写]                           |
| 明暗模式      | \[待填写]（强制 Light / 强制 Dark / 可切换） |
| 界面语言      | \[待填写]                           |
| 样式实现      | \[待填写]（CSS 方案 + 组件库 + 变量位置）      |

### 1.1 全局组件约定

> 同一种交互在全站必须长一个样，写在这里，各页面不再重复描述。

| 组件             | 规格                          | 使用场景   |
| -------------- | --------------------------- | ------ |
| 按钮（主 / 次 / 危险） | \[待填写]                      | \[待填写] |
| 空状态            | \[待填写]                      | \[待填写] |
| 加载态            | \[待填写]（骨架屏 / spinner / 进度条） | \[待填写] |
| 错误提示           | \[待填写]（toast / inline / 弹窗） | \[待填写] |
| 确认弹窗           | \[待填写]                      | 不可逆操作前 |

***

## 二、页面：\[页面名称]

**路由：** `[待填写]`　**准入：** \[待填写]（游客 / 已登录 / 特定角色）

### 2.1 宏观布局

```
┌──────────────────────────────────────────┐
│  [用 ascii 画出真实布局，标注区域名]        │
├──────────┬───────────────────────────────┤
│          │                               │
│          │                               │
└──────────┴───────────────────────────────┘
```

### 2.2 组件规格清单

| 组件     | 数量 | 样式要点 | 内部元素 |
| ------ | -- | ---- | ---- |
| \[待填写] |    |      |      |

### 2.3 交互状态矩阵

> ⭐ **五态必须写全**，缺一态即视为规格未完成。QA 会逐态验证。 ⛔ `U 编号` 必须**永久稳定**（`U2.1.e` 永远指同一个判定项），作废只标 `~~作废~~`，绝不重排、绝不复用 —— 否则跨轮次结果无法对比。 不适用的态标 `N/A` **并写原因**，禁止留空、禁止静默跳过（留空会被 QA 当成漏写规格）。

**U 编号规则**（`U<页章号>.<元素序号>.<态>`）：

```
U2.1.e
│ │ │└─ 态：i=正常 Idle  l=加载 Loading  s=完成 Success  e=错误 Error  m=空 Empty
│ │ └── 元素序号：§2.4 可交互元素清单的行序
│ └──── 页章号：本文件「## 二、页面」的章节序号
└────── 固定前缀 U（区别于 prd.md 的 A 断言号）

一个元素的一个态 = 一个判定项 = gates.md 矩阵里的一行
```

| U 编号   | 元素     | 状态节点              | 触发条件 | UI 表现 | 数据层交互 |
| ------ | ------ | ----------------- | ---- | ----- | ----- |
| U2.1.i | \[元素名] | **正常态 (Idle)**    |      |       |       |
| U2.1.l | \[元素名] | **加载态 (Loading)** |      |       |       |
| U2.1.s | \[元素名] | **完成态 (Success)** |      |       |       |
| U2.1.e | \[元素名] | **错误态 (Error)**   |      |       |       |
| U2.1.m | \[元素名] | **空状态 (Empty)**   |      |       |       |

### 2.4 可交互元素清单

> `/cc-code:whole-qa` 会逐个点击本清单每一项。`testid` 是定位锚点，改文案不改 testid。 元素序号与 §2.3 的 `U` 编号中段一一对应；**本清单是 QA 元素分母的声明来源**，运行时 DOM 发现的元素与本清单取并集，差集必须报告（声明未实现 / 实现未声明）。

| 序号 | 元素     | 类型     | testid  | 点击后期望  | 适用态               |
| -- | ------ | ------ | ------- | ------ | ----------------- |
| 1  | \[待填写] | button | `[待填写]` | \[待填写] | i / l / s / e / m |

### 2.5 响应式规则

| 断点             | 布局变化   |
| -------------- | ------ |
| Mobile（默认）     | \[待填写] |
| Tablet（`md:`）  | \[待填写] |
| Desktop（`lg:`） | \[待填写] |

### 2.6 边界 Case

* \[待填写]

***

## 三、跨页流转

> 单页装不下的流转写在这里（登录跳转、多步表单、支付回调等）。

```
[页面A] ──条件──► [页面B] ──条件──► [页面C]
   ▲                                  │
   └──────── 失败回退 ◄───────────────┘
```

| 流转     | 触发 | 携带状态 | 失败回退 |
| ------ | -- | ---- | ---- |
| \[待填写] |    |      |      |

***

## 附录、变更台账

> 每次增量落盘在此追加**一行**，正文永远只有当前态。 详情列指向 `docs/plans/F-n-<需求名>.md`（需求清单 / 现状态原型 / 裁决过程都在那里，不进本文件）。

| F 号    | 日期            | 改了什么（一句）                  | 冲突裁决             | 详情                    |
| ------ | ------------- | ------------------------- | ---------------- | --------------------- |
| \[F-1] | \[YYYY-MM-DD] | \[新增 U3.\* 五态 / 改版 P2 布局] | \[覆盖 U2.1.e / 无] | `docs/plans/F-1-*.md` |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cc-code.rongyeliu.com/templates/ux.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.