---
id: process-panel
kind: ui-spec
status: draft
uiDesign: required
---

# 研发流程看板 · UI 规格（设计稿）

> **本件是什么**：把「DSH Web 左栏的研发流程看板」设计成可验收的 UI 规格、可打开的 HTML 原型与 dev 交接表。
> **本件不是什么**：不是生产集成方案，不写组件内部结构 / 状态管理选型 / 接口调用细节；`index.html` 里的 DOM 与 class 只是设计载体。
> **流程例外**：本仓库是 `dsh-process-kit` 插件自身，不是流程仓，没有 `docs/process`、`PROJECT.md` §3 属主行。本任务只写 `docs/design/process-panel/**`，不产生 `docs/process/**`。因此本件没有 `R-NN` / `AC-N`：来源列写「任务说明」或 `docs/CONTRACT.md` 的具体契约；这是本次的例外，不当作流程包通用做法。
> **交付主件是 HTML**：`index.html` + `styles.css` + `handoff.md`。本角色不产出 PNG / PSD / 截图文件。

## 当前状态一览

- 规格条数：`UI-01`–`UI-14`，共 14 条（可断言 14 / 不可断言 0）
- 组件判定：复用 0 / 改既有 0 / 新增 10 个组件（仓库无前端组件库，逐条给理由）
- 状态矩阵：6 个交互点，留空 0
- 原型入口：`docs/design/process-panel/index.html`；样式 `styles.css`；交互 `app.js`（仅状态切换）
- 交接：`handoff.md` 覆盖 14 / 14 条 `UI-NN`
- 浏览器核对：Microsoft Edge 157.0.4341.60（headless）· 1280×900 桌面 · 390×844 窄屏（CDP 设备模拟）· 另看 492×1000
- 视觉数值：颜色 27 项 / 间距 12 项 / 字号字距 9 项（§8）
- 阻塞项：无（有待产品确认项，见 §11，不影响原型成立）
- 最后更新：2026-11-20

---

## 一、设计目标与范围

**一句话**：让用户在 DSH 对话框左侧用一眼看清「这个包走到哪、现在要不要我拍板、托管到底算不算人签、journal 还信不信得过」。

**做**：

- 280–320px 窄面板，默认 300px；可折叠为 48px 摘要栏；
- 浅色 / 深色两套 CSS 变量，跟随宿主题；
- 逐步 / 托管 / 快速三档模式徽标与对应时间线；
- 四步（或快速三步）纵向时间线，五种步骤状态；
- 下一步、待确认 Q 数、journal 健康三块信息；
- 空态、托管授权、journal 篡改三种特殊语义；
- 6 个可逐个查看的原型状态。

**不做**：

- 不做 DSH Web 生产集成、不接真实 `process_status` / 文件系统；
- 不做 Gate 批准按钮、不写入 journal、不替代 Gate 摘要；
- 不做多包切换、搜索、筛选、设置页；
- 不产出 PNG / PSD / 截图作为交付物；
- 不引入外部 CDN / 字体 / 图片 / 框架 / 构建步骤。

---

## 二、数据形状与映射假设

### 2.1 设计输入形状（任务给定）

```json
{
  "mode": "full | managed | fast",
  "packageId": "FEAT-001",
  "status": "frozen",
  "steps": [
    { "key": "gate0", "label": "需求确认", "state": "done" },
    { "key": "gate1", "label": "方案确认", "state": "delegated", "delegatedBy": "gate0" },
    { "key": "gate2", "label": "测试确认", "state": "upcoming" },
    { "key": "gate4", "label": "验收确认", "state": "upcoming" }
  ],
  "next": { "label": "调 test 写红", "action": "..." },
  "qCount": 3,
  "journal": "verified | legacy | tampered | unverified"
}
```

**原型使用的可选展示字段**（不改变上述形状，只做展示补充）：

| 字段 | 用途 | 来源 / 缺省 |
| --- | --- | --- |
| `steps[].at` | 「人签 · 11-19 14:02」的时间 | 可缺省，缺省只显示「人签」 |
| `steps[].note` | 当前 / 未到 / 冻结的一行说明 | 可缺省，按状态给默认文案 |
| `journalDetail` | 篡改报警的具体原因 | 可缺省，回退「链式校验未通过」 |

**空态**：`packageId: null`（对应 `process_status.found === false` 或 `packages.length === 0`），此时 `mode` / `status` / `steps` / `next` / `journal` 均为空。

### 2.2 与 `process_status` 的接线（handoff 的权威映射）

