Merge pull request 'Pair the contrast rules with the token change' (#198) from feature/contrast-typography into main

.task/feature-contrast-typography.md

@@ -0,0 +1,27 @@
+# feature/contrast-typography 任务卡
+
+任务主记录：<PR 链接，task-finish 时填写>；状态：进行中；owner：weichen
+
+## 基线与授权
+
+- 权威仓：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-System-Dev.git；目标分支：main；R0（initial_base_sha）= 34e82d53c1716f0075d510a5f7b6d72dd3fc9912
+- 工作区：/home/weichen/projects/Agent-System-Dev-wt-feature-contrast-typography（worktree）；分支：feature/contrast-typography
+- 授权与交付终点：实现对比度与字号治理（令牌、contrast-guard、DESIGN.md、消费端迁移、本机界面字号）。不改 Core 契约，不改后端 settings schema，不做 px→rem / prefers-contrast / 聚焦环加强。交付为 UI、Frontend、Dev 各一个 PR。
+
+## 目标与非目标
+
+- 目标：三套主题的正文与文字档对比度 ≥ 4.5:1，装饰 faint 与图形语义色 ≥ 3:1；墨绿侧栏强调色与「新建任务」按钮可见；表头与决策性文字不再使用 faint + 10px；设置中心可调界面字号（13/14/16/18，仅本机）。
+- 非目标：账号级字号同步、rem 标尺、高对比媒体查询、聚焦环重做。
+
+## 同步记录
+
+| 节点 | sync_base_sha | tested_head_sha | checked_at |
+|---|---|---|---|
+| 启动 | 34e82d53c1716f0075d510a5f7b6d72dd3fc9912 | 34e82d53c1716f0075d510a5f7b6d72dd3fc9912 | 2026-10-05T04:25:22Z |
+
+## 结果与验证（完成后填写）
+
+- 结果：三套主题的正文与文字档达到 4.5:1，装饰 faint 与图形语义色达到 3:1。墨绿侧栏的强调色与「新建任务」按钮分开用浅色令牌。设置中心可调本机界面字号（13/14/16/18）。
+- 验证：Dev 仓 `make test` 退出码 0（2026-10-05）。其中 frontend vitest 17 文件 81 项、knip 43 <= 43；ui vitest 14 文件 103 项（含 contrast-guard）、tsc、knip 55 <= 55。浏览器在 Vite（127.0.0.1:5175）上核对计算样式：墨绿新建任务按钮为 #e9f0f6 / #082d4f，active 图标为 #8fd4b4，表头无 uppercase 且走 --text-dim；`--ui-font-size: 18px` 时 xs 为 calc(18px - 3px)。后端 8787 未启动，设置弹窗本身没有点开。
+- 影响与剩余项：px→rem、prefers-contrast、聚焦环不在本次。子仓 PR 合入后 Dev 的 gitlink 才指向已合入提交。
+| 同步前验收 | 34e82d53c1716f0075d510a5f7b6d72dd3fc9912 | 17b502e5c0332607793a32240ae7c68ccf97915c | 2026-10-05T04:39:43Z |

DESIGN.md

@@ -44,21 +44,46 @@ Agent-System-Dev 是桌面优先、Web 兼容的 AI 工作台。界面应**冷
 
 ### 2.3 文本
 
-`--text`（主读文本，深 `#d4d4d4` / 浅 `#262626`）、`--text-dim`（62%）、`--text-faint`（38%）。
+`--text`（主读文本，深 `#d4d4d4` / 浅 `#262626` / 墨绿 `#082d4f`）。
+`--text-dim`：深 66% / 浅 68% / 墨绿 70%。
+`--text-faint`：深 52% / 浅与墨绿 58%。
 用文本层级制造信息密度，先于增加更多边框或颜色。
 
+门槛（`contrast-guard.test.ts`，WCAG 2.1）：
+
+- `--text` 与 `--text-dim` 在主区表面（`--bg`、`--bg-panel`、`--bg-raised`、代码底 `--bg-inset`）不低于 **4.5:1**。
+- `--text-faint` 不低于 **3:1**，并且**只用于装饰**：占位符、chevron、kbd、关闭图标的默认色。
+- 承载决策或需要读完的文字从 `--text-dim` 起步：表头、确认详情、工具清单、空态说明、设置项描述、状态词。不要把 faint 当内容色。
+
+侧栏另用 `--text-sidebar-dim`（墨绿 78%）与 `--text-sidebar-faint`（墨绿 62%），门槛与主区相同，只跟 `--bg-sidebar` 对拍。
+侧栏会把 `--text*` 重映射成侧栏色。挂在侧栏 DOM 里、但画在主区纸面上的浮层（账户菜单）改用 `--text-workspace*`，这是同一套文字的不被重映射的副本。
+
 ### 2.4 强调与语义色
 
 - 交互强调蓝：`--accent`（深 `#4099ff` / 浅 `#0b7fff`）。**只用于**链接、选中指示、聚焦环、
   进行中指示；不做大面积铺底、不做主按钮底色。
 - 主按钮：单色系反色——`--primary`（深 `#ffffff` / 浅 `#0d0d0d`）配 `--primary-foreground`
   （反向黑/白）。品牌色保持克制。
-- 语义：`--ok #46bf72`、`--warn #ff8a30`、`--err #ff5c5c`（浅色 `#1e8a3e/#e07b00/#e03131`）。
-  语义色只表语义。
+- 语义图形色：`--ok #46bf72`、`--warn #ff8a30`、`--err #ff5c5c`（浅色与墨绿 `#1e8a3e` / `#d17300` / `#e03131`）。
+  语义色只表语义。图形色（状态点、描边、色条）在 `--bg` / `--bg-panel` / `--bg-raised` 上不低于 **3:1**。
+  **图形色不作文字。** 链接、状态词、差异文字、空闲状态字用下面的文字档。
+- 文字档（同一色相，专门保证 4.5:1，含铺在 `*-soft` 上）：
+
+  | 令牌 | 深色 | 浅色 / 墨绿 | 用途 |
+  |---|---|---|---|
+  | `--accent-text` | `#58a6ff` | `#0858b0` | 链接、动作字 |
+  | `--warn-text` | `#ff8a30` | `#8d4d00` | 警告文字；也作警告徽标底 |
+  | `--err-text` | `#ff7272` | `#a92525` | 错误文字；也作错误徽标底 |
+  | `--ok-text` | `#46bf72` | `#17682f` | 成功状态字 |
+  | `--idle-text` | `#929292` | `#636363` | 空闲状态字 |
+  | `--diff-add-text` | `#7dcea0` | `#17682f` | 差异增加的文字 |
+  | `--diff-remove-text` | `#ff9b9b` | `#a92525` | 差异删除的文字 |
+
+  徽标：底用对应 `*-text`，字用 `--text-on-semantic`（深 `#101010` / 浅与墨绿 `#ffffff`）。
 - 等你确认用 `--wait`（深 `#8b93ff` / 浅 `#3a46c8` / 墨绿 `#3d5a9a`）和 `--wait-soft`。
   不借用成功绿，也不用红或橙装饰等待。
 - 差异视图：增加用 `--diff-add` / `--diff-add-text`，删除用 `--diff-remove` / `--diff-remove-text`。
-- 空闲任务用 `--task-idle`，定时任务用 `--task-scheduled`。两者不要混成同一种灰。
+- 空闲任务的图形用 `--task-idle`，文字用 `--idle-text`。定时任务用 `--task-scheduled`。两者不要混成同一种灰。
 
 ### 2.5 墨绿主题（可选，`data-theme='molv'`）
 
@@ -72,8 +97,12 @@ Agent-System-Dev 是桌面优先、Web 兼容的 AI 工作台。界面应**冷
 | `--bg-sidebar` | `#082d4f` | 左栏、顶栏 |
 | `--text` | `#082d4f` | 主读文本 |
 | `--text-sidebar` | `#e9f0f6` | 左栏与顶栏文字 |
-| `--accent` | `#165f49` | 交互强调（翠绿） |
-| `--primary` / `--primary-foreground` | `#082d4f` / `#f3f8f5` | 主按钮 |
+| `--accent` | `#165f49` | 主区交互强调（翠绿）。不用于侧栏 |
+| `--accent-sidebar` | `#8fd4b4` | 侧栏内的强调：active 图标、聚焦边、选中条 |
+| `--primary` / `--primary-foreground` | `#082d4f` / `#f3f8f5` | 主区主按钮 |
+| `--primary-sidebar` / `--primary-sidebar-foreground` | `#e9f0f6` / `#082d4f` | 侧栏上的主按钮（「新建任务」） |
+
+深色与浅色下，侧栏三令牌别名到主区：`--primary-sidebar` 同 `--primary`，深色 `--accent-sidebar` 同 `--accent`。浅色侧栏是白底，`--accent-sidebar` 改走 `--accent-text`（`#0b7fff` 在白底上不足 4.5:1）。侧栏内的 active、聚焦和主按钮只消费这组令牌，不直接用主区 `--accent` / `--primary`。
 
 ### 2.6 文档纸面（主题不变量）
 
@@ -97,12 +126,15 @@ Office 分页预览是**内容**，不是界面。纸面与默认墨色固定，
 | `--fs-ui-base` | = | 14 | 正文、常用按钮、区块标题 |
 | `--fs-ui-caption` | −1px | 13 | 紧凑辅助文案 |
 | `--fs-ui-sm` | −2px | 12 | 次要信息、行内代码 |
-| `--fs-ui-xs` | −4px | 10 | 徽标、快捷键、极弱元数据 |
+| `--fs-ui-xs` | −3px | 11 | 仅徽标与图标性字符 |
 | `--fs-ui-tooltip` | 同 `--fs-ui-sm` | 12 | 提示气泡。不另起字号 |
+| `--fs-code` | −2px | 12 | 代码块、终端、Diff。随 `--ui-font-size` 缩放 |
 
 规则：UI 组件一律用标尺令牌；禁止行内 `font-size` 数值与 Tailwind 式任意字号
 （守护测试棘轮拦截）。用户调字号只改 `--ui-font-size`，不改根字号；图标、间距、圆角不随字号缩放。
-例外：代码/Diff/终端/文档正文用独立阅读字号（等宽 12–12.5px、文档 13.5px）。
+设置中心「界面字号」提供 13 / 14 / 16 / 18 四档，写入 `--ui-font-size`，只存在本机（`localStorage`），不进账号设置。
+表头用 `--fs-ui-sm` + `--text-dim`，不用 xs，也不要对中文做 `uppercase`。
+例外：文档正文保留自己的阅读字号（约 13.5px），不跟界面标尺走。
 
 字体：`--font` 系统栈优先（-apple-system/PingFang SC…）；路径、命令、代码、快捷键用 `--mono`。
 
@@ -245,9 +277,21 @@ Primary（`--primary` 反色）、Ghost（透明，hover 出表面）、Danger
 6. 同一对象出现第二个预览落位（预览只在预览区，全屏是它的放大）；
 7. `<details>` 折叠——用 Collapsible。
 8. 绕过 `safeHtml` 直接把 HTML 字符串写进页面（`dangerouslySetInnerHTML` 或非空的 `innerHTML` 赋值）。
+9. 文字与背景的对比度低于门槛（正文与文字档 4.5:1，装饰 faint 与图形语义色 3:1）——`contrast-guard.test.ts`。
 
 ## 12. 演进规则
 
 改风格 = `DESIGN.md` 与 `tokens.css`（必要时 `motion.css`）**同 PR 成对修改**，附前后值对照；
 不允许只改代码不改文档。新增视觉规则先问：它属于结构、表面、交互还是状态？
 拿不准时，选更安静的方案、用更强的信息层级。
+
+### 12.1 对比度与字号（2026-10-05）前后值
+
+| 令牌 | 之前 | 之后 |
+|---|---|---|
+| `--text-dim` | 三主题 62% | 深 66% / 浅 68% / 墨绿 70% |
+| `--text-faint` | 深 38% / 浅与墨绿 42% | 深 52% / 浅与墨绿 58% |
+| `--text-sidebar-dim` / `faint`（墨绿） | 72% / 46% | 78% / 62% |
+| `--warn`（浅色、墨绿） | `#e07b00`（白底 2.99:1） | `#d17300` |
+| `--fs-ui-xs` | −4px（10px） | −3px（11px），仅徽标 |
+| 文字档 `*-text`、`--text-on-semantic`、`--accent-sidebar`、`--primary-sidebar`、`--fs-code`、`--idle-text` | 无 | 见 §2.4–§3。图形色不再当文字用 |