jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
169 Commits 1 Branch 0 Tags
dfaeab0e4df855a2b6e420f6ca1af63bd5ab9b47
Commit Graph

9 Commits

Author SHA1 Message Date
JianFeeeee
f6feb7c0df test(webui): 「滑动硬截断」诊断脚本（自带浏览器，不依赖共享实例） 
用户：「webui 大片界面存在滑动硬截断」。

## 现状：这一轮我**没能复现**

量法是"内容溢出但没有可滚动祖先"⇒ 候选 0 个；换成用户视角四问
（有没有可滚动容器 / 能不能滚到底 / 末尾有没有被切 / 页面自己溢不溢出）后：

    390×700  通信 ✅ 日历 ✅ 联系人 ✅ 我的 ✅
    1400×700 通信 ✅ 日历 ✅ 联系人 ✅ 我的 ✅
    （造了 12 个会话、正文都很长；验完已归档）

即按这四种量法都测不到硬截断。**长正文详情页**那一块我的探针超时没跑完 ⇒
**未判定**，不能算"没问题"。

## 这次的交付物

`client/electron/test/manual/scroll-cut-verify.mjs`：把上面这套量法固化下来，
并且**自带浏览器**（不连共享 9222）—— 共享实例被历次被中断的运行留下僵尸上下文后，
`connectOverCDP` 会一直超时（我这个会话里已经遇到三次），诊断脚本必须在
"共享实例状态未知"时也能跑。

## 我需要的（否则只能继续猜）

请指一下**具体页面 + 具体手势/位置**：哪一屏、滚轮还是触摸拖动、硬截断出现在
列表末尾还是详情正文？也可以直接看截图。我上一轮"窄屏显示不全"也是同样情况 ——
我量不出来、但你说有，那多半是我量的维度不对。
 2026-09-14 13:43:11 +08:00
JianFeeeee
83cb7528fb fix(webui): 玻璃是白色材料 —— 深色模式只降 alpha，不换基材 
用户纠正我：「什么叫深色模式也是玻璃？深色模式不应该是浅色玻璃吗？」

**他是对的，而且这是个概念错误，不是一个数值错误。**
我原先把深色模式下的玻璃写成 `rgb(15 23 42 / .72)`（一整层深色）—— 那不是玻璃，
是把面板压黑。磨砂玻璃是**白色材料**；深色模式下要做的是**降低这层白的透明度**
让深背景透出来，而不是换基材颜色。

## 更深一层的真因（这才是"半深不浅"的源头）

`.dark` 里写着 `--c-white: 24 27 33`（近黑），而**所有**玻璃面都写成
`rgb(var(--c-white) / α)` ⇒ 深色模式下**整个玻璃层系**（正文面、嵌套卡、控件、
卡片）一起变深，而 Tailwind 的浅色工具类照旧 ⇒ 界面半深不浅。
用户先看到的是"导航栏为什么还是黑色"，根子在这里。

## 改法：让这个错误写不出来

- 新增 `--glass-base: 255 255 255`（**两个主题都一样**），玻璃面的基材只有这一个来源；
- 8 处玻璃面从 `rgb(var(--c-white) / α)` 改为 `rgb(var(--glass-base) / α)`；
- `.dark` 里的玻璃相关覆盖全部清空并写明：**深色主题必须与组件侧的 `dark:` 变体
  一起做**（现在一个都没有），单独生效只会"面变深、字还是深色"，读不了；
- 删掉提前写下的 `.dark .glass-card`（它按"深色主题已存在"写，实际只会让卡片
  在浅色页面上几乎消失）。

## 判据（background.test.mjs，34 条全绿）

三条新的，都是行为级而非数值级：
- 玻璃基材只有一处定义且必须是白色；
- 没有玻璃面再用 `--c-white`（它与深色主题冲突）；
- 深色主题里不许出现非白色的 `--glass-base`；并带扰动自检。

## 实测（自己的无头 Chromium，壁纸开，1600×1000）

    系统浅色: 卡片 rgba(255,255,255,0.78)  导航 rgba(255,255,255,0.72)
    系统深色: 卡片 rgba(255,255,255,0.78)  导航 rgba(255,255,255,0.72)   ← 不再变深

