设计系统模式

面向可扩展设计系统的底层架构：令牌层级结构、主题化基础设施、令牌流水线及治理模式。

适用场景

• 定义令牌架构（基础层 → 语义层 → 组件层）
• 在 React 中实现浅色/深色/系统级主题切换
• 搭建 Style Dictionary 或 Figma-to-code 令牌流水线
• 构建多品牌主题系统
• 确立令牌命名规范与治理流程
• 防止服务端渲染（SSR）中的未样式化内容闪现（FOUC）

模式 1：令牌层级结构

三层式令牌架构将原始值、语义含义与具体使用场景相互分离。

/* 第一层：基础令牌 — 原始值，绝不在组件中直接使用 */
:root {
  --color-blue-500: #3b82f6;
  --color-blue-600: #2563eb;
  --color-gray-50: #fafafa;
  --color-gray-900: #171717;

  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-4: 1rem;

  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
}

/* 第二层：语义令牌 — 具备上下文含义，支持主题感知 */
:root {
  --text-primary: var(--color-gray-900);
  --text-secondary: var(--color-gray-600);
  --surface-default: white;
  --surface-elevated: var(--color-gray-50);
  --border-default: var(--color-gray-200);
  --interactive-primary: var(--color-blue-500);
  --interactive-primary-hover: var(--color-blue-600);
}

/* 第三层：组件令牌 — 面向特定组件的使用，可选层 */
:root {
  --button-bg: var(--interactive-primary);
  --button-bg-hover: var(--interactive-primary-hover);
  --button-text: white;
  --button-radius: var(--radius-md);
  --button-padding-x: var(--space-4);
  --button-padding-y: var(--space-2);
}

语义令牌是最关键的一层——它使主题化成为可能。组件令牌为可选层，在复杂组件库中尤为有用。

模式 2：基于 React 的主题切换

核心能力：theme（用户选择）、resolvedTheme（实际生效的浅色/深色）、setTheme、系统偏好检测、localStorage 持久化、DOM 属性注入。

type Theme = "light" | "dark" | "system";

export function ThemeProvider({ children, defaultTheme = "system", storageKey = "theme",
  attribute = "data-theme" }: { children: React.ReactNode; defaultTheme?: Theme;
  storageKey?: string; attribute?: "class" | "data-theme" }) {
  const [theme, setThemeState] = useState(() =>
    typeof window === "undefined" ? defaultTheme
      : (localStorage.getItem(storageKey) as Theme) || defaultTheme);
  const [resolvedTheme, setResolvedTheme] = useState<"light" | "dark">("light");

  const getSystem = useCallback(() =>
    matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light" as const, []);

  const apply = useCallback((r: "light" | "dark") => {
    const root = document.documentElement;
    attribute === "class"
      ? (root.classList.remove("light", "dark"), root.classList.add(r))
      : root.setAttribute(attribute, r);
    root.style.colorScheme = r;
    setResolvedTheme(r);
  }, [attribute]);

  useEffect(() => { apply(theme === "system" ? getSystem() : theme); }, [theme, apply, getSystem]);

  useEffect(() => {  // 监听系统偏好变更
    if (theme !== "system") return;
    const mq = matchMedia("(prefers-color-scheme: dark)");
    const handler = () => apply(getSystem());
    mq.addEventListener("change", handler);
    return () => mq.removeEventListener("change", handler);
  }, [theme, apply, getSystem]);

  const setTheme = useCallback((t: Theme) => {
    localStorage.setItem(storageKey, t); setThemeState(t);
  }, [storageKey]);

  return 
    {children}
  ;
}

完整实现（含 toggleTheme、disableTransitionOnChange 及测试模式）详见 references/theming-architecture.md。

防止 SSR 中的 FOUC（Next.js）

置于 中的内联脚本会在首次绘制前执行：

const themeScript = `(function(){
  var t=localStorage.getItem('theme')||'system';
  var d=t==='dark'||(t==='system'&&matchMedia('(prefers-color-scheme:dark)').matches);
  document.documentElement.setAttribute('data-theme',d?'dark':'light');
  document.documentElement.style.colorScheme=d?'dark':'light';
})()`;

// 在 layout.tsx 中