qiaoqichaoandClaude Code
d56c699ce6
按 docs/v2/05-implementation-plan.md §1 候选迁移表与 claude_use/T00 白名单， 从 55e2cdb 抽取 224 个文件（2.48 MB）到独立目录 F:/mini-OpenClaw-v2。 - 排除：凭据(.env/server-deploy.conf/旧DELIVERY.md)、运行数据(xingbang_data 等 4 个 SQLite)、依赖(venv/node_modules 符号链接)、归档(_backup*/test-evidence/ ori_file)、Office 临时文件 - 目标目录独立 git 仓库，初始恢复点；Gitea 远程与分支待 OQ-06 Q2 定案 - 未部署、未启动服务、未调用模型 Co-Authored-By: Claude Code <noreply@anthropic.com>
119 lines
7.7 KiB
Markdown
119 lines
7.7 KiB
Markdown
# 阶段 ④ UI Spec — UI 规则定义与约束规范
|
||
|
||
> **定义**：定义每个交付面的 UI 行为与视觉约束，让 UI 实现者（人或 agent）不发明任何决策：页面骨架、组件粒度、状态机、动作权限由**表面规格（Surface Specification）** 规定；颜色/字号/间距/组件形态由**设计系统契约（DESIGN.md）** 规定。
|
||
> **输入**：① 规格 §3（Surface Specification）+ ②/③ 的接口契约（UI 消费的字段）。
|
||
> **输出**：表面规格 + DESIGN.md（含 token）+ i18n 约束。
|
||
> **进入下一阶段（⑤ 实现）**：状态机、动作权限、设计 token、i18n 全部定案。
|
||
|
||
> 适用判定：本阶段仅当改动拥有用户可见 UI（项目工作台、评审页面、材料与配置界面、证据/模拟面板）时强制；纯后端/网关/CLI 改动标记 `not applicable`。
|
||
|
||
---
|
||
|
||
## 1. 要求（Requirements）
|
||
|
||
### 1.1 进入条件
|
||
- 规格 §3 已定义交付面清单与每个面的消费字段（字段有类型、可空性、枚举值）。
|
||
- 项目已有或需要建立视觉事实源（`DESIGN.md` / 主题变量 / 组件库）。
|
||
|
||
### 1.2 完成条件（DoD）
|
||
- [ ] 每个交付面有：页面骨架 + 组件粒度边界 + 完整状态机 + 动作×权限表
|
||
- [ ] 每个 UI 提交/展示的字段能在规格 §2 找到（契约门）
|
||
- [ ] 视觉 token（颜色/字号/间距/圆角/组件）有语义化来源，不出现临时发明的 `blue500` 类裸色
|
||
- [ ] 新版文案有统一维护方式、错误码映射和语言范围；当前主要中文组件内文案，统一key化方案待建设，不声称已有双语语言包
|
||
- [ ] 可访问性约束写明：对比度（WCAG AA）、focus-visible、颜色不单独承载状态、reduced-motion
|
||
- [ ] 异常态（加载/空/错误/禁用/提交中）有明确视觉与文案定义（对应规格 `E-*`）
|
||
|
||
---
|
||
|
||
## 2. 规则（Rules）
|
||
|
||
### 2.1 表面规格规则（Surface Specification）
|
||
|
||
| 编号 | 规则 |
|
||
|---|---|
|
||
| R-4.1 | **骨架先行**：每个交付面先定页面骨架（区域划分），再定组件，禁止直接进入像素级布局。 |
|
||
| R-4.2 | **组件粒度即所有权边界**：明确"哪个组件拥有哪个状态"（如筛选条是查询条件的唯一事实源、表格不持有选择集）。组件不得越界：表格不能清空选择，只能向拥有者发请求。 |
|
||
| R-4.3 | **状态机完整**：`Idle/Loading/Ready/Empty/Error/Submitting` 等状态全列；`Loading`（骨架屏）与 `Submitting`（保留现有内容+禁用交互）是不同状态，不得合并。 |
|
||
| R-4.4 | **动作×权限表**：每个动作列角色与禁用条件（如"Auditor 看到页面但没有动作控件，而非禁用按钮"）。 |
|
||
| R-4.5 | **交互约束显式**：URL 持有可分享状态、筛选变更清空选择、选择集不跨页、破坏性操作需确认且写明数量——写成条目，不留给实现。 |
|
||
| R-4.6 | **截图不是 spec**：图片可表达布局，但必须同时有规则、状态转换、权限（R-1.7 在 UI 层同样生效）。 |
|
||
|
||
### 2.2 设计系统规则（DESIGN.md / 视觉 token）
|
||
|
||
| 编号 | 规则 |
|
||
|---|---|
|
||
| R-4.7 | **视觉来源明确**：先检查src/app/globals.css、src/components/xingbang/navigation.css和当前页面CSS；v2视觉契约在docs/v2/DESIGN.md，统一token实现待建设。避免新增互相冲突的裸色/间距，不顺手重构无关旧页。 |
|
||
| R-4.8 | **语义 token 优先**：token 用语义角色（`primary`/`surface`/`danger`），不用调色板名（`teal-500`）；组件 token 带状态（如 `button-primary-hover`、`text-input-focused`）。 |
|
||
| R-4.9 | **防漂移须执行**：新token统一来源需有实际消费和可运行检查。当前scripts/test_ui_readability.cjs是源码守卫，不是完整token导出检查；缺少机制列待办。 |
|
||
| R-4.10 | **可访问性硬约束**：正文与 focus 态满足 WCAG AA 对比度；错误/成功/选中状态不得只靠颜色表达；支持 reduced-motion；表单与错误态有明确指引。 |
|
||
| R-4.11 | **不强推框架外规范**：后端/CLI/纯数据项目标记 `not applicable`，不套用视觉契约。 |
|
||
|
||
### 2.3 i18n 规则
|
||
|
||
| 编号 | 规则 |
|
||
|---|---|
|
||
| R-4.12 | 新版文案按业务域规划key并绑定错误码；实际文件位置和调用方法在UI设计阶段明确。当前仅有中文文案，不能凭空引用语言包；旧页面修复遵循最小范围。 |
|
||
| R-4.13 | 已支持的语言与UI状态同步维护；增加语言需明确范围和验收，不因来源模板写有双语就扩充产品需求。 |
|
||
| R-4.14 | API返回稳定错误码，前端统一映射业务文案；同源代理转发错误语义，不自行生成另一套判断或吞错。 |
|
||
|
||
---
|
||
|
||
## 3. 输出规范
|
||
|
||
### 3.1 表面规格结构（每个交付面一份）
|
||
|
||
```text
|
||
Skeleton 页面骨架：区域划分与信息层级
|
||
Component 组件粒度：组件清单 + 各自拥有的状态 + 不允许越界的边界
|
||
Granularity
|
||
State Machine 状态全集 + 合法转换 + 每个状态的禁用手势（表格或图）
|
||
Actions & Guards 动作 × 角色 × 禁用条件（含"只读角色无控件而非禁用"）
|
||
Interaction 交互约束：URL 状态、选择集规则、确认对话框、虚拟化/固定行高、截断策略
|
||
Constraints
|
||
```
|
||
|
||
> 兴邦表面规格示例见 [v2 UI Spec](../v2/04-ui-spec.md)，需求编号仍回链至对应规格。
|
||
|
||
### 3.2 DESIGN.md 结构
|
||
|
||
```text
|
||
frontmatter（机器可读） colors / typography / rounded / spacing / components
|
||
（顶层组，语义角色 + 组件状态 token，支持 {colors.primary} 引用）
|
||
Markdown（人读） Overview / Colors / Typography / Layout / Elevation & Depth /
|
||
Shapes / Components / Do's and Don'ts
|
||
+ 可访问性（对比度、focus-visible、color-not-alone、reduced-motion）
|
||
+ 每个 token 的"何时用 / 何时不用 / 防止什么 agent 错误"
|
||
```
|
||
|
||
> 参考 [v2 DESIGN.md](../v2/DESIGN.md)。已观察值注明CSS来源，推断标“推断”，未定品牌决策标needs-design-decision；候选契约未被CSS消费不能宣称视觉系统已统一。
|
||
|
||
### 3.3 交付物清单
|
||
- 每个交付面的表面规格
|
||
- `DESIGN.md`或缺失清单；现有来源为src/app/globals.css和业务CSS。记录Present/Structured/Token-ready/Aligned/Backstopped证据等级，不能跳级。
|
||
- i18n key 清单（新增/变更）
|
||
- UI 验收映射：表面规格的每条交互约束 ↔ 规格 `AC-xx` ↔ [06-validation.md](06-validation.md) 的测试点（组件/E2E）
|
||
|
||
---
|
||
|
||
## 4. UI 验证约束（预置，详见阶段 ⑥）
|
||
|
||
- UI 验证分驱动平面（D0 进程内渲染树 → D1 浏览器自动化协议 → D2 附加运行中浏览器 → D3 OS 输入/无障碍 → D4 物理设备），选满足声明的最便宜平面，失败再升级。
|
||
- **驱动与观察分离**：同一模型既驱动 UI 又目测自己的截图 = 无独立裁判，不能算 pass（`Self-reported success` 反模式）。截图基线只追加不覆盖。
|
||
- 定位器禁止跨动作缓存（元素索引/坐标每次交互前重新读取）；降级顺序：语义选择器 → 文本/aria → 原始坐标，并记录最终落到哪一级。
|
||
|
||
---
|
||
|
||
## 5. 轻量路径（小改动）
|
||
|
||
- 单组件样式调整：更新 DESIGN.md 对应 token + 表面规格的组件小节，不重写整份规格。
|
||
- 触碰多交付面、状态机重构、主题切换：必须完整走本阶段。
|
||
|
||
---
|
||
|
||
## 6. 相关文档
|
||
|
||
- 输入：阶段 ① [01-requirement.md](01-requirement.md) §3、阶段 ③ [03-detailed-design.md](03-detailed-design.md)
|
||
- 验证：阶段 ⑥ [06-validation.md](06-validation.md)（UI 驱动平面与裁判分离约束）
|
||
|
||
变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。
|