qiaoqichao/mini-openclaw-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c880f40e4c28f05e085bcb0bfe1018052e43af02
mini-openclaw-v2/docs/project-process/04-ui-spec.md
T
qiaoqichaoandClaude Code d56c699ce6 chore(v2): 从兴邦预审v2白名单抽取独立可运行基座 
按 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>
2026-09-29 12:58:26 +08:00

7.7 KiB
Raw Blame History

阶段 ④ 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 表面规格结构（每个交付面一份）

Skeleton            页面骨架：区域划分与信息层级
Component           组件粒度：组件清单 + 各自拥有的状态 + 不允许越界的边界
Granularity
State Machine       状态全集 + 合法转换 + 每个状态的禁用手势（表格或图）
Actions & Guards    动作 × 角色 × 禁用条件（含"只读角色无控件而非禁用"）
Interaction         交互约束：URL 状态、选择集规则、确认对话框、虚拟化/固定行高、截断策略
Constraints

兴邦表面规格示例见 v2 UI Spec，需求编号仍回链至对应规格。

3.2 DESIGN.md 结构

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。已观察值注明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 的测试点（组件/E2E）

4. UI 验证约束（预置，详见阶段 ⑥）

  • UI 验证分驱动平面（D0 进程内渲染树 → D1 浏览器自动化协议 → D2 附加运行中浏览器 → D3 OS 输入/无障碍 → D4 物理设备），选满足声明的最便宜平面，失败再升级。
  • 驱动与观察分离：同一模型既驱动 UI 又目测自己的截图 = 无独立裁判，不能算 pass（Self-reported success 反模式）。截图基线只追加不覆盖。
  • 定位器禁止跨动作缓存（元素索引/坐标每次交互前重新读取）；降级顺序：语义选择器 → 文本/aria → 原始坐标，并记录最终落到哪一级。

5. 轻量路径（小改动）

  • 单组件样式调整：更新 DESIGN.md 对应 token + 表面规格的组件小节，不重写整份规格。
  • 触碰多交付面、状态机重构、主题切换：必须完整走本阶段。

6. 相关文档

变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。

Reference in New Issue View Git Blame Copy Permalink