| 看板字段 | 真实来源（`docs/CONTRACT.md` 契约 1/2/3/6） | 规则 / 降级 |
| --- | --- | --- |
| `mode` | `package.flow` | `full` / `managed` / `fast`；空态 `null` |
| `packageId` | `package.id` | 空态 `null` |
| `status` | `package.status` | 原样显示英文状态位；中文释义只放 `title`，不替换原文 |
| `steps[].key` | `gate0` / `gate1` / `gate2` / `gate4` | 快速路径额外用 `gate0` / `impl` / `deliver`（见 UD-8） |
| `steps[].state = done` | `gates[k] === 'approved'` 且 `gateHost[k] === 'human'` | 只有人签才画实心 ✓ |
| `steps[].state = delegated` | `gates[k] === 'approved'` 且 `gateHost[k] === 'delegated'` | 空心虚线 ◌ + 「Gate0 授权」；**绝不画成 done** |
| `steps[].state = current` | `gates[k] !== 'approved'` 且 `package.next.gate === 'GateN'` | 当前停点 ● |
| `steps[].state = upcoming` | 当前停点之后的 Gate | ○ |
| `steps[].state = blocked` | `journal.integrity.state === 'tampered'`，或人工驳回 | ×；只报警 / 不推进 |
| `steps[].delegatedBy` | Gate0 的 `approve` 记录里 `delegate` 含该 Gate | 文案 `Gate0 授权`；若来源不是 Gate0，按实际 key 显示 |
| `next.label` | `package.next.short` | 一行短动作 |
| `next.action` | `package.next.action` | 12px 说明，最多自然换行，不截断到不可读 |
| `qCount` | **契约里没有该字段**；从 PRD / 核对件的待确认 Q 统计 | ⚠ 见 UQ-1；原型用 3 / 2 / 1 / 0 / null 演示 |
| `journal` | `package.journal.integrity.state` | `verified` / `legacy` / `tampered` / `unverified` |
| `journalDetail` | `journal.integrity.reason` | 可缺省 |
| 空态 | `snapshot.found === false` 或 `packages.length === 0` | 不猜、不显示假包 |
| `gateHost === 'ai-hosted'` | 契约允许的 AI 代签（仅验收 / 回归装置） | **不得映射为 done**；v1 未设计专门样式，见 UD-4 / UQ-2 |

### 2.3 三档模式

| `mode` | 徽标 | 时间线 | 说明文案 |
| --- | --- | --- | --- |
| `full` | 逐步 | 4 步：需求确认 → 方案确认 → 测试确认 → 验收确认 | 「逐步：4 个 Gate 都会停下等你。」 |
| `managed` | 托管 | 4 步；Gate1/2 为 `delegated` | 「托管怎么算数」+ 逐字授权说明 |
| `fast` | 快速 | 3 步：需求确认 → 实现/回归 → 交付 | 「快速：只在需求确认停 1 次，其余连续推进。」 |

> `managed-running` 的「推进中」不是第五个步骤：四个步骤仍是 done / delegated / delegated / upcoming，当前推进写在「现在」卡片与 header 的 `implementing` 状态位上；这样不会把「推进中」误画成一个新的 Gate。

### 2.4 步骤状态语义

| `state` | 视觉 | 可见文字 | 可断言含义 |
| --- | --- | --- | --- |
| `done` | 实心绿圆 + 白 ✓ | 「人签」+ 可选时间 | 人已签；**绿勾只给人签** |
| `current` | 蓝环 + 蓝实心点 ● | 「当前停点」/ 步骤 note | 当前停在这里等人 |
| `delegated` | 琥珀虚线空心环 + 空心点 ◌ + 「Gate0 授权」徽标 | 「不是人签」+ 可选时间 | 托管预授权；**不是人签，不是绿色对勾** |
| `upcoming` | 灰色空心圆 ○ | 「未开始」/ 步骤 note | 还没到 |
| `blocked` | 红环 + 红 × | 「已冻结 · 校验失败」/ 驳回原因 | 驳回或 journal 篡改；停住不推进 |

### 2.5 journal 健康

| `journal` | 徽标文案 | 语气 | `title` 解释 |
| --- | --- | --- | --- |
| `verified` | `✓ 链式一致` | success | `meta.lines` 与 `chainHash` 均一致（契约 3） |
| `legacy` | `⚠ 旧格式` | warn | meta 无 `chainHash`：只验了行数与末行，中间行不可验 |
| `unverified` | `⚠ 未校验` | warn | 无 `.meta.json` 或指纹损坏：无法校验，不等于通过 |
| `tampered` | `🚨 篡改嫌疑` | danger | 行数 / `lastHash` / `chainHash` 对不上：停在这里，不推进 |

> 「无法校验」**不是绿**：`legacy` / `unverified` 都用 ⚠，不用 ✓。

### 2.6 状态位语气

| status | 点颜色 | `title` 释义 |
| --- | --- | --- |
| `draft` | muted | Gate1 前的需求 / 方案阶段 |
| `frozen` | warn | Gate1 已过，等测试归因 |
| `red` | danger | 有验收测试未过 |
| `implementing` / `verifying` / `uat` | accent | 实现 / 验证 / UAT 验收中 |
| `done` | success | 已完成 |
| `terminated` | muted | 已终止 |

> `full-gate1` 示例用 `draft` 而不是任务示例里的 `frozen`：按仓库契约 `frozen` 表示 Gate1 已过，若停在 Gate1 还写 `frozen` 会自相矛盾。`frozen` 在 `tampered` 里保留，用来展示「frontmatter 写 frozen 但 journal 链断，状态位不采信」。见 UD-9。

---

## 三、UI 规格清单

> 编号稳定，短名一处定死；下游 test / uat / 证据文件名照抄。
> 来源：`任务` = 本次任务说明；`契约` = `docs/CONTRACT.md` 的契约 1/2/3/6。本包无 PRD / AC，理由见文首例外说明。