即"白色玻璃、只有透明度随主题变"确实生效；深色模式也不再出现半深不浅的观感。
 2026-09-14 13:36:54 +08:00
JianFeeeee
51522dd8c2 fix(webui): 导航令牌迁移收尾 + 生成 CSS 的头注释提前闭合（会丢规则）+ 两条过期判据重写 + 判据进 npm test 
## 改法

- **`Sidebar.tsx` 底部两个按钮还是旧的深色导航假设**（`text-chrome-400
  hover:text-white hover:bg-chrome-800`、外层 `border-chrome-700`）：导航改成白玻璃
  （`--nav-bg: 255 255 255 / 0.72`）之后，`chrome-400` 落在白底上约 2.6:1（图标要
  3:1），hover 还会在白导航上闪出一块近黑。账号头像那个按钮当时换成了 `.nav-item`，
  这两个漏了 —— 就是"导航令牌迁移做了一半"。已换成 `.nav-item` + `border-gray-200`。
  没加"Sidebar 里不许有 chrome-*"的判据：另有一处 `bg-chrome-600 text-chrome-100`
  是实心小色块（正常用法），一刀切会误红。

- **`background-takeover.generated.css` 的头注释提前闭合**：生成器在注释里写了
  「src」加「/」加两颗星加「/」加「.tsx」，其中那对「星号 + 斜杠」把 CSS 注释就地
  结束 —— 尾巴变成 CSS 正文，并与第一条规则的选择器连在一起成为非法选择器 ⇒
  **`.bg-amber-100` 那条接管规则被浏览器整条丢掉**（壁纸模式下不再变半透明）。
  构建只给一条 `[WARNING] Unexpected "14" [css-syntax-error]`，不报错、不影响构建，
  正是这套判据存在的理由。改在生成器（注释里只描述、不写 glob 字面量）并重新生成：
  压缩输出现在以 `html[data-bg=on] .bg-amber-100{` 起头、14 条规则全在、无告警。
  另加两条判据（"头注释没提前闭合" + 自检）。

- **`background.test.mjs` 第 18 组三条重写**：原先断言「浅色/深色两套 `--nav-bg` 都
  定义」与「壁纸模式下 `.nav-rail` 里有 `backdrop-filter`」，两条编码的都是**已被
  有意撤掉的设计**（`faacd3c` 撤深色导航、`9aa702b` 撤导航自叠模糊），于是 `npm test`
  在 HEAD 上恒红。判据红成常态就不再是判据 —— 该改的是判据本身，而不是把缺陷写回代码。
  改成方向相反的两条：`.dark` 不许单独给导航换色 / 模糊只由壁纸层负责。

- **`cross-client-theme.test.mjs` 从来不在 `npm test` 链里**（vitest 只收
  `test/components` 与 `test/stores`）—— 那条"防漂移判据"从没在默认套件里跑过。
  已加进 `npm test`。

## 验证

- 变异测试：往 `.dark { }` 塞一行 `--nav-bg: 15 23 42 / 0.72;` → 红；往
  `html[data-bg='on'] .nav-rail` 塞 `backdrop-filter: blur(18px);` → 红；撤回 → 绿。
- `npm test` 退出码 0：窄屏布局全通过、主题 30、背景 34、cross-client 8、packaging 3、
  vitest 258/258；`npm run typecheck` 通过。
- packaging 第 3 条此前是红的，但**不是判据过期**：安装包真的落后于 dist，而 `npm test`
  的 `&&` 链一直在 background 那条就中断，`packaging` 从没跑到过。已 `npm run build`
  + `npx electron-builder --linux -c.electronDownload.isVerifyChecksum=false` 重打包。
  ⚠️ deb 目标在本机打不出来（fpm 的 portable ruby 在 `Dir.chdir` 处退出），
  AppImage 与 `linux-unpacked` 正常。
 2026-09-14 13:29:57 +08:00
