Tailwind、CSS 变量与 CSS-in-JS 中的令牌

Style Dictionary 的 CSS 平台输出会生成一个包含 CSS 自定义属性的文件：--color-primary-500: #3b82f6; --spacing-4: 16px;，等等。这些变量定义在 :root 上，因此可在全局使用。这是应用中使用所有令牌的基础。

将生成的 CSS 令牌文件导入全局样式表或根布局组件：@import './tokens/tokens.css'。在 Next.js 中，将其导入 app/layout.tsx 或 styles/globals.css。导入后，应用中的每条 CSS 规则和每个组件都可以引用这些自定义属性。

在组件样式表或 CSS 模块中引用 CSS 变量：background-color: var(--color-primary-500); 和 padding: var(--spacing-4);。如果 JSON 源文件中的令牌值发生变化，重新构建 Style Dictionary 会更新 CSS 文件，所有使用该变量的组件都会自动反映新值。

CSS 自定义属性支持运行时切换主题。对于深色模式，在主题选择器下覆盖令牌值：[data-theme="dark"] { --color-background: #1a1a2a; --color-text: #f0f0f0; }。设置 document.documentElement.setAttribute('data-theme', 'dark') 后，无需重新加载或重新构建，即可立即切换所有令牌值。

在 tailwind.config.js 中扩展 Tailwind 的主题，以使用令牌值：theme: { extend: { colors: { primary: { 500: tokenOutput.color.primary[500] } } } }。将 Style Dictionary 生成的 JS 输出导入 Tailwind 配置，确保 Tailwind 类（bg-primary-500）始终使用权威令牌值。

若要在 Tailwind 中实现可在运行时切换的主题，请将颜色配置为引用 CSS 变量：'primary': 'rgb(var(--color-primary-rgb) / <alpha-value>)'。这要求 CSS 变量存储不带 rgb() 包装器的 RGB 分量（--color-primary-rgb: 59 130 246）。随后 Tailwind 会自动处理不透明度工具类。

CSS-in-JS 库使用 JavaScript 主题对象。将 Style Dictionary 的 JS 输出作为主题提供者的值传入：<ThemeProvider theme={tokens}>。组件通过 const theme = useTheme() 和 theme.color.primary[500] 访问令牌。Style Dictionary 会生成带类型的令牌对象；主题提供者负责分发它。

stylelint-no-hardcoded-colors 插件和自定义 ESLint 规则可以强制要求样式表或组件文件中不得出现硬编码的十六进制值。如果开发者写下 color: #3b82f6 而不是 color: var(--color-primary-500)，代码检查器就会标记它。这样可确保令牌系统是唯一的颜色来源。

当 Tailwind 类名在运行时根据令牌名称动态构造时，Tailwind 的清除过程可能会移除这些类，因为它们不会以静态字符串形式出现在源代码中。将动态类模式添加到 tailwind.config.js 中的 safelist：safelist: [{ pattern: /bg-primary-/ }]。

Figma Tokens 插件可将 Figma 令牌值直接导出为 Style Dictionary JSON 格式。工作流程如下：设计师在 Figma Variables 中更新颜色，通过插件导出，提交更新后的 JSON，预构建脚本运行 Style Dictionary，React 应用使用更新后的 CSS 和 JS 输出。设计与代码保持同步。

CSS 自定义属性仅在其定义所在的元素及其后代元素中有效。这可以实现组件级主题覆盖：卡片组件可以在其根元素上设置 --color-background: var(--color-surface-elevated)，所有后代元素都会使用提升后的表面颜色，而无需逐层传递属性。

与静态 Tailwind 值相比，使用 CSS 自定义属性（变量）作为设计令牌的主要优势是什么？

Style Dictionary 将 CSS 自定义属性输出为供全局导入的内容，并将 JS 对象输出用于 Tailwind 和 CSS-in-JS 集成。CSS 变量可通过 [data-theme] 覆盖实现运行时主题切换。Tailwind 从 JS 输出中的令牌值扩展其配置；若要实现支持不透明度的主题，请将 Tailwind 配置为引用 RGB CSS 变量。代码检查规则强制仅使用令牌的颜色，避免硬编码值进入代码库。