| 编号 | 中文短名（6–12 字） | 可观察判据句 | 来源 | 组件判定 | 状态 |
| --- | --- | --- | --- | --- | --- |
| `UI-01` | 面板容器与宽度 | 在 DSH 左栏出现 1 个宽 280–320px（演示 300px）的「研发流程」面板；折叠后只保留 48px 摘要栏；任何状态下都不出现横向滚动 | 任务「位置与尺寸」 | `new:C-1` | 已落实 |
| `UI-02` | 折叠与展开控件 | 头部有 26×26px 折叠按钮，`aria-expanded` 随状态变化；折叠后键盘焦点落到 48px 展开栏，展开后回到折叠按钮；`?collapsed=1` 可直达折叠态 | 任务「可折叠」 | `new:C-7` | 已落实 |
| `UI-03` | 标题与模式徽标 | 标题逐字「研发流程」；徽标逐字「逐步」/「托管」/「快速」；托管徽标的 `title` 写明 Gate1/2 由 Gate0 授权；空态隐藏徽标 | 任务「头部」 | `new:C-4` | 已落实 |
| `UI-04` | 包 ID 与状态 | 非空态显示「`{ID} · {status}`」（如 `FEAT-001 · draft`）；无包时显示逐字「还没有需求包」；状态不只靠色点，英文状态文字必须可见 | 任务「头部」+ 契约 1 | `new:C-5` | 已落实 |
| `UI-05` | 四步时间线 | 非空态出现纵向时间线区域；逐步 / 托管显示 4 步，Gate 顺序固定为 Gate0 → Gate1 → Gate2 → Gate4；空态隐藏 | 任务「四步时间线」 | `new:C-2` | 已落实 |
| `UI-06` | 步骤状态标记 | 每步有 20px 圆标与可见状态文字：done 实心 ✓ / current 蓝色 ● / delegated 琥珀空心 ◌ + 「Gate0 授权」 / upcoming 空心 ○ / blocked 红 ×；`aria-current="step"` 标在当前步 | 任务「每步状态」 | `new:C-3` | 已落实 |
| `UI-07` | 托管授权说明 | 托管态显示逐字「Gate1/2 由你在 Gate0 授权，不是人签；验收仍由你签。」；`delegated` 步骤的徽标与文字都不得呈现为绿色人签 | 任务「文案硬约束」 | `new:C-8` | 已落实 |
| `UI-08` | 下一步 | 显示 `next.label` 与 `next.action`；有当前停点时标签「下一步」，无当前停点（托管推进）时标签「现在」，篡改时标签「下一步（已锁定）」；篡改态无任何推进按钮 | 任务「信息区」+ 契约 6 | `new:C-6` | 已落实 |
| `UI-09` | 待确认 Q 数 | `qCount > 0` 时显示「`{N} 个待确认`」；`0` / `null` 时整枚 chip 隐藏，不占位 | 任务「可选：待确认 Q 数」 | `new:C-6` | 已落实 |
| `UI-10` | journal 健康 | 非空态显示 4 种之一：`✓ 链式一致` / `⚠ 旧格式` / `⚠ 未校验` / `🚨 篡改嫌疑`；每种都有 `title` 解释；空态隐藏 | 任务「journal 健康」+ 契约 3 | `new:C-6` | 已落实 |
| `UI-11` | 空态入口 | 无包时显示「把需求一句话发我，我来建包」，并列出 4 个拍板点（需求确认 / 方案确认 / 测试确认 / 验收确认）与人话说明；空态文案不出现 Gate 术语、不要求先学流程 | 任务「empty」 | `new:C-10` | 已落实 |
| `UI-12` | 快速路径时间线 | 快速模式只显示 3 步「需求确认 → 实现/回归 → 交付」，不出现 Gate1 / Gate2 / Gate4 步骤；第一步只保留 Gate0 辅注 | 任务「快速路径」+ 契约 1 | `new:C-2` | 已落实 |
| `UI-13` | 篡改报警与冻结 | `journal=tampered` 时顶部出现红色报警「🚨 journal 篡改嫌疑」+ 具体原因 + 「看板只报警、不推进；修好前任何 Gate 都不算数。」；下一步区显示锁定文案，不出现推进 / 签名入口 | 任务「tampered」+ 契约 3 | `new:C-9` | 已落实 |
| `UI-14` | 折叠态摘要栏 | 折叠后 48px 竖栏包含竖排「研发流程」、各步状态 glyph、模式首字（逐 / 托 / 快）与 journal glyph；按钮 `aria-label` 汇总「模式 · 包 ID，停在哪」 | 任务「可折叠」 | `new:C-7` | 已落实 |

---

## 四、组件判定

> 复用优先。本仓库是流程插件，**没有前端组件库 / 设计系统 / 既有面板**（`docs/DESIGN.md` 与源码均无 UI 组件导出），因此 10 个组件全部为 `new`，逐条给理由。

