# 设置页统一设计规范

适用版本：v0.7.8 起；适用范围：CLI Worker 设置中的各 CLI 连接页及以后新增的设置内容。以“账号与登录”“项目默认设置”的文字层级、原生控件，以及模型行的 16px 内容留白为基准。macOS 与 Windows 使用同一套样式。

本文记录当前约定，不另设产品版本号。修改参数时，同步实现与本文；实际检查结果写入 `doc/tasks.md`。

## 1. 文字层级

字体统一使用 Harness 的 `--dsw-font-family`。字号使用宿主对应主题 token；下表 px 指 CSS 像素，截图受系统缩放影响，不能直接拿物理像素当 CSS 像素。

| 层级 | 示例 | 字号 / 行高 | 字重 | 颜色与格式 |
| --- | --- | --- | --- | --- |
| CLI 页标题 | ZCode、Claude Code | 24px / 32px | 600 | 主文字色；h2；无默认 margin |
| 分区标题 | 账号与登录、项目默认设置、高级设置 | 14px token / 22px | 500 | 主文字色；h3；无默认 margin |
| 设置项标签 | 模型、思考强度、CLI 路径管理 | 14px token / 22px | 400 | 主文字色；普通 label/span，不再使用 h3/h4 |
| 设置项说明 | 新对话沿用的默认模型 | 12px token / 18px | 400 | 次级说明色 `--dsw-alias-label-tertiary` |
| 操作反馈 | 正在保存、保存成功、失败原因 | 12px token / 20px | 400 | 保持可读、允许换行；使用 status 语义 |

“高级设置”与前两个分区同级；其内部的“CLI 路径管理”与“模型”“思考强度”同级。不要靠加粗、放大或重复标签制造额外层级。

## 2. 间距与分隔线

距离以元素行框/内容框为测量边界，而非某个汉字的墨迹边缘；同一行中标签与控件保持垂直居中，多行文字正常增加高度。

| 参数 | 统一值 | 使用位置 |
| --- | --- | --- |
| 内容行上下留白 | 16px / 16px | 模型、强度、账号内容及展开后的路径内容 |
| 分隔线后的分区留白 | 16px | 线到下一个分区标题行容器外框 |
| 分区标题行容器最小高度 | 36px | 标题与刷新/展开按钮同排，22px 文字行框垂直居中 |
| 标题行后的间距 | 8px | 标题行到内容行外框 |
| 设置标签到说明 | 4px | 同一文字组内部 |
| 纵向文字组到输入框 | 16px | 路径等需要整行输入的设置 |
| 输入框到操作行 | 8px | 路径刷新/恢复自动识别 |
| 同排操作按钮之间 | 8px | 各设置操作行 |
| 左侧文字与右侧控件 | 24px；窄屏 12px | 模型、强度等左右布局 |
| 分隔线 | 0.5px，`--dsw-alias-border-l2` | 相邻设置项、相邻分区 |

必须遵守以下组合规则：

- 内容到分隔线由内容行自己的 16px 留白负责，分区之间不再叠加额外外边距。
- 相邻两个设置项之间只有一条线；最后一项与下一分区的边界也只有一条线，不能同时画末行底边和分区顶边。
- 36px 标题行容器底部到首个内容组外框为 **8 + 16 = 24px**。模型/路径对应文字组，账号对应 36px 控件行；普通分区与高级设置必须一致。同排文字在各自容器内居中，不把容器内部的居中留白误作边距差异。
- 模型文字组底部到分隔线为 **16px**，线到下一项文字组顶部也为 **16px**。长说明自然换行，仍保留相同上下 padding。
- 保存反馈只在保存中、成功或失败时出现。反馈与前一内容行之间复用已有留白，反馈底部距下一分隔线为 16px；空提示不保留空白行。
- 折叠容器外层不放内容 padding；留白随内部内容一起收起，避免高级设置折叠后留下额外空间。

## 3. 控件与对齐

| 控件 | 约定 |
| --- | --- |
| 模型 / 强度选择框 | 原生 md Button；宽度 `min(240px, 48%)`；靠右对齐 |
| 下拉菜单 | 原生 Menu；宽度实时跟随对应选择框，左右边缘对齐；最大高度 300px，内容可滚动 |
| 刷新 / 展开按钮 | 原生 md Button；36 × 36px；只按钮本身显示交互效果 |
| 路径输入框 | 原生 Input；占满当前内容宽度；与标签、分区线左侧和右侧对齐 |
| 路径操作行 | 靠右对齐；空间不足时允许换行；不挤压或截断输入框 |
| 开关 | 使用原生 Switch 的尺寸与交互，不改造成自定义图形 |

不同设置内容使用横向或纵向布局，但复用同一文字、内容留白及分隔线规则。不要给某个 CLI 单独写字号或修补 margin。

## 4. 交互与状态

- 模型和思考强度选择后自动保存；页面初读或刷新目录不写偏好。保存失败保留选择和错误，允许重新选择重试。
- 高级设置初始折叠，仅右侧箭头负责展开/收起；标题文本不是整行按钮。
- 折叠采用 220ms 高度过渡、180ms 透明度过渡；箭头旋转 220ms。减少动态效果偏好下关闭过渡。
- 收起内容不可被键盘聚焦；输入保留可访问名称，说明与输入建立关联。
- 路径管理保留说明、输入、恢复自动识别和刷新，不重复显示“CLI 路径”或单独的来源标签。
- 颜色、圆角、悬停和焦点使用 Harness 主题与原生组件，不写死浅色背景或系统专属字体。

## 5. 实现入口与扩展步骤

- `src/client/styles.ts` 的 `settingsStyles`：公共排版参数、标题、内容行、账号、模型菜单与反馈。
- `src/client/management-styles.ts`：高级设置折叠与纵向路径布局，使用公共参数。
- `src/client/settings-dialog.tsx` / `cli-executable-settings.tsx`：分区结构、标签、原生控件与可访问交互。

新增内容时：

1. 先确定是分区标题还是普通设置项，不凭视觉感觉新增标题级别。
2. 复用公共分区、文字组、内容行及间距变量；需要纵向输入时沿用路径区域的结构。
3. 明确唯一的分隔线归属，不用空元素、空反馈或额外 margin 补位置。
4. 只针对改动做最小检查：实际界面对齐、展开/折叠、溢出，以及必要的相关回归和隔离构建；纯样式不增加只检查 class 字符串的测试。
5. macOS 与 Windows 的布局应一致；未检查的平台或状态如实写入验证记录。全量验收仍只在获准的版本发布时执行。

本规范约束设置表单的共同基础；智能体角色卡片和原生账号终端有各自内容结构，扩展其设置表单时仍复用上述文字层级与间距，不将 CLI 表单排版直接套到终端画面。