From 26179e83dda4804d55ec760cfcb10c574d4792eb Mon Sep 17 00:00:00 2001
From: Stev_Wang <304865932@qq.com>
Date: Wed, 4 Nov 2026 17:18:34 +0800
Subject: [PATCH] =?UTF-8?q?fix(web):=20=E4=BF=AE=E5=A4=8D=E9=A6=96?=
 =?UTF-8?q?=E5=B1=8F=E6=B7=B1=E8=89=B2=E7=94=BB=E5=B8=83=E5=AF=BC=E8=87=B4?=
 =?UTF-8?q?=E7=9A=84=E9=BB=91=E5=B1=8F=E9=97=AA=E7=83=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

背景：
index.html 声明 color-scheme=dark，与全站浅色主题（Cloud Blue）冲突。
浏览器在样式表与 JS 就绪前会按深色绘制默认画布，导致打开任意页面时短暂黑屏。

改动：
- apps/web/index.html：color-scheme 改为 light，并在 head 内联首屏兜底底色 #f5f7fa
- packages/ui/src/theme/tokens.css：:root 锁定 color-scheme: light，避免系统深色偏好影响控件
- apps/web/src/shell.spec.ts：新增护栏，禁止 dark 声明并校验兜底底色与 --lx-color-bg-app 一致

影响面：
仅 Web 外壳首屏绘制与主题声明，不涉及接口、数据与业务逻辑；
浅色主题下视觉无变化，系统深色偏好场景下保持浅色。

回滚方式：
git revert 本提交即可恢复原状。

验证证据：
- Playwright 阻断入口模块实测首帧：修复前 #0f0f0f 黑屏，修复后 rgb(245, 247, 250)
- pnpm --filter @lingxi/web test：33 个文件 / 189 个用例通过
- pnpm lint / pnpm format:check / pnpm typecheck / pnpm build 全绿
- pnpm ci:local 全部门禁通过（248.5s，含构建、集成测试、契约检查与 E2E 冒烟）
---
 apps/web/index.html              | 16 +++++++++++++++-
 apps/web/src/shell.spec.ts       | 26 ++++++++++++++++++++++++++
 packages/ui/src/theme/tokens.css |  3 +++
 3 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 apps/web/src/shell.spec.ts

diff --git a/apps/web/index.html b/apps/web/index.html
index a6d6327..2afd1bc 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -3,8 +3,22 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="color-scheme" content="dark" />
+    <!-- 本期仅浅色主题（Cloud Blue）：声明 light，避免浏览器在样式加载前按深色绘制画布导致黑屏 -->
+    <meta name="color-scheme" content="light" />
     <title>灵犀 · 信息流素材生产平台</title>
+    <!-- 首屏兜底：样式表与 JS 就绪前先铺应用底色，避免默认画布（黑/白）闪烁 -->
+    <style>
+      html,
+      body {
+        color-scheme: light;
+        /* 与 packages/ui/src/theme/tokens.css 的 --lx-color-bg-app 保持一致 */
+        background-color: #f5f7fa;
+      }
+
+      body {
+        margin: 0;
+      }
+    </style>
   </head>
   <body theme-mode="light">
     <div id="root"></div>
diff --git a/apps/web/src/shell.spec.ts b/apps/web/src/shell.spec.ts
new file mode 100644
index 0000000..bb4eee7
--- /dev/null
+++ b/apps/web/src/shell.spec.ts
@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+
+import { describe, expect, it } from 'vitest';
+
+/** 从 spec 所在目录解析仓库内文件，避免依赖测试运行目录 */
+function readRepoFile(relativePath: string): string {
+  return readFileSync(new URL(relativePath, import.meta.url), 'utf8');
+}
+
+/** HTML 外壳不支持暗色模式：深色 color-scheme 会让浏览器在样式加载前画黑屏 */
+describe('HTML 外壳首屏防闪烁', () => {
+  const html = readRepoFile('../index.html');
+  const tokens = readRepoFile('../../../packages/ui/src/theme/tokens.css');
+
+  it('只声明浅色 color-scheme，不声明 dark', () => {
+    expect(html).not.toMatch(/name="color-scheme"\s+content="dark"/);
+    expect(html).toMatch(/name="color-scheme"\s+content="light"/);
+    expect(html).toMatch(/color-scheme:\s*light/);
+  });
+
+  it('预置的应用底色与主题 token 一致', () => {
+    const appBackground = /--lx-color-bg-app:\s*(#[0-9a-fA-F]{6})/.exec(tokens)?.[1] ?? '';
+    expect(appBackground).not.toBe('');
+    expect(html.toLowerCase()).toContain(`background-color: ${appBackground.toLowerCase()}`);
+  });
+});
diff --git a/packages/ui/src/theme/tokens.css b/packages/ui/src/theme/tokens.css
index ac41160..eb0c2dc 100644
--- a/packages/ui/src/theme/tokens.css
+++ b/packages/ui/src/theme/tokens.css
@@ -1,4 +1,7 @@
 :root {
+  /* 本期仅浅色主题（Cloud Blue），不提供暗色模式；锁定浅色方案，避免系统深色偏好影响表单控件与滚动条 */
+  color-scheme: light;
+
   /* 方向 A · 云白蓝（Cloud Blue）：传统企业后台骨架 + 现代浅色质感 */
   --lx-color-bg-app: #f5f7fa;
   --lx-color-bg-panel: #ffffff;