| # | 组件 | 判定 | 为什么既有组件不可复用 |
| --- | --- | --- | --- |
| `C-1` | 面板容器 | `new` | 仓库没有可复用的侧栏面板组件；DSH 宿主只提供外壳，不提供面板内部布局 API |
| `C-2` | 纵向时间线 | `new` | 无既有时间线 / 步骤条组件；四步 + 五状态 + 连接线是本看板专有语义 |
| `C-3` | 步骤状态标记 | `new` | 需要严格区分「人签 ✓ / 当前 ● / 托管 ◌ / 未到 ○ / 阻塞 ×」，通用徽标组件无法表达「托管不是人签」 |
| `C-4` | 模式徽标 | `new` | 三档模式文案固定，且托管必须带授权说明；通用 Tag 无法承载 |
| `C-5` | 包 ID + 状态行 | `new` | 组合了等宽 ID、分隔符、状态色点与英文状态位，无既有组件 |
| `C-6` | 信息区（下一步 + Q / journal chip） | `new` | 下一步卡片与两枚 chip 共享信息区语义，但语气不同；仓库无卡片 / chip 组件，按基础样式派生 |
| `C-7` | 折叠摘要栏 | `new` | 48px 竖排摘要 + glyph 语义是看板专有；宿主侧栏折叠不提供这种信息密度 |
| `C-8` | 托管授权说明 | `new` | 这是合规文案载体，必须逐字、必须与 delegated 视觉绑定，不能复用普通 callout |
| `C-9` | 篡改报警 | `new` | 需要 `role="alert"`、红色语气、原因行与下一步锁定联动；无既有报警组件 |
| `C-10` | 空态引导 | `new` | 需要「一句话入口 + 4 个拍板点 + 人话说明」的专用空态；仓库无空态组件，且不能用 Gate 术语 |

**结论**：无 `reuse` / `change`；10 个 `new` 均因「仓库没有 UI 组件层」而非「不愿复用」。

---

## 五、交互状态矩阵

> 本面板是**只读**的：没有 Gate 批准、没有写 journal、没有网络请求。因此「加载 / 无权限 / 禁用」多为不适用，但逐格写清原因，不留空。

| 交互点 | 默认 | 加载 | 空 | 错误 | 无权限 | 禁用 |
| --- | --- | --- | --- | --- | --- | --- |
| 面板渲染（只读） | 按当前包渲染头部 + 时间线 + 信息区 | 不适用：数据来自本地 `docs/process` 同步读取，无网络请求；本设计不出骨架屏 | `packageId=null` → 空态（UI-11），隐藏时间线 / 下一步 / meta | `journal=tampered` → 报警（UI-13）+ blocked 步骤 + 锁定下一步 | 不适用：只读本地文件，无账号 / 权限模型 | 不适用：面板没有写操作 |
| 折叠 / 展开 | 展开 300px；折叠按钮 `aria-expanded="true"` | 不适用：纯本地 DOM 状态，无异步 | 可折叠；展开栏 `aria-label` 说明「还没有需求包」，不显示假步骤 | 可折叠；展开栏显示 🚨 与「篡改」语义 | 不适用 | 不适用 |
| 下一步区（UI-08） | 显示 `next.label` + `next.action`；有停顿标「下一步」，推进中标「现在」 | 不适用 | 隐藏 | 显示「下一步（已锁定）」+ 修复说明，不提供按钮 | 不适用 | 篡改 → 锁定；其余状态仅展示，不可点击 |
| journal 健康（UI-10） | `✓ 链式一致` | 不适用 | 隐藏 | `🚨 篡改嫌疑` | 不适用 | 不适用：只读徽标 |
| 时间线形态（UI-05 / UI-12） | full / managed 四步；fast 三步 | 不适用 | 隐藏 | 保留最后可信步骤，当前 / 下一步画 blocked | 不适用 | 不适用 |
| 步骤状态（UI-06） | 组合 done / current / upcoming；managed 可出现 delegated | 不适用 | 无步骤 | blocked（×） | 不适用 | 不适用 |
| 原型状态切换器（非产品） | 6 个按钮 + `?state=`，逐个可看 | 不适用 | 可到 `state=empty` | 可到 `state=tampered` | 不适用 | 不适用 |

**矩阵外补充**：`?journal=legacy` / `?journal=unverified` 是**原型工具条专用的健康徽标覆写**，只改 chip、不改步骤；`tampered` 状态报警优先、不可覆写。生产不出现这个覆写。

---

## 六、用户可见文案定稿

> 原型逐字使用。test 断言关键字取「最终文案」列；`{...}` 是数据插值，不写死。

