# Issue2PR 工作台视觉方案

## 状态

- 方案状态：已通过产品负责人交互确认，作为下一轮 `client.js` 视觉落地的设计依据。
- 交互 Demo：[../design-demo.html](design-demo.html)
- 设计方法：`design-taste-frontend`
- 适用范围：项目 / 运行 / 产物 / 配置 / 说明五个工作台页面，以及插件品牌标识。
- 不适用范围：业务 API、流水线状态机、产物落盘规则、复核语义。落地时不得为视觉重构改变这些行为。

## 设计判断

Reading this as：面向研发与运维的 Issue-to-PR 证据链工作台，采用克制、优雅、可扫读的工程系统界面；优先级是状态识别、证据入口和操作确定性，而不是营销式视觉表现。

- `DESIGN_VARIANCE: 4`：结构稳定，避免装饰性变化。
- `MOTION_INTENSITY: 2`：仅保留状态、悬停、页面切换的短过渡。
- `VISUAL_DENSITY: 6`：信息紧凑，但每个区块保留清晰边界和呼吸感。

## 设计语言

### 视觉基调

- 底色使用暖灰瓷面（`#ecebe6` / `#f5f5f2`），深色主题使用近黑墨绿灰。
- 卡片使用半透明白面板与 1px 发丝线，不用重阴影和大圆角。
- 全局圆角控制在 3px，胶囊标签使用小圆角矩形，避免气泡化。
- 主色只保留一个绿色 `#177b62`，用于当前态、主动作和关键证据；状态色仅用于状态。
- 中文界面使用系统 UI 字体，编号、路径、耗时、Trace 使用等宽字体。
- 页面标题靠左，说明文字紧随标题，先给判断，再给数据。

### 品牌与图标

- Header 左侧使用 Issue2PR 专属 SVG 标识，尺寸固定 `24x24`。
- 标识与 `Issue2PR` 文字垂直居中，间距 `10px`，不额外加容器底色。
- 标识沿用侧栏入口的三节点分支骨架，以两条短线表达 Issue 文档，取消封闭文件轮廓。
- 主体描边继承中性色，PR 目标节点使用主题绿色，确保浅色与深色主题都清晰。
- Demo 与插件 favicon 使用同一标识，避免品牌入口不一致。

## 设计令牌

```css
:root {
    --shell: #ecebe6;
    --porcelain: #f5f5f2;
    --porcelain-strong: #ffffff;
    --panel: rgba(255, 255, 255, 0.84);
    --panel-strong: #ffffff;
    --ink: #20211f;
    --ink-soft: #474a45;
    --muted: #767a73;
    --hairline: #deddd6;
    --hairline-soft: #e9e8e1;
    --neutral-soft: #eeeeea;
    --accent: #177b62;
    --accent-soft: #e5f0eb;
    --good: #27703d;
    --warn: #90620b;
    --error: #a43c34;
    --shadow: 0 12px 38px rgba(32, 33, 31, 0.08);
}

html[data-theme="dark"] {
    --shell: #101110;
    --porcelain: #151614;
    --porcelain-strong: #1b1d1a;
    --panel: rgba(27, 29, 26, 0.88);
    --panel-strong: #1b1d1a;
    --ink: #eceae4;
    --ink-soft: #c8cbc3;
    --muted: #8f948a;
    --hairline: #343731;
    --hairline-soft: #2a2c28;
    --neutral-soft: #232521;
    --accent: #67b79d;
    --accent-soft: rgba(103, 183, 157, 0.14);
    --good: #85c99a;
    --warn: #d9ab62;
    --error: #e59b91;
    --shadow: 0 14px 44px rgba(0, 0, 0, 0.3);
}
```

落地到 `client.js` 时，应保留 `.i2p` 命名空间，并把令牌集中定义在组件根节点；深色主题继续跟随宿主主题，只显式覆盖宿主对比不足的说明文字。

## 页面方案

### 1. 项目总览

- 页面标题从「项目台账」统一为「项目总览」。
- 第一屏给仓库健康、契约状态、待处理事件，不先展示长列表。
- 信息顺序：页头与操作 → 项目目录 → 项目契约 → 最近事件。
- 项目行保留仓库、健康、契约、最近运行四个可扫读字段；搜索与新建入口固定在目录头部。

### 2. 执行路线