JianFeeeee
9aa702b8cc fix(webui): 导航改"按主题的玻璃"（浅色白玻璃+深字）+ 去掉整屏闪的入场动画 
用户两句话：
  「那你为什么不把白字换成黑字或者自动反色或者描边呢？」
  「部分动画十分不合理，会导致页面大范围的闪动，且不能让人自然的把注意力集中在
    将要出现的页面上」

## ① 导航：他说得对，我之前是用错误的方式解决对比度

这个应用是**浅色底 + 深字**，导航却是全页唯一一块黑的 —— 那才是"割裂"。我上一轮
为了"白字对比度"把它做成深玻璃，等于**把一块地方永久压黑**来回避问题。

现在导航底色/文字全部走令牌，按主题切换：

    浅色：白玻璃 rgb(255 255 255 / .72) + 深字 #475569   → 对比度 7.48:1
    深色：深玻璃 rgb(15 23 42 / .72)   + 亮字 #94a3b8   → 自动反色

组件侧改成 `.nav-rail` / `.nav-item[data-active]` 令牌类（Sidebar 与 NarrowNav 同一套）。
同时删掉壁纸模式里写死的深玻璃规则 —— 那条正是"为什么还是黑色"。

## ② 动画：整面板入场删掉

先是从"所有面板一起动"改成"只动主内容区"，试下来仍然不对：页面级淡入会把
**已经在那儿的框架**也一起暗一下，观感还是闪。所以这一档整体删掉，只保留局部、
有明确语义的动效（日历翻页、菜单展开）。实测切视图时 `animatedOnSwitch = 0`。
骨架不动，注意力自然落在变化的那块内容上。

## ③ 一条我自己的误判（值得记下）

深色主题下我量到导航文字对比度只有 2.36，一度以为是变量/级联的问题，还写死了一份
深色字面值。**那是误判**：`.nav-item` 有 `transition: color .15s`，我在切主题后
**立刻**读 computed color，拿到的是过渡的**起点**（浅色值）。决定性证据是连内联
`style.color` 都"改不动"它 —— 级联不可能这样，只可能是还在过渡中。等 400ms 再量就正常。
写死的那份已撤掉，并在 CSS 里留下说明；新判据 `test/manual/nav-contrast-verify.mjs`
用 WCAG 比值量对比度（不是"颜色是不是黑的"），每次读之前等 400ms。

背景套件 32 条全绿（含"导航走令牌 + 两套令牌都在"）。
 2026-09-14 11:57:41 +08:00
JianFeeeee
ef68c4950c fix(webui): 统一玻璃语言 —— 导航改深色玻璃 + 内层面板自带圆角 
用户：「你不觉得页面设计很割裂吗？尤其是通信页，大面积的非圆角元素。
同时还有大面积的非玻璃样式。导航栏不也应该改为玻璃样式吗，为什么还是黑色」。

## ① 导航还是黑的：因为我自己留了一条"必须不透明"的规则

`html[data-bg='on'] .bg-chrome-900 { background-color: rgb(var(--c-chrome-900));
backdrop-filter: none }` —— 这是**更早一轮**用户的要求（当时面板太透，壁纸从导航里
透出来显得脏）。现在整套语言统一到玻璃之后，导航继续做一块实心黑就成了全页唯一的
例外，也就是"割裂"的来源。

改成**深色玻璃**（α=0.72 + blur(18px) + saturate）——用深色而不是白色玻璃：
白字压在深色上才有对比度。没开壁纸时用 0.82（后面是页面底色而不是照片，太透显脏）。

## ② 通信页"大面积非圆角"：是我修滚动时带出来的

圆角原本只加在外壳上，靠 `overflow: hidden` 裁掉内层的直角 —— 但那个 overflow
会杀掉滚动（上一封），必须去掉。**于是内层白底面板的直角就从圆角外壳里戳了出来。**
现在把圆角直接给内层面板（`.comm-pane > *`），两边对齐，且不依赖裁剪 ⇒ 与滚动不冲突。
MailView 的两条工具条也不再自带宽底（只留上边框，底色继承面板），否则同样会戳角。

## 判据

