node-resource-utils 0.0.0-stage → 1.1.8

package/resources/src/lib/appearance.ts

@@ -0,0 +1,643 @@
+/**
+ * 外观设置 —— 皮肤（配色 + 材质）与字体大小的唯一来源。
+ *
+ * 为什么要有这一层：
+ *   题目一换，页面全是新写的，但"换个外观"这种全站能力不能跟着重写。
+ *   所以这里只描述 **token**（颜色、阴影、侧栏材质、品牌区渐变），
+ *   页面永远只引用语义（MILITARY.primary / var(--wb-text)），
+ *   皮肤切换就是把另一套 token 换上去，页面代码一行都不用动。
+ *
+ * 三层结构：
+ *   1. `SKINS`：每套皮肤的字面值（hex / 渐变串 / rgba）。
+ *      —— 图表（canvas 不认 CSS 变量）和 SSR 首屏需要字面值，所以必须留在 JS 里。
+ *   2. `buildAppearanceCss()`：把字面值编译成 CSS 变量（`--wb-*`），
+ *      由根布局一次性写进 <head>。**所有皮肤**的变量块都在首屏 HTML 里，
+ *      切换皮肤只改 <html data-wb-skin>，不动任何组件 —— 零重排、零闪烁。
+ *   3. `buildBootScript()`：首屏渲染前跑的一行脚本，把本机保存的皮肤/字号
+ *      写回 <html>，避免"先按原版画一遍再跳成暗色"。
+ *
+ * 新增一套皮肤 = 往 `SKINS` 里加一条（含字面色板 + 侧栏/品牌区材质），
+ * 再在 `SKIN_LIST` 里排好序。不需要改任何页面。
+ *
+ * 新增一档字号 = 往 `FONT_SCALES` 里加一条（scale 是乘数）。
+ * 页面里的字号统一用 `fs(13)`（见 lib/theme.ts），它会乘上 `--wb-fs`。
+ */
+
+export type SkinId = 'classic' | 'minimal' | 'deck';
+export type FontId = 'sm' | 'md' | 'lg' | 'xl';
+
+/** 本地保存键。改结构才升版本号（v1 起） */
+export const APPEARANCE_KEY = 'wb.appearance.v1';
+
+/** 字体栈：三套皮肤共用，离线环境只有系统字体可用 */
+export const FONT_STACK =
+  "system-ui, -apple-system, 'Segoe UI', 'Microsoft YaHei', 'PingFang SC', sans-serif";
+
+export interface AppearanceSettings {
+  skin: SkinId;
+  font: FontId;
+}
+
+export const DEFAULT_APPEARANCE: AppearanceSettings = { skin: 'classic', font: 'md' };
+
+/* ------------------------------------------------------------------ *
+ * 字体档位
+ * ------------------------------------------------------------------ */
+
+export interface FontScale {
+  id: FontId;
+  name: string;
+  /** 乘数：页面字号 `fs(13)` → 13px * scale */
+  scale: number;
+  hint: string;
+}
+
+export const FONT_SCALES: FontScale[] = [
+  { id: 'sm', name: '小', scale: 0.9, hint: '一屏能看更多行' },
+  { id: 'md', name: '标准', scale: 1, hint: '默认' },
+  { id: 'lg', name: '大', scale: 1.1, hint: '长时间阅读更轻松' },
+  { id: 'xl', name: '特大', scale: 1.2, hint: '投屏 / 视力不佳时用' },
+];
+
+export function fontScaleOf(id: FontId): number {
+  return (FONT_SCALES.find((f) => f.id === id) ?? FONT_SCALES[1]).scale;
+}
+
+/* ------------------------------------------------------------------ *
+ * 皮肤
+ * ------------------------------------------------------------------ */
+
+/** 字面色板：图表、canvas、以及任何"必须有真实颜色值"的地方用它 */
+export interface SkinPalette {
+  primary: string;
+  primaryHover: string;
+  primaryActive: string;
+  /** 主色上的文字色（深色皮肤的主色偏亮，压深文字更清楚） */
+  onPrimary: string;
+  primaryDark: string;
+  primaryDeep: string;
+  soft: string;
+  softStrong: string;
+  accent: string;
+  accentSoft: string;
+  bg: string;
+  card: string;
+  /** 内容区（卡片外那层纸） */
+  paper: string;
+  border: string;
+  borderSoft: string;
+  text: string;
+  text2: string;
+  text3: string;
+  success: string;
+  warning: string;
+  error: string;
+  successBg: string;
+  warningBg: string;
+  errorBg: string;
+  dark: boolean;
+  radius: number;
+  shadow: string;
+  shadowSm: string;
+  /** 图表默认色板（canvas 用字面值） */
+  chart: string[];
+  /** 图谱连线（canvas 用字面值；深色皮肤要提亮，否则线全糊在底色里） */
+  edge: string;
+}
+
+/** 侧边栏材质：深色皮肤是作训服/舱壁，浅色皮肤是纸面 */
+export interface SiderTokens {
+  /** 作为 background-image，'none' 表示只用底色 */
+  bg: string;
+  dark: boolean;
+  text: string;
+  textStrong: string;
+  textMuted: string;
+  hover: string;
+  active: string;
+  line: string;
+  /** 选中项左侧那条定位条 */
+  mark: string;
+  border: string;
+}
+
+/** 品牌区（登录页左栏、AI 指挥带、报告封面） */
+export interface BrandTokens {
+  /** 整块品牌底（登录页整屏） */
+  bg: string;
+  /** 内嵌的小指挥带（AI 页、报告封面） */
+  panel: string;
+  text: string;
+  textSoft: string;
+  textMuted: string;
+  /** 眉标（kicker）颜色 */
+  kicker: string;
+  line: string;
+  /** 四角定位角标 / 强调描边 */
+  tint: string;
+  /** 半透明玻璃块（指标胶囊） */
+  glass: string;
+  shadow: string;
+}
+
+/**
+ * 操作反馈层（components/feedback/motion.css）的取材：
+ * 悬停/按下的阴影与描边。深色皮肤不能沿用"深色半透明阴影"，
+ * 否则抬起动作完全看不见，得换成一点白光。
+ */
+export interface MotionTokens {
+  shadeIdle: string;
+  shadeHover: string;
+  shadePress: string;
+  borderIdle: string;
+  borderHover: string;
+  surfaceHover: string;
+  /** 「结果落在这里」那一闪的底色 */
+  flash: string;
+}
+
+export interface Skin {
+  id: SkinId;
+  name: string;
+  /** 一句话描述，面板里显示 */
+  blurb: string;
+  palette: SkinPalette;
+  sider: SiderTokens;
+  brand: BrandTokens;
+  motion: MotionTokens;
+  skeleton: { a: string; b: string };
+  scrollbar: { a: string; b: string };
+  selection: string;
+  selectionText: string;
+  /** 皮肤独有的装饰规则（只放 shell 级签名元素，不碰业务页） */
+  extraCss: string;
+}
+
+/* ----------------------------- 1. 原版 ----------------------------- */
+
+const classic: Skin = {
+  id: 'classic',
+  name: '原版',
+  blurb: '军绿与黄铜，纸感底纹',
+  palette: {
+    primary: '#4E5F3C',
+    primaryHover: '#61764D',
+    primaryActive: '#3D4C2F',
+    onPrimary: '#FFFFFF',
+    primaryDark: '#2B3721',
+    primaryDeep: '#1F2918',
+    soft: '#EDF0E3',
+    softStrong: '#DCE3CC',
+    accent: '#C0A97E',
+    accentSoft: '#F4EEDF',
+    bg: '#F2F3EA',
+    card: '#FFFFFF',
+    paper: '#F8F9F3',
+    border: '#E3E5D6',
+    borderSoft: '#EEF0E5',
+    text: '#202619',
+    text2: '#5B6252',
+    text3: '#8B9181',
+    success: '#5E7C4E',
+    warning: '#B08A3E',
+    error: '#B4472F',
+    successBg: '#ECF2E4',
+    warningBg: '#F7F0DE',
+    errorBg: '#F9ECE8',
+    dark: false,
+    radius: 8,
+    shadow: '0 8px 24px rgba(32,38,25,.10)',
+    shadowSm: '0 1px 2px rgba(32,38,25,.05)',
+    chart: ['#4E5F3C', '#7C8F63', '#B99C6B', '#5F7050', '#9A7B52'],
+    edge: '#C8CEB8',
+  },
+  sider: {
+    bg: 'repeating-linear-gradient(135deg, rgba(255,255,255,.028) 0 2px, transparent 2px 10px), linear-gradient(180deg, #2B3721 0%, #1F2918 100%)',
+    dark: true,
+    text: 'rgba(245,246,238,.72)',
+    textStrong: '#F5F6EE',
+    textMuted: 'rgba(245,246,238,.34)',
+    hover: 'rgba(255,255,255,.07)',
+    active: 'rgba(192,169,126,.16)',
+    line: 'rgba(255,255,255,.07)',
+    mark: '#C0A97E',
+    border: 'rgba(0,0,0,.28)',
+  },
+  brand: {
+    bg:
+      'radial-gradient(900px 520px at 10% 5%, rgba(192,169,126,.18), transparent 62%), ' +
+      'repeating-linear-gradient(135deg, rgba(255,255,255,.03) 0 2px, transparent 2px 14px), ' +
+      'linear-gradient(135deg, #1C2415 0%, #2B3721 46%, #43542F 100%)',
+    panel:
+      'radial-gradient(600px 220px at 8% 0%, rgba(192,169,126,.18), transparent 65%), ' +
+      'repeating-linear-gradient(135deg, rgba(255,255,255,.035) 0 2px, transparent 2px 12px), ' +
+      'linear-gradient(118deg, #1F2918 0%, #2B3721 52%, #47583A 100%)',
+    text: '#F7F8F1',
+    textSoft: 'rgba(240,242,232,.78)',
+    textMuted: 'rgba(240,242,232,.5)',
+    kicker: '#CBB98D',
+    line: 'rgba(192,169,126,.22)',
+    tint: 'rgba(192,169,126,.5)',
+    glass: 'rgba(255,255,255,.06)',
+    shadow: '0 18px 50px rgba(20,26,15,.3)',
+  },
+  motion: {
+    shadeIdle: 'rgba(32,38,25,.05)',
+    shadeHover: 'rgba(32,38,25,.1)',
+    shadePress: 'rgba(32,38,25,.07)',
+    borderIdle: '#E3E5D6',
+    borderHover: '#D5DAC4',
+    surfaceHover: '#FCFDF6',
+    flash: 'rgba(192,169,126,.32)',
+  },
+  skeleton: { a: '#EDF0E3', b: '#F6F7EF' },
+  scrollbar: { a: '#C9CFBA', b: '#A9B195' },
+  selection: 'rgba(78,95,60,.2)',
+  selectionText: '#1B2116',
+  extraCss: '',
+};
+
+/* ----------------------------- 2. 简洁 ----------------------------- */
+
+/**
+ * 简洁版：纸白 + 发丝线 + 石墨青。
+ * 签名元素是"浅色侧栏 + 一条 2px 定位线"——把原版的深色面料整个翻过来，
+ * 不靠阴影堆层次，只靠留白和 1px 线的深浅差。
+ */
+const minimal: Skin = {
+  id: 'minimal',
+  name: '简洁',
+  blurb: '纸白与发丝线，浅色侧栏',
+  palette: {
+    primary: '#2C4A52',
+    primaryHover: '#3C6270',
+    primaryActive: '#213B42',
+    onPrimary: '#FFFFFF',
+    primaryDark: '#2C4A52',
+    primaryDeep: '#1B2E34',
+    soft: '#EDF1F3',
+    softStrong: '#DCE4E8',
+    accent: '#9BA8AE',
+    accentSoft: '#F2F5F6',
+    bg: '#F6F7F8',
+    card: '#FFFFFF',
+    paper: '#FFFFFF',
+    border: '#E5E8EA',
+    borderSoft: '#EFF1F2',
+    text: '#16191C',
+    text2: '#5A646B',
+    text3: '#8B959C',
+    success: '#2E7D5B',
+    warning: '#B07C2E',
+    error: '#B4453C',
+    successBg: '#E8F3EE',
+    warningBg: '#F8F1E2',
+    errorBg: '#F9EBE9',
+    dark: false,
+    radius: 6,
+    shadow: '0 6px 20px rgba(20,35,42,.08)',
+    shadowSm: '0 1px 0 rgba(20,35,42,.04)',
+    chart: ['#2C4A52', '#5C7C86', '#8FA6AD', '#3E6470', '#B3C2C7'],
+    edge: '#D2DDE2',
+  },
+  sider: {
+    bg: 'linear-gradient(180deg, #FFFFFF 0%, #FCFDFD 100%)',
+    dark: false,
+    text: '#55626A',
+    textStrong: '#16191C',
+    textMuted: '#9AA6AD',
+    hover: '#F2F5F6',
+    active: '#E9EFF2',
+    line: '#EDF1F3',
+    mark: '#2C4A52',
+    border: '#E5E8EA',
+  },
+  brand: {
+    bg:
+      'radial-gradient(760px 520px at 8% 0%, #E9F0F2, transparent 62%), ' +
+      'linear-gradient(160deg, #FFFFFF 0%, #F5F8F9 55%, #E7EDEF 100%)',
+    panel: 'linear-gradient(160deg, #FFFFFF 0%, #F2F6F7 100%)',
+    text: '#16191C',
+    textSoft: '#4E5A61',
+    textMuted: '#7C8990',
+    kicker: '#2C4A52',
+    line: '#DFE6E9',
+    tint: '#B9C9CE',
+    glass: 'rgba(255,255,255,.72)',
+    shadow: '0 18px 50px rgba(20,35,42,.12)',
+  },
+  motion: {
+    shadeIdle: 'rgba(20,35,42,.04)',
+    shadeHover: 'rgba(20,35,42,.09)',
+    shadePress: 'rgba(20,35,42,.06)',
+    borderIdle: '#E5E8EA',
+    borderHover: '#D2DCE0',
+    surfaceHover: '#FAFCFC',
+    flash: 'rgba(44,74,82,.16)',
+  },
+  skeleton: { a: '#EFF2F4', b: '#FAFBFC' },
+  scrollbar: { a: '#D7DEE1', b: '#BFCACE' },
+  selection: 'rgba(44,74,82,.16)',
+  selectionText: '#16191C',
+  extraCss: `
+/* 简洁版：顶栏不投影，只留一条发丝线；卡片靠线不靠影 */
+html[data-wb-skin='minimal'] .wb-header { box-shadow: none; }
+html[data-wb-skin='minimal'] .ant-card { box-shadow: none !important; }
+/* 登录页：品牌区与表单区之间只放一条发丝线，其余交给留白 */
+html[data-wb-skin='minimal'] .wb-brand-copy { border-right: 1px solid var(--wb-border); }
+html[data-wb-skin='minimal'] .wb-brand-card .ant-card { border-color: var(--wb-border); }
+`,
+};
+
+/* ----------------------------- 3. 炫酷 ----------------------------- */
+
+/**
+ * 炫酷版：深色指挥舱。
+ * 底色压到近黑，面板靠 1px 荧光描边 + 顶部微光分层；
+ * 主色是荧光橄榄（夜间可读性比纯青绿更好），琥珀只用在极小面积。
+ * 签名元素：侧栏的竖向细网格 + 顶栏底部那条冷光。
+ */
+const deck: Skin = {
+  id: 'deck',
+  name: '炫酷',
+  blurb: '深色指挥舱，荧光描边',
+  palette: {
+    primary: '#9FD166',
+    primaryHover: '#B7E083',
+    primaryActive: '#86B94F',
+    onPrimary: '#0B1208',
+    primaryDark: '#0C1710',
+    primaryDeep: '#060B08',
+    soft: 'rgba(159,209,102,.14)',
+    softStrong: 'rgba(159,209,102,.24)',
+    accent: '#E6B968',
+    accentSoft: 'rgba(230,185,104,.16)',
+    bg: '#080D0A',
+    card: '#111A14',
+    paper: '#0C1210',
+    border: '#25322B',
+    borderSoft: '#1B2621',
+    text: '#E7F0E4',
+    text2: '#A4B3A0',
+    text3: '#6F7F6B',
+    success: '#6FD39A',
+    warning: '#E6B968',
+    error: '#FF7E6B',
+    successBg: 'rgba(111,211,154,.14)',
+    warningBg: 'rgba(230,185,104,.14)',
+    errorBg: 'rgba(255,126,107,.14)',
+    dark: true,
+    radius: 10,
+    shadow: '0 0 0 1px rgba(159,209,102,.10), 0 10px 28px rgba(0,0,0,.5)',
+    shadowSm: '0 1px 2px rgba(0,0,0,.55)',
+    chart: ['#9FD166', '#5FD3C0', '#E6B968', '#7FA5FF', '#C58BFF'],
+    edge: '#44614F',
+  },
+  sider: {
+    bg:
+      'repeating-linear-gradient(90deg, rgba(159,209,102,.05) 0 1px, transparent 1px 34px), ' +
+      'linear-gradient(180deg, #0C1710 0%, #060B08 100%)',
+    dark: true,
+    text: 'rgba(231,240,228,.74)',
+    textStrong: '#EAF3E7',
+    textMuted: 'rgba(231,240,228,.38)',
+    hover: 'rgba(159,209,102,.08)',
+    active: 'rgba(159,209,102,.16)',
+    line: 'rgba(159,209,102,.12)',
+    mark: '#9FD166',
+    border: '#101A13',
+  },
+  brand: {
+    bg:
+      'radial-gradient(760px 420px at 12% 0%, rgba(159,209,102,.18), transparent 62%), ' +
+      'radial-gradient(520px 360px at 92% 88%, rgba(230,185,104,.12), transparent 60%), ' +
+      'linear-gradient(150deg, #070C09 0%, #0F1A12 55%, #16241A 100%)',
+    panel:
+      'radial-gradient(560px 220px at 10% 0%, rgba(159,209,102,.16), transparent 65%), ' +
+      'linear-gradient(118deg, #0A120C 0%, #101C13 52%, #16281A 100%)',
+    text: '#EAF3E7',
+    textSoft: 'rgba(231,240,228,.78)',
+    textMuted: 'rgba(231,240,228,.5)',
+    kicker: '#E6B968',
+    line: 'rgba(159,209,102,.24)',
+    tint: 'rgba(159,209,102,.45)',
+    glass: 'rgba(255,255,255,.05)',
+    shadow: '0 24px 60px rgba(0,0,0,.55)',
+  },
+  motion: {
+    shadeIdle: 'rgba(255,255,255,.05)',
+    shadeHover: 'rgba(255,255,255,.09)',
+    shadePress: 'rgba(255,255,255,.07)',
+    borderIdle: '#25322B',
+    borderHover: '#3A4B40',
+    surfaceHover: '#16211A',
+    flash: 'rgba(159,209,102,.24)',
+  },
+  skeleton: { a: '#18221B', b: '#223028' },
+  scrollbar: { a: '#27352C', b: '#38493C' },
+  selection: 'rgba(159,209,102,.22)',
+  selectionText: '#EAF3E7',
+  extraCss: `
+/* 炫酷版：顶栏底部一道冷光，内容区一圈极淡的舱壁描边 */
+html[data-wb-skin='deck'] .wb-header {
+  box-shadow: inset 0 -1px 0 rgba(159,209,102,.22), 0 1px 28px rgba(159,209,102,.07);
+}
+html[data-wb-skin='deck'] .wb-content { box-shadow: inset 0 0 0 1px rgba(159,209,102,.07); }
+html[data-wb-skin='deck'] .ant-card { box-shadow: inset 0 1px 0 rgba(255,255,255,.03); }
+/* 登录卡片：暗底上靠一圈冷光而不是投影分层 */
+html[data-wb-skin='deck'] .wb-brand-card .ant-card {
+  box-shadow: 0 0 0 1px rgba(159,209,102,.16), 0 26px 60px rgba(0,0,0,.6);
+}
+`,
+};
+
+export const SKINS: Record<SkinId, Skin> = { classic, minimal, deck };
+
+/** 面板里的展示顺序：原版永远排第一，它是基准 */
+export const SKIN_LIST: Skin[] = [classic, minimal, deck];
+
+/* ------------------------------------------------------------------ *
+ * token → CSS 变量
+ * ------------------------------------------------------------------ */
+
+/**
+ * 语义变量表。页面/组件只准用这些名字，不许自己拼 rgba。
+ * 新增视觉语义时先在这里加，再去 SKINS 里给三套皮肤各填一个值。
+ */
+export function varsOfSkin(s: Skin): Record<string, string> {
+  const p = s.palette;
+  return {
+    '--wb-primary': p.primary,
+    '--wb-primary-hover': p.primaryHover,
+    '--wb-primary-active': p.primaryActive,
+    '--wb-on-primary': p.onPrimary,
+    '--wb-primary-dark': p.primaryDark,
+    '--wb-primary-deep': p.primaryDeep,
+    '--wb-soft': p.soft,
+    '--wb-soft-strong': p.softStrong,
+    '--wb-accent': p.accent,
+    '--wb-accent-soft': p.accentSoft,
+    '--wb-bg': p.bg,
+    '--wb-card': p.card,
+    '--wb-paper': p.paper,
+    '--wb-border': p.border,
+    '--wb-border-soft': p.borderSoft,
+    '--wb-text': p.text,
+    '--wb-text-2': p.text2,
+    '--wb-text-3': p.text3,
+    '--wb-success': p.success,
+    '--wb-warning': p.warning,
+    '--wb-error': p.error,
+    '--wb-success-bg': p.successBg,
+    '--wb-warning-bg': p.warningBg,
+    '--wb-error-bg': p.errorBg,
+    '--wb-shadow': p.shadow,
+    '--wb-shadow-sm': p.shadowSm,
+    '--wb-radius': `${p.radius}px`,
+    '--wb-radius-sm': `${Math.max(2, p.radius - 2)}px`,
+    '--wb-sider-bg': s.sider.bg,
+    '--wb-sider-text': s.sider.text,
+    '--wb-sider-text-strong': s.sider.textStrong,
+    '--wb-sider-text-muted': s.sider.textMuted,
+    '--wb-sider-hover': s.sider.hover,
+    '--wb-sider-active': s.sider.active,
+    '--wb-sider-line': s.sider.line,
+    '--wb-sider-mark': s.sider.mark,
+    '--wb-sider-border': s.sider.border,
+    '--wb-brand-bg': s.brand.bg,
+    '--wb-brand-panel': s.brand.panel,
+    '--wb-brand-text': s.brand.text,
+    '--wb-brand-text-soft': s.brand.textSoft,
+    '--wb-brand-text-muted': s.brand.textMuted,
+    '--wb-brand-kicker': s.brand.kicker,
+    '--wb-brand-line': s.brand.line,
+    '--wb-brand-tint': s.brand.tint,
+    '--wb-brand-glass': s.brand.glass,
+    '--wb-brand-shadow': s.brand.shadow,
+    '--wb-skeleton-a': s.skeleton.a,
+    '--wb-skeleton-b': s.skeleton.b,
+    '--wb-scrollbar': s.scrollbar.a,
+    '--wb-scrollbar-hover': s.scrollbar.b,
+    '--wb-selection': s.selection,
+    '--wb-selection-text': s.selectionText,
+    '--wb-shade-idle': s.motion.shadeIdle,
+    '--wb-shade-hover': s.motion.shadeHover,
+    '--wb-shade-press': s.motion.shadePress,
+    '--wb-border-idle': s.motion.borderIdle,
+    '--wb-border-hover': s.motion.borderHover,
+    '--wb-surface-hover': s.motion.surfaceHover,
+    '--wb-flash': s.motion.flash,
+    '--wb-graph-edge': p.edge,
+  };
+}
+
+/** 一次性生成全站外观 CSS：所有皮肤 + 所有字号档 + shell 级签名规则 */
+export function buildAppearanceCss(): string {
+  const skinBlocks = SKIN_LIST.map(
+    (s) =>
+      `html[data-wb-skin='${s.id}']{${Object.entries(varsOfSkin(s))
+        .map(([k, v]) => `${k}:${v}`)
+        .join(';')}}`
+  ).join('\n');
+
+  const fontBlocks = FONT_SCALES.map(
+    (f) => `html[data-wb-font='${f.id}']{--wb-fs:${f.scale}}`
+  ).join('\n');
+
+  const extras = SKIN_LIST.map((s) => s.extraCss).filter(Boolean).join('\n');
+
+  return `/* 外观底座：由 lib/appearance.ts 按皮肤定义生成，勿手改 */
+:root{${Object.entries(varsOfSkin(classic))
+    .map(([k, v]) => `${k}:${v}`)
+    .join(';')};--wb-fs:1}
+${skinBlocks}
+${fontBlocks}
+html{background:var(--wb-bg);color:var(--wb-text)}
+html[data-wb-skin='deck']{color-scheme:dark}
+html[data-wb-skin='classic'],html[data-wb-skin='minimal']{color-scheme:light}
+/* 切换皮肤时让颜色平滑过渡（只过渡颜色类属性，不动布局） */
+html.wb-skin-anim,html.wb-skin-anim *{transition:background-color .18s ease,background-image .18s ease,border-color .18s ease,color .18s ease,box-shadow .18s ease !important}
+@media (prefers-reduced-motion: reduce){html.wb-skin-anim,html.wb-skin-anim *{transition:none !important}}
+${extras}
+`;
+}
+
+/**
+ * 首屏脚本：在 React 挂载前把本机外观写回 <html>。
+ * 必须内联执行（阻塞），否则会先按原版画一帧再跳成暗色。
+ */
+export const APPEARANCE_BOOT = (() => {
+  const skinIds = SKIN_LIST.map((s) => s.id).join('|');
+  const fontIds = FONT_SCALES.map((f) => f.id).join('|');
+  return (
+    `(function(){try{var v=JSON.parse(localStorage.getItem('${APPEARANCE_KEY}')||'null')||{};` +
+    `var e=document.documentElement;` +
+    `if(new RegExp('^(${skinIds})$').test(v.skin))e.dataset.wbSkin=v.skin;` +
+    `if(new RegExp('^(${fontIds})$').test(v.font))e.dataset.wbFont=v.font;` +
+    `}catch(_){}})();`
+  );
+})();
+
+/* ------------------------------------------------------------------ *
+ * 读写 / 应用
+ * ------------------------------------------------------------------ */
+
+function isSkinId(v: unknown): v is SkinId {
+  return typeof v === 'string' && Object.prototype.hasOwnProperty.call(SKINS, v);
+}
+
+function isFontId(v: unknown): v is FontId {
+  return typeof v === 'string' && FONT_SCALES.some((f) => f.id === v);
+}
+
+/** 容错解析：版本升级、手工改坏、存了别的值，一律回落到默认 */
+export function parseAppearance(raw: string | null | undefined): AppearanceSettings {
+  if (!raw) return DEFAULT_APPEARANCE;
+  try {
+    const v = JSON.parse(raw) as Partial<AppearanceSettings> | null;
+    return {
+      skin: isSkinId(v?.skin) ? v.skin : DEFAULT_APPEARANCE.skin,
+      font: isFontId(v?.font) ? v.font : DEFAULT_APPEARANCE.font,
+    };
+  } catch {
+    return DEFAULT_APPEARANCE;
+  }
+}
+
+/** 读本机设置；SSR 环境返回默认值 */
+export function readAppearance(): AppearanceSettings {
+  if (typeof window === 'undefined') return DEFAULT_APPEARANCE;
+  try {
+    return parseAppearance(window.localStorage.getItem(APPEARANCE_KEY));
+  } catch {
+    return DEFAULT_APPEARANCE;
+  }
+}
+
+export function saveAppearance(s: AppearanceSettings): void {
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.setItem(APPEARANCE_KEY, JSON.stringify(s));
+  } catch {
+    /* 隐私模式下写不进去：本次会话仍然生效，只是刷新后回到默认 */
+  }
+}
+
+/** 把设置写到 <html> 上；CSS 变量由 buildAppearanceCss 提供，这里只切开关 */
+export function applyAppearance(s: AppearanceSettings): void {
+  if (typeof document === 'undefined') return;
+  const el = document.documentElement;
+  el.dataset.wbSkin = s.skin;
+  el.dataset.wbFont = s.font;
+}
+
+/**
+ * 取某个 CSS 变量的当前真实值。
+ * 图表（ECharts / canvas）不认 var()，必须先把颜色解析成 hex。
+ * 只在浏览器里调用；SSR 返回 fallback。
+ */
+export function cssVar(name: string, fallback = ''): string {
+  if (typeof window === 'undefined') return fallback;
+  const v = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+  return v || fallback;
+}