# Browser Kitten · Design

侧栏 UI 的设计基准。新增或修改界面时先读本文，再复用现有组件与 token。本文记录现有 UI 规范；权限、执行、存储合同仍以 `AGENTS.md` 和领域文档为准。

## 1. 视觉方向

**Quiet Black / Quiet Light：安静的黑白工作台，少量橙色提示交互与状态。**

内容和操作优先。通过表面明度、细边框、间距和字重建立层级，不靠渐变、发光、大面积品牌色或装饰动画。可点击的常驻入口必须像控件，不能看起来像禁用的灰色说明。

保留猫形品牌标识。现有点选、截图图标沿用；新增图标保持简单、同尺寸、同笔画重量，不为了填满按钮增加装饰。

## 2. 颜色与表面

唯一颜色来源是 [tokens.css](src/sidepanel/css/tokens.css)。组件引用语义变量，不复制颜色值或另建主题。

- 页面底色 `--paper`：深色 `#050506`，浅色 `#f4f3ef`。
- 正文 `--ink` / `--text`：深色 `#f4f3ef`，浅色 `#111113`。
- 卡片 `--surface` / `--bg-elevated`：深色 `#111113`，浅色 `#ffffff`。
- 次级表面 `--surface-2`：深色 `#1c1c1e`，浅色 `#eceae4`。
- 分隔线 `--border`，可点击边界 `--border-strong`。普通边框 1px。
- 次要元数据用 `--text-muted`，不能用它表示默认可操作按钮的主标签。
- 橙色 `--signal` / `--accent` 为 `#ff6a00`，用于键盘焦点、选中边界和需要关注的运行状态。
- 成功、警告、错误沿用 `--green`、`--amber`、`--danger`，并提供文字或图标，不能只靠颜色说明结果。

普通表面不投影，使用 `--shadow` / `--shadow-card`（当前为 `none`）。弹窗通过遮罩和边框分层。主按钮使用 `--ink` 背景及 `--paper` 文字，浅色主题自动反转。

## 3. 尺寸与排版

- 字体使用 `--font`；代码、结构化定义和原始输出使用 `--font-code`。
- 正常控件文字 12–13px；区域标题约 15px。11px 只用于紧凑字段标签和元数据，不作为主操作字号。
- 主操作字重 650–700；正文保持普通字重，不整片加粗。
- 常用间距沿用 `--space-1/2/3/4`，对应 4 / 8 / 12 / 16px。紧凑按钮组可用 6px。
- 容器圆角 `--radius`（14px），入口与卡片 `--radius-sm`（10px），小控件 `--radius-xs`（6px）。
- 顶部入口高度统一为 `--density-pick-h`，正常 34px、compact 30px；字级和内边距跟随相应 `--density-pick-*`。

长名称保留单行省略和完整 tooltip / accessible name。结果、错误及必要说明允许换行，不能将关键失败原因截断。

## 4. 按钮与交互

**主操作**：实心黑白反色按钮，例如点选、发送、弹窗最终的添加／更新。同一区域避免多个相互竞争的主按钮。

**次级操作**：表面底色、细描边、正常文字颜色。截图、工具、Workflow 使用同一高度、圆角和交互规则。「⋯」是同高度方形管理按钮，保留可访问名称。

**辅助操作**：删除条目、关闭、展开等可使用低强调图标按钮；需要明确命中区域与说明。权限盾牌属于顶栏状态入口，不挤进聊天输入工具栏。

- Hover：轻微改变背景或边框；已有快捷按钮允许上移 1px。
- Pressed：短促反馈，不移动整块布局。
- Focus-visible：清晰橙色轮廓，不能去掉 outline 后不提供替代。
- Disabled：降低强调并真实禁用，不能只更改颜色。
- 系统要求 reduced-motion 时关闭非必要动画与过渡。
- 确认类操作使用明确动词；试运行说明真实页面副作用，发布必须由用户点击添加／更新。

## 5. 页面职责与布局

### 顶栏与快捷入口

顶栏保留品牌、当前页面、权限盾牌、齿轮设置入口；「⋯」用于快捷区的个人库管理。快捷区顺序为点选、截图、工具、Workflow、个人库管理。工具和 Workflow 可被已固定的用户条目替换；替换后维持原有按钮样式。

五个快捷入口始终保持同一行，不通过换行增加顶部高度。窄栏优先缩减横向留白与间距，按钮允许收缩，长名称省略并保留完整 tooltip / accessible name；不能隐藏常驻入口或产生横向溢出。使用 `.panel` 的 container query，不按显示器宽度判断。选区摘要、固定展开与清空另行排列，不能挤压常驻入口。入口网格只在 `sidepanel.css` 定义，避免旧布局规则覆盖新入口。

