主题

@theme 为工具类定义注册令牌。其修饰符分别控制交付哪些令牌声明，以及生成值使用 var() 还是代入原始声明值。主题令牌说明项目设置；变量与模式说明作用域、继承与解析。

@theme

以自定义属性声明工具类令牌。主题块必须位于顶层，且仅接受自定义属性令牌声明。关键帧请在块外的原生 CSS 中声明。

@theme {  --color-brand: #4f46e5;  --spacing-card: 1.5rem;}

未知或重复的修饰符会产生错误。static 与 inline 的顺序不限。

令牌输出于 @layer theme 中的 :root, :host。编译器保留声明顺序与重复值。已使用令牌保留传递变量依赖。选择器和条件规则应放在块外的原生 CSS 中。

只有 @theme 为工具类模式注册命名令牌。:root { --app-brand: red; } 这类原生声明仍为常规 CSS；可直接用 (color:var(--app-brand)) 使用，或通过 inline 主题令牌桥接。

每种情况均声明 brand 与 spare，但仅使用 bg-brand。只有 inline 时，两个令牌均不需要声明。加入 static 保留两者，但不改变代入后的类值。

文字说明

1. 四种情况均声明 --color-brand: #4f46e5 和 --color-spare: #0d9488。bg-brand 是唯一引用方，没有原生令牌引用。
2. 常规 @theme 输出已使用的 brand 令牌和 background-color: var(--color-brand)，省略未使用的 spare 令牌。
3. @theme inline 将 #4f46e5 代入生成声明。工具类不再读取任何一个令牌，因此该情况不输出两条令牌声明。
4. @theme static 保留两个令牌。@theme static inline 也保留两者，但生成的 background-color 仍为 #4f46e5。保留与代入相互独立。

@theme inline

使用 inline，将令牌的声明值代入 Master 生成的声明：

@theme inline {  --color-brand: var(--app-brand);}:root {  --app-brand: #4f46e5;}[data-theme="ocean"] {  --app-brand: #0369a1;}

bg-brand 输出 background-color:var(--app-brand)，在使用该类的元素上解析原生变量。直接声明类、工具类及原生 @apply 展开均采用相同代入方式。手写原生声明保留原有 var() 引用。

代入仅执行一次。替换值中的变量、函数和回退值保留原生 CSS 语义。依赖从代入后的声明收集；仅使用 inline 工具类不会强制输出被替换的令牌。直接以原生方式引用该令牌仍可保留其声明。

重复主题定义先按重要性、再按源顺序选择 inline 值与模式。自定义属性的 !important 不会使生成工具类也变为重要。常规别名在声明作用域内解析；桥接值需要在使用处读取其他变量时，请用 inline。

@theme static

即使没有类或原生引用也必须输出令牌时，请用 static：

@theme static {  --color-integration: #4f46e5;}@theme static inline {  --color-brand: var(--app-brand);}

static 控制令牌交付，inline 控制生成值，两者可按任意顺序组合。只要令牌具有任一 static 声明，就与其依赖一起保留，直至定义移除。被引用样式表不会仅因令牌为 static 就成为输出根节点。

原生主题覆盖

在 @theme 注册默认值，再用原生选择器或查询覆盖变量：

@theme {  --color-panel: white;}[data-theme="ocean"] {  --color-panel: #082f49;}@media (prefers-color-scheme: dark) {  :root {    --color-panel: #111827;  }}

原生覆盖保留原有作用域、层与样式表交付方式。同一元素上，无层的普通覆盖优先于 theme 层的普通声明。defaults 这类较后的层也能使覆盖优先，同时允许 components 与 utilities 层取得更高优先级。需要覆盖的地方都要导入原生样式表；@reference 仅提供定义，不交付这些规则。

预设使用原生 light-dark() 提供自适应颜色与阴影。两个变量分支均保留为依赖。其原生基础 CSS 在根元素设置 color-scheme: light dark，并提供适用于元素和 shadow host 的明暗 data-theme 选择器。请见颜色。

@theme { --color-brand: #4f46e5; }  .dark { --color-brand: #111827; } .card { color: var(--color-brand); }

.dark {  --color-brand: #111827;}.card {  color: var(--color-brand);}@layer theme {  :root,  :host {    --color-brand: #4f46e5  }}