/** * 深色主题的结构性检查。 * * 判据全部是「源码里存在/不存在某种形态」,不需要浏览器 —— * 真正的视觉验收靠手工脚本(test/manual/theme-verify.mjs)。 * * 这些检查存在的理由:深色模式的 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'); const cfg = read('../tailwind.config.js'); const html = read('../index.html'); // 1) tailwind 必须走 class 策略。 // media 策略下主题无法被人显式选择 —— 白天想开深色就做不到。 check('darkMode 为 class 策略', /darkMode:\s*['"]class['"]/.test(cfg)); // 2) 颜色必须经 CSS 变量。写死十六进制的话深色模式无从切换。 check( '调色板指向 CSS 变量', cfg.includes('rgb(var(') && cfg.includes(''), '缺少 rgb(var(--x) / ) 形态' ); // 3) 变量值必须是 RGB 三元组而不是 #hex。 // 代码里有 bg-blue-50/70 这类透明度修饰符,#hex 会生成无效 CSS, // 那些半透明高亮静默失效(不报错,只是不透明)。 const varLines = css.match(/--c-[a-z]+-?\d*:\s*[^;]+;/g) || []; const hexVars = varLines.filter(l => l.includes('#')); check( '色板变量存 RGB 三元组而非 #hex', varLines.length >= 30 && hexVars.length === 0, hexVars.length ? `${hexVars.length} 个变量是 hex:${hexVars[0]}` : `只找到 ${varLines.length} 个变量` ); // 4) 必须有 .dark 覆盖块,且覆盖了同样多的变量。 // 漏掉的那些会在深色下保持浅色值 —— 那正是白底白字的来源。 const lightBlock = css.slice(css.indexOf(':root'), css.indexOf('.dark')); const darkBlock = css.slice(css.indexOf('.dark {')); const lightVars = new Set((lightBlock.match(/--c-[\w-]+(?=:)/g) || [])); const darkVars = new Set((darkBlock.match(/--c-[\w-]+(?=:)/g) || [])); const missing = [...lightVars].filter(v => !darkVars.has(v)); check( '.dark 覆盖了全部色板变量', lightVars.size >= 15 && missing.length === 0, missing.length ? `深色缺 ${missing.length} 个:${missing.slice(0, 5).join(', ')}` : `浅色只有 ${lightVars.size} 个` ); // 5) 灰阶必须真的反转:深色的 white 要比 gray-900 暗。 // 不反转的话组件里的 `bg-white text-gray-900` 在深色下依然是白底黑字。 const lum = (block, name) => { const m = block.match(new RegExp(`--c-${name}:\\s*(\\d+)\\s+(\\d+)\\s+(\\d+)`)); if (!m) return null; return (Number(m[1]) + Number(m[2]) + Number(m[3])) / 3; }; const darkWhite = lum(darkBlock, 'white'); const darkG900 = lum(darkBlock, 'gray-900'); check( '深色下灰阶已反转(white 比 gray-900 暗)', darkWhite !== null && darkG900 !== null && darkWhite < darkG900, `white=${darkWhite} gray-900=${darkG900}` ); // 6) 深色的页面底(gray-50)必须比卡片(white)更暗。 // 浅色下页面底比卡片浅,深色下要反过来 —— 否则卡片陷进背景失去边界。 const darkG50 = lum(darkBlock, 'gray-50'); check( '深色下页面底比卡片更暗', darkG50 !== null && darkWhite !== null && darkG50 < darkWhite, `gray-50=${darkG50} white=${darkWhite}` ); // 7) 次要文字(gray-400/500)在深色下必须提亮。 // 照搬浅色值只有约 2:1 对比度,远低于 WCAG AA 的 4.5:1 —— // 实际效果是「看得见但读不动」。 const lightG400 = lum(lightBlock, 'gray-400'); const darkG400 = lum(darkBlock, 'gray-400'); check( '深色下次要文字未沿用浅色值', darkG400 !== null && lightG400 !== null && Math.abs(darkG400 - lightG400) > 5, `light=${lightG400} dark=${darkG400}` ); // 8) color-scheme 两处都要设。 // 不设的话深色页面上会出现浅色滚动条与白底的 autofill 输入框。 check( ':root 与 .dark 都声明 color-scheme', /color-scheme:\s*light/.test(lightBlock) && /color-scheme:\s*dark/.test(darkBlock) ); // 9) index.html 必须有同步内联脚本消除首帧闪屏。 // bundle 有几百 KB,从 HTML 解析完到 React 挂载之间页面是 body 默认色 —— // 深色用户每次刷新都被闪一下白屏。外链或 defer 都晚于首次绘制。 check( 'index.html 内联防闪屏脚本', html.includes('agentmail.theme') && html.includes('prefers-color-scheme') && html.includes("classList.add('dark')") && !/]+(src=|defer)[^>]*>[\s\S]*?agentmail\.theme/.test(html), '缺少同步内联脚本' ); // 10) 内联脚本与 themeStore 必须用同一个 localStorage 键。 // 不一致的后果是首帧按 A 键渲染、React 挂载后按 B 键重渲染 —— 闪一下再变回去 const store = read('../src/stores/themeStore.ts'); const keyInStore = store.match(/STORAGE_KEY\s*=\s*'([^']+)'/); check( '内联脚本与 themeStore 共用同一 storage 键', keyInStore !== null && html.includes(`'${keyInStore[1]}'`), keyInStore ? `store 用 ${keyInStore[1]}` : '未找到 STORAGE_KEY' ); // 11) body 必须有显式底色:移动端橡皮筋回弹露出的是 body 背景, // 不设的话深色下滑到边界会闪出白边。 check( 'body 有显式主题底色', /body\s*\{[^}]*background-color:\s*rgb\(var\(--c-/.test(css) ); // 12) 组件里不该残留写死的十六进制颜色。 // 它们不经变量,深色模式下不会变 —— 而这类遗漏只有肉眼能发现。 const compDir = join(here, '../src/components'); const offenders = []; for (const f of readdirSync(compDir).filter(x => x.endsWith('.tsx'))) { const src = readFileSync(join(compDir, f), 'utf8'); // 只看 className 与 style 里的颜色;SVG 的 currentColor 不算 const hits = (src.match(/#[0-9a-fA-F]{3,6}\b/g) || []); if (hits.length) offenders.push(`${f}(${hits.join(',')})`); } check( '组件里没有写死的十六进制颜色', offenders.length === 0, offenders.join(' ') ); // 13) 主题三态:system 不能被当成 light 的别名。 // 只给开关的话,白天设浅色之后晚上系统切深色应用不会跟着变 check( 'ThemePref 是三态且含 system', /'light'\s*\|\s*'dark'\s*\|\s*'system'/.test(store) && store.includes("=== 'system'") ); // 14) 只有 pref 为 system 时才跟随系统变化。 // 显式选了 light/dark 的人不该因为日落被切换主题 check( '仅 system 偏好跟随系统变化', /if\s*\(pref === 'system'\)/.test(store) ); // 15) text-white 必须与 bg-white 用不同的变量。 // `white` 服务两种冲突用途:卡片表面(深色下变暗)与彩色按钮上的文字 // (深色下必须保持浅色)。共用一个变量时后者跟着变暗 —— 实测激活导航项的 // 「收件」在 bg-chrome-700 上只剩 1.34:1,几乎看不见。 check( 'textColor.white 指向独立变量(不跟 bg-white 一起反转)', /textColor:\s*\{[^}]*white:\s*withAlpha\('--c-on-accent'\)/.test(cfg) && /--c-on-accent:/.test(lightBlock) && /--c-on-accent:/.test(darkBlock) ); // 16) --c-on-accent 在深色下必须仍然是浅色。 // 它变暗就是上一条描述的那个 bug。 const onAccentDark = lum(darkBlock, 'on-accent'); check( '深色下 on-accent 仍是浅色', onAccentDark !== null && onAccentDark > 200, `on-accent 亮度 ${onAccentDark}` ); // 17) 强调色(blue/red/...)不走变量。 // 它们跟着反转会让主按钮在深色页面上失去「这是主操作」的视觉重量, // 而且白字落在变暗的 blue-600 上对比度会掉到 3:1 以下。 check( '强调色为固定值,不随主题反转', !/blue:\s*accent\(/.test(cfg) && /blue:\s*\{\s*50:\s*'#/.test(cfg) ); // 18) 应用框架(侧栏 / 底部导航)必须有独立色阶。 // 它在浅色模式下本来就是深色的 —— 并入反转的 gray 之后深色模式下会变成 // 近白色,比内容区还亮,整个层次翻过来(实测 rgb(243,245,248))。 check( '框架有独立的 chrome 色阶', /chrome:\s*\{/.test(cfg) && /--c-chrome-900:/.test(lightBlock) && /--c-chrome-900:/.test(darkBlock) ); // 19) 深色下框架必须比内容区更沉(保持浅色下就有的层次关系)。 const chromeDark = lum(darkBlock, 'chrome-900'); check( '深色下框架比内容区更暗', chromeDark !== null && darkG50 !== null && chromeDark < darkG50, `chrome-900=${chromeDark} gray-50=${darkG50}` ); // 20) 侧栏与底部导航里不该残留 slate-*(那条色阶指向反转的 gray)。 const chromeFiles = ['Sidebar', 'NarrowNav']; const slateLeft = []; for (const f of chromeFiles) { const src = readFileSync(join(here, `../src/components/${f}.tsx`), 'utf8'); const hits = src.match(/(?:bg|text|border|hover:bg|hover:text|active:bg|ring)-slate-\d+/g) || []; if (hits.length) slateLeft.push(`${f}: ${hits.join(',')}`); } check('框架组件已全部改用 chrome 色阶', slateLeft.length === 0, slateLeft.join(' | ')); console.log(`\n主题:${pass} 通过${fail ? `,${fail} 失败` : ''}`); process.exit(fail ? 1 : 0);