### 点选与资料组

点选得到对象；快捷操作直接处理对象；资料组保存和组织；参考让 Bot 理解对象。资料组与对话引用都不授予浏览器执行权限。

无内容时不展示资料组或空抽屉。有内容后按对象、适用操作、文字剪贴板、收集位置排列。不要恢复用户已要求删除的灰色解释段落；必要说明放 tooltip、可访问描述或相关帮助中。对象名称、计数和操作标签仍可见。

点选后短暂展开、随后收起；悬停、固定与键盘焦点遵守现有抽屉规则。菜单操作期间不得误收起。

### 对话与附件

输入任务不要求先点选或创建资料组。参考计数只来自实际绑定。上传和粘贴预览必须位于 `.composer-inner` 内，随输入框移动，不能掉到聊天框外。删除预览只改变待发送附件。

打开对话后，消息直接落在 `--paper` 上：不画 `.session-thread` / `.task-card` 的大边框井、也不再给卡片套呼吸流光。用户气泡保持橙色胶囊；助手回复是裸散文。运行中的进度说明也是裸散文（与回答同字号、正文字色），和灰色小图标活动行在同一条时间线里按顺序穿插；回合结束后与活动行一起折成一行，展开时带 HH:MM 时间。不进思考块，不画成卡片或气泡。首页（无会话线程）不要再长出第二张卡；输入坞仍停在 composer。

滚动以 [layout.css](src/sidepanel/css/layout.css) 为准：首页由 `#panelScroll` 滚动，打开对话后由 `.task-body` 滚动，保留会话标题与输入区域。不要为每张普通内容卡新建滚动容器。代码预览、附件列表、弹窗编辑器可有明确的高度限制。

可恢复的持续任务放在输入区上方的独立抽屉（`footer.composer > #durableTaskDock`），不插入聊天顶部或消息时间线。抽屉与单张任务都默认折叠，展开状态按会话保留；折叠行用短标题、计数与状态，长目标单行省略并保留完整 tooltip。展开后才能看步骤、来源、进度和操作。抽屉内容整体限高 `min(38vh, 320px)` 并独立滚动，单张任务不另建滚动容器，滚轮不转送聊天。继续使用中性表面、细边框和橙色焦点，不加大面积橙色卡框。

对话滚动条是 overlay，不占布局：静止时隐藏；滚轮 / 触控 / 触摸板滚动时出现，最后一次滚动后约 700ms 再隐去。只点亮**滚动条本身**（对话 6px / 思考块 4px 的 thumb），不是整列轨道。`.task-body` 与思考块 `.think-body-wrap` 各有一条星光条，互不连动——在思考块里滑记录只点亮块内小条，不会点亮外层对话条。星尘裁在 thumb 里（`overflow: hidden`），不洒到正文。`prefers-reduced-motion` 保留渐变与光晕，冻结粒子。不是橙色霓虹管，也不再绕卡片跑彗星。

### 个人库与 Workflow

个人库、参数输入、流程编辑沿用相同表面、圆角和按钮层级。窄栏表单允许折行或堆叠，名称与错误信息不能撑出侧栏。草稿编辑区不因运行事件重新绘制并丢失输入。

「工具」是独立的确定性脚本；「自动化」是可录制、可循环的结构化流程；「Agent 任务」通过模型对话执行。界面必须区分这三者。运行状态展示当前步骤、已通过的检查、失败原因及恢复位置；用户确认不能显示成系统已验证。运行时不能让编辑弹窗遮住宿主审批。

## 6. 实现位置与验收边界

- [tokens.css](src/sidepanel/css/tokens.css)：颜色、字体、圆角、间距、密度。
- [layout.css](src/sidepanel/css/layout.css)：高度链、主要滚动与响应式布局。
- [motion.css](src/sidepanel/css/motion.css)：动效及 reduced-motion。
- [sidepanel.css](src/sidepanel.css)：组件外观、快捷入口与个人库布局。
- [sidepanel/README.md](src/sidepanel/README.md)：模块、事件与交互合同。

CSS 加载顺序保持 tokens → layout → motion → components。优先合并同一组件的已有规则，避免不断追加高优先级覆盖。旧界面尚未完全收敛的样式随实际改动修正，不以统一设计为理由重写无关模块。

提交前运行相关 Node 回归和差异检查。实际外观由 Chrome 验收：深浅主题、中英文、常规与窄侧栏、空选区与混合选区、长固定名称、键盘焦点、弹窗和粘贴附件。纯文案或样式不新增快照测试；Node 通过不代表真实浏览器视觉验收通过。