`background.test.mjs` 里两条**旧判据**（断言"导航必须不透明、不参与模糊"）按现行契约
重写为"深色玻璃（α∈[0.6,0.9]）+ 参与模糊"，并新增"内层面板自带圆角"。
要求反转后旧判据必须一起改 —— 留着只会让下次改动"要么违规、要么把缺陷写回去"。

**实测**（真浏览器，1280×900，壁纸态）：导航 α=0.72 / blur(18px) / radius 14px；
内层 MailList 面板 radius **14px**（不再是直角）。背景套件 31 条全绿。
 2026-09-14 11:17:12 +08:00
JianFeeeee
76ce201c3a feat(webui): 导航合并 + 悬浮玻璃 + 页面动画 + 控件档透明度 + 圆角无条件生效 
用户四封信（同一线索）提的六件事，都在这里：

## ① 导航合并（「导航栏的内容有点多了」）

收件箱/发件箱/授权 → 一项「通信」，进去由**内部页签**区分（CommTabs）；
新建 → 「通信」页内**悬浮圆形加号**（ComposeFab）；导航只剩 通信/日历/联系人；
管理 → 合进「我的」，管理员在页面**最下面**看得到（非管理员不渲染，不是禁用）。

`viewMode` 仍是原来那三个值（几十处调用点不用改），新增 `commTab` 记住上次用的子页签；
通信项的徽标 = 未读 + 待决策（授权信息不能因为合并而消失）。

## ② 窄屏底部导航：悬浮玻璃（「还是固定底部延伸，没有玻璃效果，也没有悬浮」）

原来是 `border-t bg-chrome-900` 通栏贴底。改成：左右/离底各留 10px、圆角、
深色半透明 + `blur(18px)`、投影，安全区并入下外边距。

## ③ 页面动画（「页面极度缺少动画，所有页面都是直接出现」）

在 `<html>` 上挂一个短命类触发外壳直接子面板的入场动画。**没有用 key 重挂载**：
面板是 flex 链上的一环，套 wrapper 会改掉 flex 传递（窄屏覆盖层最先坏）。
并且尊重 `prefers-reduced-motion`（关了就一点都不动）。

## ④ 控件档透明度（「复选框和地址猜测项…他们才是真正需要拉低透明度的地方」）

新增第三档 `--bg-glass-control`（0.5/0.55）：授权多选胶囊、地址建议菜单。
三档递减：正文面 0.88 > 嵌套 0.82 > 控件 0.5。

## ⑤ 打底 vs 透明（上一封「该打底的地方透了、该透的空白处糊了」）

正文面回到 0.88（读得清优先）、空白/页面底透明**且不模糊**、面板模糊降到 10px。

## ⑥ 圆角与玻璃**无条件**生效（「大面积缺失圆角与玻璃效果…都是硬截断」）

根因：`.app-shell` 的留缝/圆角/投影原先全写在 `html[data-bg='on']` 里
⇒ **没开壁纸的账号**看到的是硬边不透明面板。现在几何下沉为无条件基线，
壁纸相关的加强仍叠加在上面。窄屏内容面板同样浮起来。

## 判据

- `test/nav-merge.test.mjs` 8 条（含自检：重构前的写法必须判红）——
  改完跑老套件 254 条**全绿却一条都没测导航结构**，结构改动必须自带判据。
- `test/manual/nav-restructure-verify.mjs`：真浏览器 9 条（导航项数、页签切换真的换内容、
  加号 56×56 且 `elementFromPoint` 命中自己、我的页底部管理入口在退出登录之后、
  控件档 α=0.5 对正文面 α=0.88 的反向对照）。
- `test/manual/narrow-glass-verify.mjs` 6 条：悬浮几何（三边留缝 10px、圆角 14px、
  缝隙处命中的是页面底 ⇒ 真的浮着）、玻璃（α=0.82 + blur18）、触摸高度最小 49px、
  动画真的在跑（静止时 `animationName=none`，切换后 =pane-in）且 reduced-motion 下不动。
- `test/background.test.mjs`：把三条**过时判据**（早前那版"越透越好"）按现行契约重写 ——
  旧判据留着只会把我拽回错误方向。30 条全绿。

