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，未部署即验收）
- 截图对照：浅色/深色 + 极光背景，面板玻璃化与层次均符合预期
This commit is contained in:
157
client/electron/test/background.test.mjs
Normal file
157
client/electron/test/background.test.mjs
Normal file
@ -0,0 +1,157 @@
|
||||
/**
|
||||
* 自定义背景的结构性检查。
|
||||
*
|
||||
* 与 theme.test.mjs 同一风格：判据是「源码里存在/不存在某种形态」，不需要浏览器。
|
||||
* 真正的视觉验收靠手工脚本（test/manual/）。
|
||||
*
|
||||
* 这些检查存在的理由：背景是**装饰层叠加在内容之下**，它的 bug 形态是
|
||||
* 「正文读不动」和「背景根本没出现」，两者都不报错、不影响构建。
|
||||
*/
|
||||
import { readFileSync, readdirSync } from 'node:fs';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { dirname, join } from 'node:path';
|
||||
|
||||
const here = dirname(fileURLToPath(import.meta.url));
|
||||
const read = p => readFileSync(join(here, p), 'utf8');
|
||||
|
||||
let pass = 0;
|
||||
let fail = 0;
|
||||
const check = (name, ok, detail = '') => {
|
||||
if (ok) {
|
||||
pass++;
|
||||
console.log(` 通过 ${name}`);
|
||||
} else {
|
||||
fail++;
|
||||
console.log(` 失败 ${name}${detail ? ' — ' + detail : ''}`);
|
||||
}
|
||||
};
|
||||
|
||||
const css = read('../src/index.css').replace(/\/\*[\s\S]*?\*\//g, '');
|
||||
const store = read('../src/stores/backgroundStore.ts');
|
||||
const picker = read('../src/components/BackgroundPicker.tsx');
|
||||
const main = read('../src/main.tsx');
|
||||
|
||||
const rootBlock = css.slice(css.indexOf(':root'), css.indexOf('.dark'));
|
||||
const darkBlock = css.slice(css.indexOf('.dark {'));
|
||||
|
||||
// 1) 遮罩颜色必须两种主题各一份。
|
||||
// 只有一个值时，深色模式下用白色遮罩会把照片洗成一块亮斑，正文完全读不动。
|
||||
check(
|
||||
'--bg-scrim 在浅色与深色下都有定义',
|
||||
/--bg-scrim:\s*\d+\s+\d+\s+\d+/.test(rootBlock) && /--bg-scrim:\s*\d+\s+\d+\s+\d+/.test(darkBlock),
|
||||
'深色缺少遮罩色时浅色照片会压不住'
|
||||
);
|
||||
|
||||
// 2) 遮罩色必须是 RGB 三元组（与色板同一约定），否则 rgb(var() / var()) 无效。
|
||||
check(
|
||||
'--bg-scrim 存 RGB 三元组',
|
||||
/--bg-scrim:\s*\d+\s+\d+\s+\d+;/.test(rootBlock) && !/--bg-scrim:\s*#/.test(css)
|
||||
);
|
||||
|
||||
// 3) 背景层必须画在内容**之下**。
|
||||
// z-index:0 / auto 的定位元素会画在常规流内容之上，把整个界面盖住。
|
||||
check(
|
||||
'背景层用负 z-index 且不吃点击',
|
||||
/\.app-backdrop\s*\{[^}]*z-index:\s*-1/.test(css) &&
|
||||
/\.app-backdrop\s*\{[^}]*pointer-events:\s*none/.test(css),
|
||||
'z-index 不为负会盖住界面'
|
||||
);
|
||||
|
||||
// 4) 背景开启时必须让出不透明的页面底，否则背景永远看不见。
|
||||
// 这是最容易漏的一条：写好了渐变、挂好了层，却被 bg-gray-50 挡住。
|
||||
//
|
||||
// 正则要写成「选择器列表 … { 声明体 }」而不是 [^{]* 直接跨到声明：
|
||||
// [^{] 遇 { 即停，而这里要跨过的正是选择器后面的那个 {。
|
||||
check(
|
||||
'data-bg=on 时页面底变透明',
|
||||
/html\[data-bg='on'\]\s+body/.test(css) &&
|
||||
/html\[data-bg='on'\][^{}]*\.bg-gray-50/.test(css) &&
|
||||
/html\[data-bg='on'\][^{}]*\{[^}]*background-color:\s*transparent/.test(css)
|
||||
);
|
||||
|
||||
// 5) 玻璃化只应在背景开启时生效。
|
||||
// 若无条件给 .bg-white 加半透明/模糊，关闭背景的用户会看到一层发灰的卡片。
|
||||
const glassRules = css.match(/html\[data-bg='on'\][^{]*\{[^}]*backdrop-filter/g) || [];
|
||||
const bareGlass = /(^|\n)\s*\.bg-white\s*\{[^}]*backdrop-filter/.test(css);
|
||||
check(
|
||||
'backdrop-filter 仅在 data-bg=on 下使用',
|
||||
glassRules.length > 0 && !bareGlass,
|
||||
bareGlass ? '存在无条件的 .bg-white 模糊规则' : '未找到玻璃化规则'
|
||||
);
|
||||
|
||||
// 6) 悬停态也要接管。
|
||||
// 不接管的话鼠标一进面板就从不透明闪回，观感是明显的跳动。
|
||||
check(
|
||||
'悬停态一并在背景模式下接管',
|
||||
/html\[data-bg='on'\][^{]*\.hover\\:bg-gray-50:hover/.test(css)
|
||||
);
|
||||
|
||||
// 7) 预设渐变只能由 CSS 提供色值，组件里不得写死颜色。
|
||||
// 写死十六进制会绕过主题变量 —— 深色模式下会原样落下浅色渐变。
|
||||
const presetClasses = (css.match(/\.bg-preset-[a-z]+\s*\{/g) || []).length;
|
||||
const hexInPicker = picker.match(/#[0-9a-fA-F]{3,6}\b/g) || [];
|
||||
check(
|
||||
'预设渐变定义在 CSS 且组件无写死颜色',
|
||||
presetClasses >= 4 && hexInPicker.length === 0,
|
||||
hexInPicker.length ? `组件含 ${hexInPicker.join(',')}` : `只找到 ${presetClasses} 个预设`
|
||||
);
|
||||
|
||||
// 8) 预设必须复用调色板变量（因此自动随主题变），而不是字面色值。
|
||||
check(
|
||||
'预设渐变复用调色板变量',
|
||||
/\.bg-preset-aurora\s*\{[^}]*rgb\(var\(--c-/.test(css)
|
||||
);
|
||||
|
||||
// 9) 背景必须在 render 之前套用，且在 App 之外挂载。
|
||||
// 挂在 App 内会只存在于主界面分支上，登录页/加载页没有背景。
|
||||
check(
|
||||
'启动时套用背景且挂在 App 之外',
|
||||
/initBackground\(\)/.test(main) && /className="app-backdrop"/.test(main),
|
||||
'缺少 initBackground 或背景层不在 App 外'
|
||||
);
|
||||
|
||||
// 10) 存储键与归一化入口存在（旧数据/脏数据不能让页面白屏）。
|
||||
check(
|
||||
'有独立存储键与脏数据归一化',
|
||||
/STORAGE_KEY\s*=\s*'agentmail\.background'/.test(store) && /normalizeBackground/.test(store)
|
||||
);
|
||||
|
||||
// 11) 图片必须压缩后再存，且有明确上限。
|
||||
// 手机直出照片 4–8MB，直接塞 localStorage 会超配额并抛异常 ——
|
||||
// 用户看到的是「选了图片没反应」。
|
||||
check(
|
||||
'图片有缩放与体积上限',
|
||||
/MAX_EDGE\s*=\s*\d+/.test(store) &&
|
||||
/MAX_DATA_URL_BYTES\s*=\s*[\d_]+/.test(store) &&
|
||||
/drawScaled/.test(store)
|
||||
);
|
||||
|
||||
// 12) 失败必须给出原因，不能静默。
|
||||
check(
|
||||
'图片处理失败返回原因',
|
||||
/ok:\s*false;\s*reason:\s*string/.test(store) && /role="alert"/.test(picker)
|
||||
);
|
||||
|
||||
// 13) 背景是装饰偏好，写 DOM 失败不得抛出打断操作。
|
||||
check(
|
||||
'背景写入 DOM 前有环境判断',
|
||||
/typeof document === 'undefined'/.test(css.slice(0, 0) + store)
|
||||
);
|
||||
|
||||
// 14) 动效必须尊重 prefers-reduced-motion。
|
||||
check(
|
||||
'尊重 prefers-reduced-motion',
|
||||
/@media\s*\(prefers-reduced-motion:\s*reduce\)/.test(css)
|
||||
);
|
||||
|
||||
// 15) 组件里不得出现未映射色族（emerald/purple 等会绕过主题）。
|
||||
const compDir = join(here, '../src/components');
|
||||
const unmapped = [];
|
||||
for (const f of readdirSync(compDir).filter(x => x.endsWith('.tsx'))) {
|
||||
const src = readFileSync(join(compDir, f), 'utf8');
|
||||
if (/(?:bg|text|border)-(?:emerald|purple)-\d+/.test(src)) unmapped.push(f);
|
||||
}
|
||||
check('新组件未使用未映射色族', unmapped.length === 0, unmapped.join(' '));
|
||||
|
||||
console.log(`\n背景：${pass} 通过${fail ? `，${fail} 失败` : ''}`);
|
||||
process.exit(fail ? 1 : 0);
|
||||
Reference in New Issue
Block a user