# DSH 插件 UI 规格

版本：1.2 · 2026-10-04。本文件为交付副本，与工作区根目录的 DSH-PLUGIN-UI-SPEC.md 保持一致；修改共享规范时同步此副本。

## 基准与适用范围

以 `dsh-computer-use/src/client/index.ts`、`select.ts` 的配置页为基准。桌面插件继承 DSH 主题，远程独立应用采用同一强调色与控件规则。强调色已在全部带界面的插件中统一（1.2）；其余条目各仓库逐步迁移。

## 颜色与主题

| 语义 | 桌面 | 独立浅色 | 独立深色 |
|---|---|---|---|
| 背景 | 宿主背景变量 | `#FAF9F5` | `#242321` |
| 卡片 | 宿主分层背景变量 | `#FFFEFA` | `#2D2B28` |
| 正文 | `--dsw-alias-label-primary` | `#292724` | `#F0EEE8` |
| 次要文字 | `--dsw-alias-label-secondary` | `#77736C` | `#B5AFA6` |
| 边框 | `--dsw-alias-border-l2` | `#E4E0D8` | `#454039` |
| 主操作 | 用户所选强调色 | 用户所选强调色 | 用户所选强调色 |
| 错误/危险 | 宿主错误变量 | `#B34337` | `#EF9181` |

### 强调色（用户可切换，各插件共用）

强调色不是固定值，由用户在三套中选择，默认陶土橙。选择只有一份：在任意一个插件的设置页里改，所有插件的界面一起变，并即时生效。

| 名称 | 强调色 | 强调色上的文字 |
|---|---|---|
| 陶土橙（默认） | `#D97757` | `#FFFFFF` |
| 蓝色 | `#3D63E6` | `#FFFFFF` |
| 黑色 | 宿主正文色 `--dsw-alias-label-primary`（浅色主题近黑，深色主题近白） | 宿主背景色 `--dsw-alias-bg-base` |

- 选择保存在浏览器的 `localStorage`，键名 `copylee.dsh.accent`，值为 `orange`、`blue` 或 `black`；改动时在 `window` 上派发 `copylee-dsh-accent` 事件。
- 每个插件启动时把当前选择画成 `<body>` 上的两个变量：`--cl-accent`（强调色）和 `--cl-accent-ink`（强调色上的文字）。宿主的主题变量也定义在 `<body>` 上，所以黑色能跟随宿主的深浅色主题，不需要插件自己判断主题。
- 样式里只写变量，并带默认值：`var(--cl-accent, #D97757)`、`var(--cl-accent-ink, #fff)`。不得写死色值；悬停用 `color-mix(in srgb, var(--cl-accent) 88%, #000)`，淡色底用 `color-mix(in srgb, var(--cl-accent) 9–12%, transparent)`。插件可以用自己的前缀变量转一层（如 `--rc-accent: var(--cl-accent, #D97757)`）。
- 强调色用于：主按钮、开关和选中状态、链接、焦点框、复选框与单选框。成功、警告、错误、信息标签用宿主的语义色，危险操作始终用语义危险色，都不随强调色变化。
- 切换入口是一排圆形色块（单选语义，带名称），放在设置页底部或外观设置旁边，并注明“对全部插件生效”。
- 新增配色时必须同时给出强调色和它上面的文字色，并保证在深浅两种主题下对比度足够。
- 参考实现：各插件的 `src/client/accent.ts`（内容相同，改动时一起改）；`dsh-free-search` 是手写 JS，对应 `lib/client.js` 里的 accent 区块。
- 需要在宿主一侧保存选择的插件（`dsh-remote-control` 要把配色发给配对页和手机）另外保存一份，并与浏览器里的选择双向同步，见 `dsh-remote-control/src/client/accent-sync.ts`。独立页面（配对页、手机界面）没有宿主变量，黑色在深色主题下用 `#F0EEE8`、文字用 `#242321`。
- 渲染对话内容的插件（`dsh-better-display`）不使用强调色，链接和引用跟随宿主主题，与对话区保持一致。

成功、警告、错误优先跟随宿主语义变量；只用于表达状态，不能另立页面主色。主题选择提供浅色、深色和跟随系统。二维码保持白底与深色码点。不得用浅色按钮背景作为唯一的选中信号。

## 布局、字形与间距

- 桌面配置正文 13px、标题 20px、卡片标题 15px；手机正文与输入框至少 16px，辅助说明可用 13–14px。
- 使用本地系统字体与 SVG 图标，不请求外部字体或图标服务。中文正文采用清晰无衬线字体。
- 间距以 4px 为步长，主要使用 8、12、16、20、24px。卡片内边距 16px，卡片圆角 12px，控件圆角 8px。
- 配置页最大内容宽度 880px。窄屏标签、输入和说明纵向排列，所有弹层约束在视口内；禁止常驻宽侧栏挤压手机内容。
- 手机主要触控目标至少 44×44px；正文区域不得水平溢出，代码和表格在局部容器中横向滚动。

## 控件与反馈

- 主按钮使用当前强调色和对应的文字色；次按钮使用透明或分层背景与细边框；危险操作以文字和语义颜色标识，并在不可恢复时要求明确确认。
- 下拉菜单与可编辑选择器使用统一边框、圆角与菜单面板；不得混入外观突兀的 datalist。手机系统选择器可用于原生选择体验，但触发器必须符合页面规格。
- 开关与复选框必须有完整可点击标签。选中、禁用和加载态有文字或语义属性；请求中阻止重复提交。
- 焦点框可见且对比清晰，键盘可操作；抽屉与弹窗正确管理焦点、关闭和返回。
- 成功反馈短暂且不遮挡内容；失败就近呈现具体原因和重试。状态区分未开启、启动中、验证中、已连接、失败和断开。
- 空状态解释当前情况并提供真实可执行的下一步；不得放置无行为按钮或虚构成功提示。

## 手机与独立远程应用

- 顶部标题和抽屉导航，底部聊天输入区；设置采用分类列表与全屏详情，返回键回到上一层。
- 使用动态视口与安全区，软键盘不遮挡输入框、发送或审批操作。中文组合输入期间不提交，手机 Enter 换行。
- 切后台与断网后重新读取宿主状态，仅恢复读取和订阅；消息、审批、插件安装等写操作不自动重放。
- 用户向上浏览历史时不抢滚动；提供“回到最新”按钮。减少动画偏好下关闭过渡效果。
- 浏览器端保留草稿与主题选择；凭据只在提交期间保留内存，不进入 localStorage、日志或错误详情。

## 验收

检查浅色/深色、360/390/430px、横屏、桌面宽屏、长中文、长地址和代码、软键盘、焦点、禁用、错误、空状态。自动化视口检查不能写成手机真机验收。