## 顺带

窄屏探针原先只调视口、**没模拟触屏**，于是 `(hover: hover)` 仍为真，
把「悬停才显形的次要动作」误报成透明 —— 差点去"修"一个本来就对的规则。
已改成 hasTouch + isMobile + DPR 的触屏上下文，且收尾只关自己的 context
（CDP 连的是共享 Chromium，`browser.close()` 会把别人的标签页一起关掉）。
 2026-09-14 10:35:05 +08:00
JianFeeeee
d2904fc45d style(webui): 导航栏改为完全不透明 + 内容面板更通透 + 整屏浮动圆角玻璃 
用户 2026-09-14 原话：「导航栏应当完全不透明……没有正文的位置过于不通透，
同时导航栏应当现代化一下，整个界面应当圆角化玻璃化」。

这三句是**两个方向**的要求，我上一轮正好把导航栏做反了（越改越透）：

## ① 导航栏：完全不透明（含窄屏底部导航）

`chrome-800/900` 在背景模式下不再吃 alpha、也不参与模糊。它是**框架**，
不该跟着壁纸一起虚化。它与"内容要通透"是两个方向的要求，所以写成独立规则、
并在注释里点名 —— 合并成一条必然互相打架。

## ② 内容面板：更通透

`--bg-glass` 0.62 → **0.45**（深色 0.66 → 0.5），嵌套层 0.3 → 0.22。
实测（纯红壁纸读绿通道）：邮件列表有效不透明度 115/255 ≈ **0.45**，正文区全透。

## ③ 整屏浮动圆角玻璃

给宽屏外壳加了稳定钩子 `app-shell`，背景开启时：外壳 **padding/gap 10px**
（面板之间露壁纸 —— 没有缝隙的"玻璃"看上去仍是一整块板）、顶层面板
**圆角 var(--radius-card)** + 投影。实测三栏：导航 60px/圆角14px/不透明、
列表 320px/圆角14px/0.45、正文 1020px/圆角14px/全透。

## 判据

`test/background.test.mjs` 新增 5 条形态判据（导航不透明、导航不参与模糊、
`--bg-glass ≤ 0.55`、外壳留缝、顶层面板圆角），共 **28 条**。
前端 254 条 + 打包一致性全绿。

## 过程中的三处自纠

1. **我的 App.tsx 编辑第一次根本没落盘**：那份 python 脚本第 18 行语法错误就整体
   没执行，而我把"✓ 已加钩子"当成了成功 —— 后来 `.app-shell 存在: false` 才暴露。
   教训：脚本报成功不等于目标文件变了，**改完要回读**。
2. **JSX 里把 `{/* … */}` 放在 `return (` 与根元素之间**是非法的 ⇒ 构建失败。
   改为 JS 注释放在 `return` 之前。
3. ★ 这两次失败都是**新加的部署闸门先拦住的**（"前端 dist 比源码旧"），
   也就是上一轮刚补的那道门当天就发挥了作用 —— 换成以前，会再次静默部署旧界面。

## 顺带清理

验收截图用的 2 封样例邮件已删、随之产生的空会话已归档；测试账号外观已重置。
 2026-09-14 09:07:49 +08:00
JianFeeeee
ababe4ae56 fix(webui): 壁纸被不透明层盖住 —— 玻璃不再层层相乘 + 浅色表面类全部接管 
用户报的：「webui 目前在壁纸底上叠了太多不透明层，导致壁纸效果很差，几乎看不出来」，
追问后补充：「不只是玻璃，而是很多界面是不透明的」。两句都成立，是两个叠加的原因。

## ① 玻璃层层相乘

每层面板都吃同一个不透明度 a，两层就是 1-(1-a)²。a=0.82 时两层 0.97、三层 0.995
—— 壁纸在数学上被吃掉，而且每层各做一次 16px 模糊，图案被糊成灰块。
改法：玻璃只出现一次（外层 0.62 + 18px 模糊；嵌套层只留 0.3 色调且不再模糊；
第三层透明）。同时把遮罩 24%→12%、照片自身模糊 8→4px（那张被洗白的锅之一）。