| # | 位置 | 最终文案 | 来源 |
| --- | --- | --- | --- |
| `W-01` | 面板标题 | `研发流程` | UI-03 |
| `W-02` | 模式徽标 | `逐步` / `托管` / `快速` | UI-03 |
| `W-03` | 包行模板 | `{packageId} · {status}` | UI-04 |
| `W-04` | 空态包行 | `还没有需求包` | UI-04 / UI-11 |
| `W-05` | 四步标签 | `需求确认` / `方案确认` / `测试确认` / `验收确认` | UI-05 |
| `W-06` | 快速三步标签 | `需求确认` / `实现/回归` / `交付` | UI-12 |
| `W-07` | done 说明 | `人签`（可选追加 ` · {at}`） | UI-06 |
| `W-08` | current 说明 | `当前停点`（可被步骤 note 覆盖） | UI-06 |
| `W-09` | delegated 徽标 | `{delegatedBy} 授权`，Gate0 时逐字 `Gate0 授权` | UI-06 / UI-07 |
| `W-10` | delegated 说明 | `不是人签`（可选追加 ` · {at}`） | UI-06 / UI-07 |
| `W-11` | delegated hover / 说明 | `托管：不是人签` | UI-06 / UI-07 |
| `W-12` | upcoming 说明 | `未开始`（可被步骤 note 覆盖，如 `未到 · 验收仍由你签`） | UI-06 |
| `W-13` | blocked 说明 | `已冻结 · 校验失败`（可被驳回原因覆盖） | UI-06 / UI-13 |
| `W-14` | 托管授权说明 | `Gate1/2 由你在 Gate0 授权，不是人签；验收仍由你签。` | UI-07 |
| `W-15` | 托管说明标题 | `托管怎么算数` | UI-07 |
| `W-16` | 下一步标签 | `下一步` / `现在` / `下一步（已锁定）` | UI-08 |
| `W-17` | journal 健康 | `✓ 链式一致` / `⚠ 旧格式` / `⚠ 未校验` / `🚨 篡改嫌疑` | UI-10 |
| `W-18` | 空态标题 | `把需求一句话发我，我来建包` | UI-11 |
| `W-19` | 空态示例 | `例：给订单页加一个批量导出` | UI-11 |
| `W-20` | 空态引导 | `你只需要在 4 个拍板点回答「行 / 不行」：` | UI-11 |
| `W-21` | 空态四问 | `这条需求要不要做` / `这么做行不行` / `测试够不够` / `验收过不过` | UI-11 |
| `W-22` | 空态脚注 | `第一次用不用记流程：把需求发我，每一步我会告诉你拍什么板。` | UI-11 |
| `W-23` | 逐步说明 | `逐步：4 个 Gate 都会停下等你。` | UI-03 |
| `W-24` | 快速说明 | `快速：只在需求确认停 1 次，其余连续推进。` | UI-12 |
| `W-25` | 篡改报警标题 | `🚨 journal 篡改嫌疑` | UI-13 |
| `W-26` | 篡改报警正文 | `{journalDetail}。看板只报警、不推进；修好前任何 Gate 都不算数。` | UI-13 |
| `W-27` | Q 数 chip | `{qCount} 个待确认` | UI-09 |
| `W-28` | 折叠按钮 aria | `折叠研发流程看板` | UI-02 |
| `W-29` | 展开栏 aria 模板 | `展开研发流程看板：{modeLabel} · {packageId}，{summary}` | UI-14 |
| `W-30` | 空态展开栏 aria | `展开研发流程看板：还没有需求包` | UI-14 |

**禁用语气**：不得出现任何「系统替你批准 / 自动代签」类表述；不得把 delegated 说成「已签」「通过」。

---

## 七、响应式 / 多端

> 本设计的主战场是 DSH Web 桌面左栏；窄屏行为仅用于原型自查与极端窗口，不是移动端产品形态。

| 断点 / 端 | 布局与行为变化 | 涉及 `UI-NN` |
| --- | --- | --- |
| `> 960px` | 演示外壳双列：左栏 324px（面板 300px）+ 右侧对话区；面板高度跟随外壳 640–780px | UI-01 |
| `≤ 960px` | 外壳单列；对话区移到下方；面板宽 `min(300px, 100%)`，最小高度 620px | UI-01 / UI-05 |
| `≤ 640px` | 工具条纵向堆叠；状态按钮 3 列换行；对话区隐藏；面板仍 300px（≥280px 下限），折叠栏 480px 高 | UI-01 / UI-02 / UI-14 |
| 折叠态 | 面板整体换成 48px 竖栏；外壳左列 72px（12px 边距 + 48px 栏） | UI-02 / UI-14 |

**验证读数**（CDP 390×844）：`innerWidth = 390`、`documentElement.scrollWidth = 390`、面板 `width = 300`、外壳 `width = 366`，无横向滚动。

---

## 八、视觉数值

> **令牌来源**：本仓库无项目级 UI 令牌文件（`PROJECT.md` 不存在），本次采用 `scaffold/ui/tokens.md` 的**通用默认令牌**（深色语义档），并按同一语义补了浅色档；所有文字对底对比度实测 ≥ 4.5:1。**这是默认令牌，不是项目既有视觉语言**。
> 颜色一律 `#rrggbb` / `rgba(...)`；间距、字号、圆角一律 `px`。

### 8.1 颜色