- 运行页不再用长表展示 11 个阶段，改为整宽可扫读路线。
- 桌面约 `1200px` 宽下使用 6 列，11 个阶段自然分为 2 行；`880px` 下降为 3 列。
- 阶段卡片包含编号、名称、一句职责；已完成、当前、待执行、复核门、失败必须一眼可辨。
- 鼠标设备悬停阶段卡片时上移 `2px` 并增加轻阴影；选中态必须保留绿色边框。
- `prefers-reduced-motion` 下禁用阶段卡片位移，触摸设备不启用 hover 动效。
- 「当前阶段」与「运行证据」依次放在路线下方，不再挤在右侧窄栏。
- 主操作固定在页头：查看日志、继续执行、停止、回滚；证据入口从当前阶段直接链到产物。

### 3. 产物工作台

- 左侧目录固定 `310px`，右侧为选中产物详情，窄屏自动单列。
- 目录必须是真实树状层级：`run_4821 / 06-implementation / patch-001.diff`。
- 目录节点可点击展开 / 收起；箭头随状态旋转，并使用 `aria-expanded`、`aria-controls`。
- 根目录收起时隐藏全部子级；嵌套目录可独立收起，不影响父级其它文件。
- 目录树外层不显示边线、阴影或悬浮位移；可点击的目录与文件行保留背景反馈。
- 文件行显示图标、名称、大小或状态；当前选中文件使用浅绿当前态。
- 右侧详情先给产物元信息，再给只读内容；大文件沿用现有 200KB 在线预览边界。

### 4. 阶段配置

- 左侧为阶段索引，右侧为当前阶段配置，避免一次性展开全部复杂表单。
- 阶段索引保留编号、名称和复核门标识；P5 / P6 / P9 / P11 必须独立可识别。
- 右侧按「模型与提示词 / 执行参数 / 委托配置」分组，说明文字解释影响面。
- 修改配置只影响后续执行，视觉上不暗示立即修改历史 Run。

### 5. 工作流说明

- 面向新用户，按「理解与规划 → 实施与交付 → 边界规则 → 失败路径」组织。
- 每节先给一句话结论，再列关键规则；避免把 README 原文整段搬进界面。
- 失败路径必须说明 P10 只分类与建议，不自动 replan。

## 组件规则

- 主动作：实心绿、白字、3px 圆角；同一区域最多一个。
- 次动作：透明底、发丝线、深色字；悬停只提升底色。
- 面板：半透明底、1px 发丝线、3px 圆角、轻阴影；标题与计数同行。
- 状态胶囊：浅底 + 深状态字；禁用彩色边框和大面积色块。
- 数据字段：`ID`、阶段号、路径、耗时、Trace 使用等宽字体和表格数字。
- 树节点：目录箭头独立可点击，文件图标保持方形，层级缩进与左侧竖线表达父子关系。
- 焦点：所有可交互元素保留 `focus-visible` 外框，颜色使用主色。
- 动效：页面进入 `180ms`，状态与悬停 `120ms - 180ms`；不得使用循环动画。

## 落地顺序

1. 在 `client.js` 建立设计令牌、主题映射、App Header、官方 `I2P` 标识与五页导航。
2. 替换项目 / 配置 / 说明页的页面骨架和基础组件，保持既有数据绑定不变。
3. 重排运行页为整宽阶段路线，并接入真实阶段状态与证据入口。
4. 重排产物页为树状目录与详情双栏，实现目录展开 / 收起状态。
5. 清理旧视觉中与本方案冲突的组件样式，避免新旧两套卡片、按钮、状态胶囊并存。
6. 做明暗主题、窄屏、键盘焦点、Console 与既有 UI 状态测试回归。

## 验收清单

- 五个页面标题、信息顺序、空态与操作入口与 Demo 一致。
- `1257x1320`：运行页 11 阶段为 2 行，无横向溢出。
- `880x1000`：运行页阶段路线自然换行，无横向溢出。
- 产物树根目录与嵌套目录均可展开 / 收起，文件计数与实际层级一致。
- 明暗主题下正文与说明文字对比度可读，Logo 随主题色正确。
- Console 为 `0 errors / 0 warnings`；页面切换与目录展开不产生运行时错误。
- 既有 `npm test` 全部通过；不得改变 API、状态机、产物路径和复核语义。