## ② 14 个浅色表面类根本没被接管（"很多界面是不透明的"就是这条）

旧规则只接管 white / gray-50 / slate-100，而源码里在用的是
gray-100(24 处)、blue-50(17)、red-50(13)、blue-100(8)、gray-200(8)、green-50(8)…
—— 全是实心的，正好盖住壁纸。

清单改为**从源码用法生成**（`scripts/gen-background-takeover.mjs` → 生成的 CSS，
构建前自动跑），因为手写清单必然烂；判据保证"源码里出现的浅色表面类必须都被接管"，
并明确排除页面底（gray-50/slate-100 必须保持**全透明**，不能被改成半透明）。
按钮/徽标（*-600/700、chrome-600/700）**故意保持不透明**：小控件可读性优先
（index.css 里原有注释记着实测 4.46:1 的教训）。

## 判据

- `test/background.test.mjs` 23 条（新增 8 条）：玻璃算式（两层 ≤0.85）、外层 ≤0.70、
  嵌套规则存在、**判据自检**（旧值 0.82 必须算得出 >0.95）、表面类覆盖、页面底不得进清单、
  清单非空跑。犯过一次错：第一版把判据追加在 `process.exit()` **之后** ⇒ 根本没执行，
  从"测试数没变"才发现。
- `test/manual/wallpaper-layers-verify.mjs`（真实渲染，自带无头 Chromium）：
  用**纯红壁纸读绿通道**测有效不透明度（纯色下 backdrop-filter 不影响读数）。
  面板 p95：**修复前 82% → 修复后 62%**；反向对照（改回旧值）能分辨 ≥10 个百分点；
  深色照片面上面板仍是浅底；关掉壁纸的同坐标对照更实。5/5。
  过程中作废了两个指标：只看绿通道会把深色元素误判成"盖死"；"面积占比"类阈值
  （Δ≥8/≥40）在 0.97 时仍会蹭过门槛，饱和而无分辨力 —— 同坐标比值才可信。

## 交付

已部署（网关内嵌 WebUI 重建）：线上 CSS 已含 `--bg-glass-inner`、嵌套规则与 14 个接管类。
 2026-09-14 08:09:22 +08:00
JianFeeeee
84c1d749cd feat(webui): 自定义背景 + 外观现代化；修正实心按钮白字在深色下的对比度 
# 自定义背景（新功能）

三选一：不设 / 预设渐变 / 自定义图片，另加压暗与模糊两条滑杆。

**预设的色值全部复用现有调色板变量**，因此自动随主题变化 —— 那一组
（50–300）在深色下本来就是暗的（见 .dark 与 theme.test.mjs 第 19 条），
于是浅色得到柔和 pastel、深色得到低沉暗调，不需要维护两套渐变，也不会
出现「深色模式下原样落下浅色渐变」这类绕过主题变量的错误。

图片路径的关键取舍：
- **先压缩再存**。手机直出照片 4–8MB，而 localStorage 配额约 5MB，直接写会抛
  异常，用户看到的是「选了图片没反应」。等比缩到最长边 2560px、转 JPEG；
  仍超限则再缩一档；再不行就**明确拒绝并说明原因**（不是静默失败）。
- 失败一律返回 `{ok:false, reason}` 并渲染成 `role="alert"`。

# 背景层为什么不放进主题 store

主题（light/dark/system）是必须全局一致的语义；背景是纯装饰偏好，取值空间
与主题毫无关系。混在一起会让「跟随系统」的实现被背景字段淹没。

# 背景层实现在 CSS，不改 27 个组件

按 Tailwind 生成的实际类名统一接管：背景开启时让出不透明的页面底
（body / bg-gray-50 / bg-slate-100 → 透明），并把卡片（bg-white）与框架
（bg-chrome-800/900）变成半透明 + 背景模糊。