| 令牌 | 深色 | 浅色 | 用在哪 |
| --- | --- | --- | --- |
| `--bg` | `#0d1117` | `#f6f8fa` | 页面 / 对话区底 |
| `--shell` | `#010409` | `#eaeef2` | 演示外壳左栏底 |
| `--surface` | `#161b22` | `#ffffff` | 面板、卡片底 |
| `--surface-2` | `#1c2128` | `#f6f8fa` | 下一步卡片、chip 底 |
| `--surface-3` | `#21262d` | `#eef1f4` | hover 底 |
| `--border` | `#30363d` | `#d0d7de` | 常规描边、分隔线 |
| `--border-strong` | `#484f58` | `#afb8c1` | 空心步骤环、虚线框 |
| `--text` | `#e6edf3` | `#1f2328` | 主文字 |
| `--text-soft` | `#b1bac4` | `#57606a` | 12px 辅助文字（不用 muted） |
| `--muted` | `#8b949e` | `#6e7781` | 仅状态点 / 装饰 |
| `--accent` | `#58a6ff` | `#0550ae` | 当前步、快速徽标、主强调文字 |
| `--accent-fill` | `#1f6feb` | `#0969da` | 当前步圆点、脉冲点 |
| `--accent-soft` | `rgba(56,139,253,0.16)` | `rgba(9,105,218,0.08)` | 当前步底、选中态 |
| `--accent-border` | `rgba(88,166,255,0.38)` | `rgba(9,105,218,0.30)` | 当前步描边 |
| `--success` | `#7ee787` | `#116329` | 人签文字、链式一致 |
| `--success-fill` | `#238636` | `#1a7f37` | 实心 ✓ 圆底、成功点 |
| `--success-soft` | `rgba(63,185,80,0.16)` | `rgba(26,127,55,0.08)` | 健康 chip 底 |
| `--success-border` | `rgba(126,231,135,0.34)` | `rgba(26,127,55,0.30)` | 健康 chip 描边 |
| `--warn` | `#e3b341` | `#7d4e00` | 托管徽标、delegated 文字 |
| `--warn-fill` | `#d29922` | `#bf8700` | delegated 虚线环 |
| `--warn-soft` | `rgba(210,153,34,0.16)` | `rgba(191,135,0,0.10)` | 托管说明底、授权徽标底 |
| `--warn-border` | `rgba(227,179,65,0.40)` | `rgba(191,135,0,0.36)` | 托管说明 / 徽标描边 |
| `--danger` | `#ff7b72` | `#a40e26` | 篡改 / 阻塞文字 |
| `--danger-fill` | `#da3633` | `#cf222e` | 阻塞 ×、状态点 |
| `--danger-soft` | `rgba(248,81,73,0.14)` | `rgba(207,34,46,0.08)` | 报警 / 锁定底 |
| `--danger-border` | `rgba(255,123,114,0.38)` | `rgba(207,34,46,0.30)` | 报警 / 锁定描边 |
| `--focus` | `#58a6ff` | `#0969da` | 2px 焦点环 |
| 实心 ✓ 的白 | `#ffffff` | `#ffffff` | 绿底上的对勾 |

### 8.2 间距

| 位置 | 值 |
| --- | --- |
| 面板头部内边距 | `12px 14px 10px` |
| 面板主体内边距 | `12px 14px 14px` |
| 主体区块间距 | `12px` |
| 时间线行间距 | `8px` |
| 步骤标记与文字间距 | `10px` |
| 步骤框内边距 | `5px 8px 6px` |
| 下一步卡片内边距 | `9px 11px 10px` |
| 报警 / 托管说明内边距 | `9px 11px 10px` |
| meta 分隔线上间距 | `10px` |
| 空态列表行内边距 | `7px 0` |
| 折叠栏内边距 | `10px 0 12px` |
| 演示外壳左栏内边距 | `12px` |

### 8.3 字号 / 行高 / 字距（中文 tracking 按 `tokens.md` 映射）

| 用途 | 字号 | 行高 | 字重 | 字距 |
| --- | --- | --- | --- | --- |
| 面板标题 | `14px` | `1.3` | `600` | `0.045em` |
| 步骤标签 | `14px` | `1.35` | `500`（current 600） | `0.045em` |
| 下一步主文 | `14px` | `1.4` | `600` | `0.045em` |
| 空态标题 | `15px` | `1.45` | `600` | `0.04em` |
| 正文 / 报警 / 授权说明 | `13px` | `1.55` | `400` | `0.06em` |
| 步骤说明 / 下一步说明 / chip | `12px` | `1.45–1.5` | `400` | `0.06em` |
| 徽标 / 小标签 | `12px` | `1` | `500–600` | `0.06–0.08em` |
| Gate 辅注 / 空态编号 | `11px` | `1.4–1.7` | `400` | `0`（等宽拉丁） |
| 包 ID | `12px` | `1.4` | `600` | `0`（等宽拉丁） |

### 8.4 圆角 / 尺寸 / 控件

| 项 | 值 |
| --- | --- |
| 面板圆角 | `12px` |
| 卡片 / 报警 / 授权说明圆角 | `8px` |
| 步骤框圆角 | `8px` |
| 胶囊 / 徽标圆角 | `999px` |
| 步骤标记 | `20px` 直径，`1.5–2px` 描边 |
| 折叠按钮 | `26×26px` |
| 折叠摘要栏 | `48px` 宽 |
| 面板宽度 | `280–320px`（演示 `300px`） |
| chip 高度 | `24px` |
| 焦点环 | `2px` 实线，`offset 2px` |
| 当前推进脉冲 | `6px`，`1.8s ease-in-out` 循环；`prefers-reduced-motion` 下关闭 |

### 8.5 对比度实测

| 组合 | 深色 | 浅色 | 判据 |
| --- | --- | --- | --- |
| 主文字 on `surface` | `14.64:1` | `15.80:1` | ≥ 4.5 |
| 辅助文字 on `surface` | `8.81:1` | `6.39:1` | ≥ 4.5 |
| accent on `surface` | `6.85:1` | `7.59:1` | ≥ 4.5 |
| success on `surface` | `11.26:1` | `7.39:1` | ≥ 4.5 |
| warn on `surface` | `8.89:1` | `7.09:1` | ≥ 4.5 |
| danger on `surface` | `6.86:1` | `7.87:1` | ≥ 4.5 |
| 白 ✓ on `success-fill` | `4.63:1` | `5.08:1` | 图形 / 文字均过 |
| accent chip | `5.23:1` | `6.68:1` | ≥ 4.5 |
| success chip | `7.68:1` | `6.56:1` | ≥ 4.5 |
| warn chip | `6.48:1` | `6.09:1` | ≥ 4.5 |
| danger chip | `5.54:1` | `6.83:1` | ≥ 4.5 |

