定制主题

SD Design 现在以 ConfigProvider 的 theme 对象作为主题入口。你不需要再把主题能力绑定到 Less modifyVars，而是直接在运行时传入 tokens、components 和 meta 三个层级。

组件级 ThemeProvider

现在支持真正的组件级主题切换。你可以直接使用 ThemeProvider 包裹某个局部区域，让 sd-theme 和对应的 CSS variables 只在这个子树内生效。

<template>
  <sd-theme-provider theme-mode="dark">
    <sd-card title="Scoped Theme">
      <sd-button type="primary">Primary Action</sd-button>
      <sd-alert type="success">这里的语义 token 不会再回退到 body。</sd-alert>
    </sd-card>
  </sd-theme-provider>
</template>

如果你已经在用 ConfigProvider，也可以直接通过 theme 和 theme-mode 这两个配置项得到同样的局部主题容器能力。

注意：局部容器不会覆盖挂载到 body 的浮层节点（例如 Popover、Tooltip、Select 下拉）。这类场景需要全局主题能力（global）。

主题对象结构

interface SDThemeConfig {
  tokens?: Record<string, string | number>;
  components?: Record<string, Record<string, string | number>>;
  meta?: {
    name?: string;
    schemaVersion?: number;
    cssVarPrefix?: string;
  };
}

推荐的约定：

tokens 存放全局颜色、圆角、语义中性色等可跨组件复用的变量
components 存放组件级覆盖，用于表达某个组件相对全局 token 的偏移
meta 用来标记 schemaVersion、导出名称和 CSS 变量前缀

基本用法

<template>
  <sd-config-provider :theme="theme">
    <sd-space direction="vertical" fill>
      <sd-button type="primary">主题按钮</sd-button>
      <sd-input placeholder="查看输入框状态" />
      <sd-card title="运行时主题">不需要重新编译样式。</sd-card>
    </sd-space>
  </sd-config-provider>
</template>

<script setup lang="ts">
  const theme = {
    meta: {
      schemaVersion: 1,
      cssVarPrefix: '--',
      name: 'Brand Campaign',
    },
    tokens: {
      primary5: '255,98,150',
      primary6: '230,57,122',
      primary7: '184,28,90',
      colorBg2: '#fff8fb',
      colorNeutral10: '#2d1020',
      borderRadiusMedium: '14px',
    },
  };
</script>

CSS variables 约定

Scss 迁移后的组件样式优先消费 CSS variables。当前已经稳定使用的变量主要集中在三类：

颜色变量：如 primary1 到 primary7、colorNeutral2 到 colorNeutral10、colorBg2、colorBg5
语义浅色层：如 colorPrimaryLight1 到 colorPrimaryLight4、danger 和 success 的 light 层
圆角变量：如 borderRadiusSmall、borderRadiusMedium、borderRadiusLarge

你传入的 token key 会先被归一化，再注入成 CSS 变量。例如：

primary6 会变成 —primary-6
colorNeutral10 会变成 —color-neutral-10
borderRadiusMedium 会变成 —border-radius-medium

主题编辑器

如果想查看主题结构和 JSON 约定，参考主题编辑器说明。

迁移建议

新项目直接使用 theme 对象，不再新增 Less modifyVars 覆盖
已有 Less 主题先抽取出主品牌色、中性色和圆角，映射到 tokens
需要迁移步骤和风险说明时，查看样式迁移手册