逐个组件加 class 必然漏 —— 漏掉的那块就是一张不透明卡片浮在背景上。
这段 CSS **刻意放在所有 @layer 之外**：它要覆盖的正是 utilities 生成的
`.bg-white`，写进 @layer components 会被 utilities 压过去（静默失效），
而分层 CSS 恒输给未分层 CSS，这是唯一稳定可靠的位置。

**chrome-600/700 刻意保持不透明**：它们不是大面板，而是导航项与 15px 的
计数徽标。真实渲染量得半透明会把徽标上的数字压到 4.46:1，低于 AA 4.5 ——
小控件的可读性优先于装饰效果（已用脚本量出，见下）。

# 「跟随系统」的可见性

三态本来就已实现（system 为默认值 + matchMedia 监听）。这次做的是让它可被
发现与信任：选择器改成分段控件（role=radiogroup + aria-checked），说明文案
写清「跟随系统会随系统的深色开关自动切换」，并保留单选按钮入口的
「当前跟随系统：深色/浅色」提示。

# 外观现代化

- **圆角整体调大一档**（默认 0.25→0.5rem）。原值是几年前的紧凑风格，
  在宽屏桌面应用上偏硬。只改比例尺，200 处圆角一次性刷新，不产生
  「新组件大圆角、旧组件小圆角」的断层。
- 语义化圆角令牌：`rounded-card` / `rounded-control`（数值档位答的是「多大」，
  这两个名字答的是「用在哪」）。
- 自定义滚动条（桌面应用里常驻可见，系统默认样式偏旧）。
- 键盘焦点环（`:focus-visible`，仅键盘导航时出现；可访问性硬要求）。
- 交互元素统一过渡；并尊重 `prefers-reduced-motion`。

# 顺带修正两处真实问题（都由真实渲染量出，不是估算）

1. **实心按钮白字在深色下 4.46:1，低于 AA**。
   深色 `--c-on-accent` 是「近白」244 246 250（为了不刺眼），而结构检查第 23
   条只拿**浅色**的纯白 255 去算 → 4.83 通过。**测试存在盲区**：
   同一个实心底，白字换暗一点点就越过 AA 线。导航未读徽标「12」正是这个组合。

   两处都修：把第 23 条改成**两种模式的 on-accent 都算**（闭合盲区），
   并把深色 on-accent 抬到 250 250 252（4.65:1，仍非纯白，保留原初衷）。

2. **theme.test.mjs 切颜色块的方式很脆**：它用 `indexOf('.dark')` 切片，于是在
   :root 的注释里写一句带点的选择器写法就会把浅色块提前截断（我加注释时
   真的踩到了，第 8 条假失败）。更危险的是反向情形：块被截短后变量集合变小，
   「覆盖齐全」这类断言可能**真空通过**。改为所有块切分都基于**剥注释后**的文本。

# 测试

- 新增 `test/background.test.mjs`（15 条结构检查）：遮罩两主题各一份、
  背景层必须负 z-index（0 会盖住界面）、背景开启时必须让出页面底、
  玻璃化只在 data-bg=on 下、悬停态一并接管、预设复用调色板变量、
  图片上限与失败原因存在、尊重 reduced-motion 等。
- 新增 `test/stores/background.test.ts`（16 条）：脏数据归一化（未知预设、
  kind=image 却无图、越界数值）、CSS 变量写入与清理成对（残留 --bg-image 会
  让「关掉背景」后仍显示旧图）、localStorage 抛异常不打断操作。
- 新增 `test/manual/background-verify.mjs`：连真实 Chromium 验收**渲染结果**
  （背景层是否真的可见、玻璃化的计算样式、正文在背景之上是否仍达 WCAG AA、
  自动模式在**不刷新**页面时跟随系统切换、显式选择不被系统覆盖）。
  它拦住了上面两个真问题，也拦住了我自己两次写错的判据。

# 验证

- typecheck 干净
- 主题 30/30、背景 15/15、vitest 216/216（新增 16）
- 真实渲染验收 23/23（AGENTMAIL_DIST 注入本地构建 + 活 Gateway，未部署即验收）
- 截图对照：浅色/深色 + 极光背景，面板玻璃化与层次均符合预期
 2026-09-12 08:02:30 +08:00