> 12–13px 中文不使用 `--muted` 作正文；`--text-soft` 在两种主题都 ≥ 6.39:1，给抗锯齿留了余量。

---

## 九、可访问性

- **不只看颜色**：每一步同时有 glyph（✓ / ● / ◌ / ○ / ×）+ 可见状态文字 +（delegated）徽标；journal 同时有 glyph + 文字；模式徽标有文字。
- **键盘可达**：状态切换器（原型）、journal 覆写、主题、折叠按钮、折叠摘要栏均为原生 `button` / `select`，Tab 可达；折叠时焦点从折叠按钮移到摘要栏，展开时移回折叠按钮。
- **语义**：当前步 `aria-current="step"`；折叠按钮与摘要栏 `aria-expanded` + `aria-controls`；篡改报警 `role="alert"`；状态切换通过 `aria-live="polite"` 播报；delegated 步骤有 `title="托管：不是人签"`，且可见文字已写明「不是人签」。
- **焦点**：`:focus-visible` 2px 实线 + 2px offset；深色 `#58a6ff` / 浅色 `#0969da`。
- **目标尺寸**：折叠按钮 26×26px（≥ WCAG 2.2 AA 的 24×24）；摘要栏 48px 宽；其余信息区不可点击，避免假按钮。
- **动效**：仅当前推进脉冲；`prefers-reduced-motion: reduce` 下时长压到 0.001ms。
- **语言**：`html lang="zh-CN"`；英文 ID / 状态保留原文，不翻译成假中文。
- **边界**：面板只读，没有「批准」按钮，因此不存在误触签名；这不是缺陷，是设计约束（见 UD-11）。

---

## 十、偏差与未落实项

| # | 对应来源 | 偏差 / 未落实内容 | 原因 | 影响面 | 建议处置 |
| --- | --- | --- | --- | --- | --- |
| `UD-1` | 任务「不做生产集成」 | 只有 HTML 原型，没有 DSH Web 生产挂载、真实数据读取、真实折叠联动 | 任务明确只做设计稿 + 原型 | dev 需要按 handoff 接宿主 | 保持；生产实现另立包 |
| `UD-2` | 状态矩阵「加载」 | 不出骨架屏 / 加载态 | 数据来自本地 `docs/process` 同步读取，无网络；面板应瞬时渲染 | 若宿主读取慢，可能出现空白 < 200ms | 真机上若 > 200ms，再补 3 行骨架 |
| `UD-3` | `qCount` | 契约 `process_status` 没有 `qCount` 字段 | 任务给定形状有，但仓库契约未提供 | 真实接线时 Q 数可能缺失 | 见 UQ-1，需产品/主控定来源 |
| `UD-4` | 契约 2 / 6 `gateHost=ai-hosted` | v1 没有专门的「AI 托管」步骤样式 | 任务六态未覆盖；但契约允许该值，且不得当人签 | 验收 / 回归装置里可能出现 | 见 UQ-2；临时规则：**绝不映射为 done**，按 delegated 的空心样式 + 「AI 托管」徽标兜底 |
| `UD-5` | 契约 6 `packages[]` | 只设计单包视图，没有多包切换 | 任务只要求「当前包 ID」 | 多包仓库只能显示约定的一包 | 见 UQ-3；v1 建议按宿主当前选中包 |
| `UD-6` | `docs/I18N.md` / 双语仓库 | 原型只有中文文案 | 任务以中文写死文案 | 英文仓库需要 i18n | 见 UQ-4；文案表已按 key 化预留（W-01…W-30） |
| `UD-7` | UI-14 | 折叠栏不显示包 ID 文本 | 48px 放不下可读 ID；放缩写会发明新标识 | 展开后才能看到完整 ID | `aria-label` / `title` 已带完整上下文；可接受 |
| `UD-8` | UI-12 | 快速路径用 `impl` / `deliver` 两个展示 key，不在 Gate 枚举里 | 契约说 fast 只有 Gate0；「交付」是里程碑不是 Gate | 数据适配层需要把 `progress` 的三段折成 steps | 见 UQ-5；不要把它们写进 journal 的 `gate` 字段 |
| `UD-9` | UI-04 | 状态位只显示英文原文，中文释义只在 `title` | 避免把 `frozen` 等状态位翻译成另一套状态机 | 用户可能不熟悉英文状态 | 见 UQ-8；若要中文，需先统一术语表 |
| `UD-10` | UI-06 / UI-07 | delegated 的 hover 说明用原生 `title`，没有自定义 tooltip | 窄面板里自定义浮层容易越界；可见文字已写明「不是人签」 | 触屏没有 hover，但文字仍可读 | 保持；若必须 hover 浮层，另立小改 |
| `UD-11` | 任务「信息区」 | 面板没有 Gate 批准 / 跳转 / 打开产物按钮 | 看板是只读视图，批准走 Gate 摘要；加按钮会造出第二条签名入口 | 用户需回对话里操作 | 保持；若产品要跳转，需补交互规格 |

---

## 十一、回流产品 / 主控的问题

