kevin/deepseek-harness
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rescan rebased documentation hierarchy

Browse Source
This commit is contained in:
Turtle
2026-08-05 16:16:57 +08:00
parent 012bb0a549
commit 8af3babaea
304 changed files with 1091 additions and 1983 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/web-styling.zh.md
+15 -99
View File
@@ -1,109 +1,25 @@
# Web GUI 样式规范
# Web UI 样式参考
[English](web-styling.md) | 中文
> **【token 体系已换代——§1 表格仅历史参考】** 本文的 `--bg-*`/`--text-*`/`--accent` token 族与其宿主包 `packages/client/web-ui` 已随插件化重构退役。现行 token 唯一来源=`packages/client/ui-theme/src/styles/` 的 `--dsw-*` 体系（static 色阶+alias 语义层，暗色=`body[data-ds-dark-theme]` 覆写），sheet 即权威、组件对账以它为准。**仍然有效**：工程约束（CSS Modules + clsx、无组件库、无 tailwind、组件禁 hardcode 色值）、字号成对写行高、间距 4 倍数、代码字体栈末位不放 monospace。
本文规定浏览器客户端包的样式职责归属与组件规则。当前 token 值位于 [`packages/client/ui-theme/src/styles/`](../packages/client/ui-theme/src/styles/)；本文不重复这份由源码生成的清单。
> 状态：原「活文档」（随 `packages/client/web-ui` 演进）。视觉基线源自对 deepseekchat 前端仓的实测调研。框架决策与工程约束由 [web-styling-system RFC](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md) 拍板，本文不重复论证。
## 职责归属
## 1. 设计 token 表（权威定义）
[`ui-theme`](../packages/client/ui-theme/README.md) 负责 `--dsw-*` 静态色阶、语义别名、排版、动效、渐变、阴影、滚动条样式以及明暗主题偏好。[`ui-layout`](../packages/client/ui-layout/README.md) 将解析后的主题快照应用到文档。功能包使用语义别名，不得另行定义全局主题。
所有 token 住 `packages/client/web-ui/src/style/global.css`：`:root` 亮色实值，`[data-theme='dark']` 块覆盖同名变量（未补全前列为占位）。组件 CSS 只引 token，不出现字面量色值。
全局样式表归 `ui-theme/src/styles/` 所有。组件样式以 CSS Modules 形式放在组件旁。当某个值属于组件自身的布局或呈现契约时，组件可以定义局部自定义属性；共享颜色、排版、层级和动效属于主题包。
### 1.1 颜色（两层：注释里是 base 色板出处，变量名即语义别名）
## 组件规则
| token | 亮色实值 | 暗色（占位） | 用途 |
| --- | --- | --- | --- |
| `--bg-base` | `#ffffff` | `#151517` | 页面底 |
| `--bg-layer` | `#ffffff` | `#232324` | 浮层/面板 |
| `--bg-sidebar` | `#f9fafb` | `#1b1b1c` | 侧边栏底 |
| `--text-primary` | `#0f1115` | `#f9fafb` | 正文 |
| `--text-secondary` | `#61666b` | `#cfd3d6` | 次要文字 |
| `--text-tertiary` | `#81858c` | `#adb2b8` | 辅助/说明 |
| `--border-l1` | `rgba(0,0,0,.04)` | `rgba(255,255,255,.06)` | 弱分隔（侧边栏右缘） |
| `--border-l2` | `rgba(0,0,0,.1)` | `rgba(255,255,255,.12)` | 常规边框 |
| `--hover-bg` | `rgba(38,49,72,.06)` | `rgba(255,255,255,.08)` | hover 态底 |
| `--active-bg` | `rgba(38,49,72,.1)` | `rgba(255,255,255,.14)` | 按压/激活态底 |
| `--accent` | `#3964fe` | `#5686fe` | 品牌蓝（deepseek-500；暗提亮一档） |
| `--accent-soft` | `#edf3fe` | `#28313f` | 淡品牌底（强调块） |
| `--accent-item` | `#e4edfd` | `#35363a` | 侧边栏选中条目底 |
| `--bubble-bg` | `#edf3fe` | `#2c2c2e` | 用户消息气泡底 |
| `--ok` / `--error` / `--warn` | `#22c55e` / `#ec1313` / `#f59e0b` | 同值 | 语义状态色 |
| `--text-on-solid` | `#ffffff` | 同值 | 实色底（accent/error 徽标等）上的文字 |
| `--ok-soft` / `--error-soft` | `#e6faed` / `#fee2e2` | `#233c2c` / `#570c0c` | 语义状态软底（徽章）；green-100/red-100，暗为 900 档 |
| `--color-frame-mux` / `--color-frame-host` | `#8250df` / `#0969da` | 同值 | RPC 调试面板方向色（自有，非基线） |
| `--frame-mux-soft` / `--frame-host-soft` | `rgba(130,80,223,.1)` / `rgba(9,105,218,.1)` | 同色 `.24` | 方向色软底（徽章） |
| `--scroll-color` / `--scroll-color-hover` | `rgba(0,0,0,.08)` / `.15` | `rgba(255,255,255,.15)` / `.24` | 滚动条（`.scrollable` 专用） |
- 使用 CSS Modules 和 `clsx`；不得添加组件库或 Tailwind。
- 功能组件使用 `--dsw-alias-*` 语义 token。不得复制静态色板值或在其中写入颜色字面量。
- 功能组件 CSS 不得包含主题选择器。明暗主题覆盖属于主题所有方。
- 字体大小必须与行高配对；已有角色匹配时使用主题排版变量。
- 当组件契约要求保留列结构时，源码文本、终端输出和 diff 行不得换行；使用共享滚动条样式，不得定义组件专用滚动条选择器。
- 呈现规则写在 CSS 中。React 内联样式可以传递组件局部自定义属性值，但不得编码主题分支。
- 添加过渡动画或仅悬停可见的控件时，保留清晰可见的键盘焦点和减少动态效果行为。
### 1.2 非颜色
## 变更系统
| token | 值 | 说明 |
| --- | --- | --- |
| `--font-ui` | `Inter, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif` | 正文栈 |
| `--font-mono` | `Menlo, Monaco, Consolas, 'JetBrains Mono', 'Courier New', sans-serif` | 代码栈；**末位不放 monospace**（防 Windows 中文回退宋体） |
| `--fw-strong` | `600` | 粗体统一权重 |
| `--ease` | `cubic-bezier(.4,0,.2,1)` | 唯一缓动曲线 |
| `--dur` / `--dur-fast` / `--dur-slow` | `.2s` / `.1s` / `.3s` | 过渡三档 |
| `--radius-s` / `--radius-m` / `--radius-l` / `--radius-bubble` / `--radius-xl` | `8px` / `12px` / `16px` / `22px` / `24px` | 圆角语义档：小控件 / 列表条目与面板内块 / 浮层 / 气泡 / 输入卡片（基线 inputWrapper 同值）；胶囊直接写 `999px` |
| `--shadow-panel` | `0 0 1px rgba(0,0,0,.2), 0 0 4px rgba(0,0,0,.02), 0 12px 32px rgba(0,0,0,.08)` | 浮层阴影（基线 lv3） |
| `--shadow-float` | `0 0 1px rgba(0,0,0,.24), 0 4px 12px rgba(0,0,0,.06), 0 16px 48px rgba(0,0,0,.16)` | 强浮动面板（lv3 加强档，如 RPC 调试浮层） |
| `--shadow-card` | `0 4px 10px rgba(0,0,0,.02), 0 2px 4px rgba(0,0,0,.04)`；暗色 `none` | 输入卡片微阴影（基线：亮色同底靠边框+微影区分，暗色靠提亮底、阴影关闭） |
字号与间距**不 token 化**（基线仓同款决策）：字号在组件里写 px 且**成对写行高**，常用对 16/24（气泡）、14/22（UI 默认）、12/18（辅助）；间距用 4 的倍数。
## 2. 视觉基线（源自 deepseekchat）
- 侧边栏：宽 `260px + 1px` 右边框（`--border-l1`）；底色 `--bg-sidebar`。
- 侧边栏条目：高 `40px`、圆角 `--radius-m`、字号 14px；hover 底 `--hover-bg` 或 sidebar 专属灰、**选中底 `--accent-item` 且不改文字色**。
- 侧边栏分组标题：12px / weight 500 / `--text-tertiary` / sticky 顶部（底色同侧边栏遮滚动内容）。
- 会话列：`max-width: 840px` 居中，<1024px 降 712px。
- 消息流：**仅用户侧有气泡**——`--bubble-bg` 底、圆角 `--radius-bubble`、padding `10px 16px`、字号 16px/24px、`max-width: calc(100% - 88px)`；**助手侧纯文档流无底色**。
- 消息操作条：默认 `opacity: 0`，父块 hover/focus-within 淡入（`--dur` + `--ease`）。
- 输入卡片：与会话列同宽（840px，<1024px 降 712px)居中悬浮（距底留白带）；圆角 `--radius-xl`、边框 `--border-l2`、底 `--bg-base`、阴影 `--shadow-card`；内部上下两段=textarea（16px/24px，min 2 行 max 14 行=336px，镜像 div 自增高）+ 操作行（右下嵌 34px 主圆钮）；focus 无边框/阴影变化（基线同款）。
- 输入主按钮（拍板 2026-07-20 三连，视觉参照 Codex App）：32px 实心正圆图标钮（内联 SVG）——空闲=`--accent` 底白↑箭头「发送」，运行中原地变 `--accent-soft` 底 accent ■「停止」（同色系不告警、不用红）。**运行中锁输入**（拍板 3，取代早先 hover 菜单方案）：textarea disabled（灰、草稿内容保留可见）、无任何排队/插话菜单，停止是唯一动作；turn 结束解禁并 refocus。键盘 Enter=发送、Ctrl/Meta+Enter=换行（运行中键盘路径随锁失效）。
- 滚动条：近隐形、hover 加深、`scrollbar-gutter: stable` 不占布局（统一走 `.scrollable`，见 §3-9）。
- RPC 四象限方向符（官方视觉词汇，空间隐喻：上=去 server、下=来自 server；单线=客户端发起的交互、双线=服务端发起的交互）：
| 符号 | 象限 | 徽章配色 |
| --- | --- | --- |
| `↑` | client-request（unary 出站） | `--accent` / `--accent-soft` |
| `↓` | server-response（unary 回包） | ok `--ok`/`--ok-soft`，error `--error`/`--error-soft` |
| `⇟` | server-request（下行流） | mux `--color-frame-mux`/`--frame-mux-soft`，host `--color-frame-host`/`--frame-host-soft` |
| `⇞` | client-response（对 server request 的回应） | `--accent`/`--accent-soft` 降透明度 |
## 3. 样式编码规范（review 对照打勾）
1. 颜色/圆角/动效/字体栈只引 §1 token；组件 CSS 出现字面量色值即打回（渐变遮罩等特效除外，须注释说明）。
2. 组件 CSS 禁止出现 `[data-theme]` 选择器；暗色差异只在 global.css token 表做。确需按主题换非 token 值（渐变端点等），组件定义局部 CSS 变量、主题块只覆写变量（变量桥）。
3. 类名 camelCase；状态类用单形容词（`.active` `.show`），由 clsx 挂载：`clsx(styles.x, cond && styles.active, className)`。
4. 对外组件必须透传 `className` 并合入根元素。
5. 禁用 `composes`；复用靠 token 与组件抽取。
6. `:global` 仅用于穿透第三方/跨包类名；禁止用它定义新全局类。
7. 交互过渡一律 `var(--dur*) var(--ease)`，只过渡 opacity / transform / 背景色 / 阴影；纯 hover 展示型元素包 `@media (hover: hover)`。
8. hover/active 底色优先用透明度制 token（叠任意海拔底色都成立），不新造实色灰。
9. 滚动容器统一挂 global.css 的 `.scrollable` 工具类；组件内禁写 `::-webkit-scrollbar`。
10. 媒体查询写在组件 css 尾部、贴着被覆盖规则；断点当前仅 1024px 一档（会话列降档），加第二档需先记入本文档。
11. 动态样式 JS 侧只写 CSS 变量（`style={{'--x': v}}`），规则留在 CSS；禁止在 TSX 里拼接样式对象做主题/状态分支。
12. 文字灰阶只用 `--text-primary/secondary/tertiary` 三级，不新造灰色。
## 4. 文件组织
- `src/style/global.css` 固定分区顺序：① token 表（`:root` + `[data-theme='dark']`）② 全局基础（box-sizing、body、button reset）③ 全局工具类（`.scrollable` 等，总数保持个位数）。
- `*.module.css` 与组件同目录同名；一个组件一个 module 文件。
- 类型声明用现有 `css-modules.d.ts` 通配；组件数超 20 再评估引入 tcm 生成精确 `.css.d.ts`。
- PostCSS 特性白名单：当前**零插件**（平铺 CSS + 原生嵌套按需）；引入 nested/custom-media 需先记入本文档。
## 5. 演进规则与偏离记录
- **加新 token**：先进 §1 表（含暗色占位列）再在组件使用；review 见到未入表的 `--` 新变量即打回（组件局部变量桥除外）。
- **偏离基线**：与 §2 任一常数不一致的实现，须在下方偏离表记一行（日期/项/理由）。
- **暗色表补全验收**：`[data-theme='dark']` 覆盖 §1 全部占位列后，用 RPC 面板 + 侧边栏 + 会话流三个界面人工/截图核对一遍，无组件级主题选择器即达标。
| 日期 | 偏离项 | 理由 |
| --- | --- | --- |
| （空） | | |
## 6. 相关文档
- [web-styling-system RFC](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md)（框架五条与工程约束的裁决记录）
- 客户端消费架构与分层协议：[Web 客户端架构 RFC](../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)、[GUI 分层与 RPC 协议 RFC](../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)
在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式契约发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.md)；[样式系统 Agent Note](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md) 记录框架依据。