| # | 触发处 | 需要人裁定的口径 | 为什么不能自定 |
| --- | --- | --- | --- |
| `UQ-1` | `UI-09` / `qCount` | 待确认 Q 数从哪来：PRD / 核对件的 `Q` 计数，还是给 `process_status` 新增字段？ | 这是数据来源与契约变更，不是 UI 能决定的 |
| `UQ-2` | `UI-06` / `gateHost=ai-hosted` | AI 托管的 Gate 在面板上怎么显示？用空心 + 「AI 托管」徽标，还是直接显示「不可作为人签」？ | 涉及合规语气与验收装置口径，必须人定 |
| `UQ-3` | 面板头部 | 多包仓库显示哪一包：宿主当前选中包、最近更新包，还是加包切换器？ | 任务只给单包形状；选错会看错包 |
| `UQ-4` | 全文案 | 看板是否需要中英双语 / 跟随仓库 `lang`？ | 仓库是双语项目，但任务文案是中文；术语翻译需统一 |
| `UQ-5` | `UI-12` | 快速路径的「交付」是不是人的一个停点？契约说 fast 只停 Gate0 | 若「交付」也是人签，就与契约冲突；若只是里程碑，文案要避免「签」 |
| `UQ-6` | `UI-01` | 宿主左栏实际宽度是 280 / 300 / 320？面板是否与别的面板共享侧栏？ | 影响 280px 下限与折叠行为 |
| `UQ-7` | `UI-08` | 下一步要不要可点击（跳到产物 / 触发 Gate 摘要）？ | 会改变「只读」边界与权限模型 |
| `UQ-8` | `UI-04` | `status` 是否要显示中文释义（draft / frozen / uat …）？ | 需要先有全仓统一术语表，不能 UI 自造 |

---

## 十二、自检与浏览器核对

### 12.1 原型门禁（等价执行）

本仓库不是流程仓，`scripts/check-ui-prototype.mjs` 默认要求 `docs/process` 结构；为了验证 HTML 交付完整性，在 `/tmp` 建了**临时门禁根**（不属于交付物、未写入仓库），把本目录的四个原型文件与 `spec.md` 复制成临时门禁根，再跑仓库自带脚本：

```bash
node scripts/check-ui-prototype.mjs --root /tmp/ppgate --pkg FEAT-001
```

输出：`10 ✓ / 0 ⚠ / 0 ❌`，退出码 `0`；完整原始输出见 `handoff.md` §自检。

### 12.2 浏览器核对

| 项 | 值 |
| --- | --- |
| 浏览器 | Microsoft Edge 157.0.4341.60（headless，Chromium） |
| 桌面视口 | 1280×900 |
| 窄屏视口 | 390×844（CDP `Emulation.setDeviceMetricsOverride`，`innerWidth=390` / `scrollWidth=390`） |
| 另看 | 492×1000（headless 最小窗口宽度） |
| 覆盖 | 6 个状态 ×（深色 / 浅色抽查）+ 折叠态 + 390 窄屏 |
| 核对了什么 | 元素出现 / 逐字文案 / 步骤 glyph 与颜色 / 面板宽度 / 折叠栏 / 无横向滚动 / 焦点顺序（Tab 走查） |
| 未核对 | Safari / Firefox；真机触屏；屏幕阅读器实际播报（只核了 ARIA 结构与属性） |
| 截图 | 只在 `/tmp` 做核对，**不作为交付物**；本目录没有 PNG / PSD |

### 12.3 结论

- 6 个状态全部可达：`?state=empty|full-gate1|managed-running|managed-gate4|fast|tampered`。
- 折叠态可达：`?collapsed=1`，也可点头部折叠按钮。
- 浅色 / 深色都可达：`?theme=light|dark`，也可点工具条按钮；生产跟随宿主。
- 文案硬约束逐条核对：无任何「系统替你批准」类表述；delegated 为琥珀空心 + 「Gate0 授权」+「不是人签」；托管说明逐字；空态无 Gate 术语。
- 遗留：见 §10 / §11；均不阻塞原型评审。

---

## 十三、主控裁定（2026-11-20）

| # | 裁定 | 落地口径 |
| --- | --- | --- |
| `UQ-1` | **v1 不显示 `qCount`** | 契约暂无该字段；不要从 PRD 文本猜。后续给 `process_status` 增加 `qCount` 后，UI-09 再显示。 |
| `UQ-2` | **`ai-hosted` = 空心 + 「AI 托管」徽标，绝不 done** | 与 `delegated` 同级但用不同语义色；只在验收 / 回归装置出现，正式开发不出现。v1 原型未画，落地时补第 7 态。 |
| `UQ-3` | **显示宿主当前选中包；无选中则最近更新包** | v1 不做多包切换器；多包场景先由对话侧切换，面板只读当前包。 |
| `UQ-4` | **v1 中文定稿；文案 key 化，后续跟随仓库 `lang`** | 已按 `W-01`–`W-30` 预留；英文版另立翻译稿，不混排。 |
| `UQ-5` | **快速路径的「交付」是里程碑，不是人签 Gate** | fast 契约只停 Gate0；文案避免出现「签 / 批准」。 |
| `UQ-6` | **默认 300px，范围 280–320px；折叠栏 48px** | 与宿主左栏同宽由宿主决定；面板不抢宽度。 |
| `UQ-7` | **v1 只读，下一步不可点击** | 跳转 / 打开产物后续单独立项；避免造出第二条签名入口。 |
| `UQ-8` | **状态位保留英文原文 + `title` 中文释义** | 待全仓统一术语表后再决定是否中文化，避免第二套状态机。 |
