> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/guide/theming.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# 定制主题

颜色、圆角和深色模式都通过 ConfigProvider 的 `theme` 设置。通常几行配置就够了，其他样式会自动跟随。

## 改颜色和圆角

在应用入口用 ConfigProvider 包住页面。下面把主题色改成紫色，基础圆角改成 8px：


保存更改

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/theming/basic.tsx"
import { Button, ConfigProvider } from '@ifhover/leaf-ui';

export function ThemeBasic() {
  return (
    <ConfigProvider theme={{ primaryColor: '#7654c6', borderRadius: 8 }}>
      <Button>保存更改</Button>
    </ConfigProvider>
  );
}
```

展开代码

把示例中的 Button 换成你的应用内容即可。按钮、输入框、选择器及浮层会一起使用这份主题；按钮按下和其他交互状态的颜色会自动生成，按钮悬停保持原样。

`primaryColor` 是基色输入，组件库会保留原色，并生成 `light-3`、`light-7`、`light-9`、`dark-1`、`dark-3`、`dark-7`、`dark-9` 七档语义色。浅色和深色使用同一组基色与语义色，只切换中性角色以及 `soft`、`border`、`ink` 等用途；中性色仍使用 `100`–`900` 色阶。

实色背景上的文字默认白色，需要黑字时设置 `theme.tokens.onPrimaryColor: '#000000'`。颜色通过 ConfigProvider 的 JS 配置更新，修改 DOM 样式不会触发 JS 色板重算。

`borderRadius` 是圆角的基准值。卡片、弹窗等会按各自的层级生成圆角，因此不必逐个组件设置。数字表示像素，也支持 `'0.5rem'` 等 CSS 长度。

### 常用参数

下面这些参数都放在 `theme` 中，只写需要修改的项。

| 参数              | 常见写法                  | 用途                                          |
| --------------- | --------------------- | ------------------------------------------- |
| `primaryColor`  | `'#7654c6'`           | 设置主题基色并生成七档语义色；原色不会被改写。                     |
| `borderRadius`  | `10`                  | 调整基础圆角，`0` 为直角。                             |
| `appearance`    | `'light'` / `'dark'`  | 设置浅色或深色外观。                                  |
| `controlHeight` | `40`                  | 调整单行控件的基础高度，小、大尺寸同步变化。                      |
| `fontSize`      | `14`                  | 设置组件基础字号。                                   |
| `lineHeight`    | `20`                  | 设置正文行高；数字默认为 px，`1`–`4` 保留旧倍率语义，也支持 CSS 长度。 |
| `fontFamily`    | `'Inter, sans-serif'` | 设置字体；字体文件由应用加载。                             |
| `motion`        | `false`               | 关闭当前区域的动效，保留正常操作。                           |

未设置的字段继承外层配置。默认使用浅色外观、8px 基础圆角、34px 基础控件高度、14px 字号和 20px 正文行高。

完整参数见 [LeafTheme](https://ifhover.github.io/leaf-ui/components/config-provider.md#leaftheme)。需要单独调整文字色、背景色或某个尺寸时，再查阅 [LeafThemeTokens](https://ifhover.github.io/leaf-ui/api/theme-tokens.md#leafthemetokens)。

## 复制主题示例

下面的示例包含默认、插画、Windows XP、Material 和拟物五种风格的完整定义。将源码复制到自己的项目，把生成的 `LeafTheme` 对象传给 `ConfigProvider` 即可使用；主题定义保留在示例源码中，可以直接修改。

| 风格             | 外观                         |
| -------------- | -------------------------- |
| `default`      | 组件库原始外观，不增加主题覆盖。           |
| `illustration` | 高对比描边、鲜明配色与偏移硬阴影。          |
| `windows-xp`   | 小圆角、Tahoma 字体、斜面高光与渐变卡片标题。 |
| `material`     | 参考 MUI 的简洁轮廓、4px 圆角与层次阴影。  |
| `skeuomorphic` | 柔和底面、双向浮雕阴影与按下时的内凹效果。      |


默认

插画

Windows XP

Material

拟物

**#1e964f

### 你的下一份灵感

创建项目稍后再说

presets.tsx

复制代码

```tsx lineNumbers file="../../src/examples/theming/presets.tsx"
import { Button, Card, ColorPicker, ConfigProvider, Flex, Input, type LeafTheme, Select, Space, Tabs } from '@ifhover/leaf-ui';
import { useState } from 'react';

export type ThemeStyle = 'default' | 'illustration' | 'windows-xp' | 'material' | 'skeuomorphic';

export function createExampleTheme(style: ThemeStyle, primaryColor?: string): LeafTheme {
  const base: LeafTheme = primaryColor ? { primaryColor } : {};
  if (style === 'default') return base;
  if (style === 'illustration') {
    return {
      ...base,
      borderRadius: 4,
      tokens: {
        borderWidth: 2,
        borderColor: 'color-mix(in srgb, var(--leaf-color-primary) 12%, var(--leaf-color-text))',
        mutedSurfaceColor:
          'color-mix(in srgb, var(--leaf-color-primary) 8%, var(--leaf-color-surface))',
        controlShadow: '3px 3px 0 var(--leaf-color-border)',
        surfaceShadow: '6px 6px 0 var(--leaf-color-border)',
      },
    };
  }
  if (style === 'windows-xp') {
    const bevel = 'inset 1px 1px 0 rgb(255 255 255 / 0.7), inset -1px -1px 0 rgb(0 0 0 / 0.18)';
    return {
      ...base,
      borderRadius: 3,
      fontFamily: 'Tahoma, "Microsoft YaHei", sans-serif',
      tokens: {
        borderColor:
          'color-mix(in srgb, var(--leaf-color-primary) 45%, var(--leaf-color-text-muted))',
        mutedSurfaceColor:
          'color-mix(in srgb, var(--leaf-color-primary) 6%, var(--leaf-color-surface))',
        controlShadow: `${bevel}, 0 1px 2px rgb(0 0 0 / 0.12)`,
        surfaceShadow: `${bevel}, 2px 3px 6px rgb(0 0 0 / 0.18)`,
      },
      components: {
        Card: {
          headerBackground:
            'linear-gradient(180deg, color-mix(in srgb, var(--leaf-color-primary) 28%, var(--leaf-color-surface)), color-mix(in srgb, var(--leaf-color-primary) 8%, var(--leaf-color-surface)) 48%, color-mix(in srgb, var(--leaf-color-primary) 14%, var(--leaf-color-surface)))',
        },
        Button: {
          active: { shadow: 'inset 1px 2px 3px rgb(0 0 0 / 0.25)' },
        },
      },
    };
  }
  if (style === 'material') {
    return {
      ...base,
      borderRadius: 4,
      fontFamily: 'Roboto, "Inter Variable", "Microsoft YaHei", sans-serif',
      tokens: {
        surfaceShadow: '0 3px 8px rgb(0 0 0 / 0.12), 0 1px 3px rgb(0 0 0 / 0.1)',
      },
      components: {
        Button: {
          shadow: '0 2px 3px rgb(0 0 0 / 0.16), 0 1px 2px rgb(0 0 0 / 0.1)',
          hover: { shadow: '0 4px 8px rgb(0 0 0 / 0.2)' },
          active: { shadow: '0 1px 2px rgb(0 0 0 / 0.18)' },
        },
      },
    };
  }
  const highlight = 'light-dark(rgb(255 255 255 / 0.95), rgb(255 255 255 / 0.06))';
  const shade = 'light-dark(rgb(0 0 0 / 0.16), rgb(0 0 0 / 0.5))';
  return {
    ...base,
    borderRadius: 14,
    tokens: {
      surfaceColor:
        'light-dark(color-mix(in srgb, var(--leaf-color-primary) 3%, #eef0f3), color-mix(in srgb, var(--leaf-color-primary) 3%, #26282d))',
      mutedSurfaceColor:
        'color-mix(in srgb, var(--leaf-color-primary) 5%, var(--leaf-color-surface))',
      borderColor: 'color-mix(in srgb, var(--leaf-color-text) 12%, var(--leaf-color-surface))',
      controlShadow: `3px 3px 7px ${shade}, -3px -3px 7px ${highlight}, inset 0 1px 0 ${highlight}`,
      surfaceShadow: `6px 6px 14px ${shade}, -6px -6px 14px ${highlight}`,
    },
    components: {
      Button: {
        active: { shadow: `inset 3px 3px 6px ${shade}, inset -3px -3px 6px ${highlight}` },
      },
    },
  };
}

export function ThemePresets() {
  const [preset, setPreset] = useState<ThemeStyle>('illustration');
  const [color, setColor] = useState('#1e964f');
  return (
    <ConfigProvider theme={createExampleTheme(preset, color)}>
      <Flex direction="column" gap="md">
        <Tabs
          type="card"
          aria-label="主题风格"
          activeKey={preset}
          onChange={(key) => setPreset(key as ThemeStyle)}
          items={[
            { key: 'default', label: '默认' },
            { key: 'illustration', label: '插画' },
            { key: 'windows-xp', label: 'Windows XP' },
            { key: 'material', label: 'Material' },
            { key: 'skeuomorphic', label: '拟物' },
          ]}
        />
        <ColorPicker
          aria-label="主题色"
          value={color}
          onChange={setColor}
          format="hex"
          disableAlpha
          showText
        />
        <Card title="你的下一份灵感">
          <Flex direction="column" gap="md">
            <Input aria-label="项目名称" placeholder="给项目起个名字" />
            <Select
              aria-label="项目类型"
              defaultValue="design"
              options={[
                { value: 'design', label: '设计' },
                { value: 'development', label: '开发' },
              ]}
            />
            <Space wrap>
              <Button>创建项目</Button>
              <Button variant="outline">稍后再说</Button>
            </Space>
          </Flex>
        </Card>
      </Flex>
    </ConfigProvider>
  );
}
```

展开代码

默认风格不增加任何 token；`density` 使用默认值时也无需设置。按下、焦点和主色上的文字颜色由组件库自动生成，不需要在配置中逐项写出；示例仅按风格调整必要的阴影反馈。

自定义风格只定义差异：圆角、描边宽度、全局 `tokens.borderColor`、阴影，以及用 `color-mix()` 生成的染色表面。设置一次全局边框色，实色按钮、开关、卡片、表格、浮层等组件的外框都会生效，无需为每个组件重复配置。组件级覆盖优先，错误、选中等状态继续保留各自语义；原本无边框的组件保持自身结构。

调用 `createExampleTheme('illustration', '#1d9bf0')` 设置主色。染色背景和描边使用 `var(--leaf-color-primary)`，阴影复用 `var(--leaf-color-border)`，因此会随主色自动变化，无需为每种颜色手写整套色板。省略颜色参数可继承所在区域的主题色；表面色继续由组件库按深浅外观生成，染色背景在此基础上混入主色。

Windows XP 和 Material 是使用 Leaf UI 主题能力制作的风格示例。Windows XP 保留当前主色，用斜面、字体和渐变表达复古质感；Material 使用本地可用的 Roboto 或回退字体。拟物的表面用 `light-dark()` 区分深浅模式，再通过 `color-mix()` 混入主色；固定的光照与中性基底不需要为每种主色重写。组件级配置仅用于卡片标题渐变和按钮阴影反馈，全局描边与阴影继续由一份 token 统一应用。

切换风格不会重挂载子组件，输入值与选择状态会保留。浮层及服务反馈继承调用区域的主题。展开示例源码即可查看完整主题定义，复制到项目的 `ConfigProvider` 中使用。页面插画、背景纹理与字体文件由应用自行提供。

## 使用深色模式

设置 `appearance: 'dark'` 即可；改回 `'light'` 恢复浅色：

```tsx
<ConfigProvider theme={{ appearance: 'dark' }}>
  <App />
</ConfigProvider>
```

组件的文字、背景和边框会一起切换。没有指定 `primaryColor` 时，浅色和深色使用同组默认语义基色。显式主色始终保留原值：黑色按钮在深色模式下仍使用黑底白字，并在需要时添加细微边界。两种外观共享五个语义色带与中性色阶，只改变中性角色和 `soft`、`border`、`ink` 等映射档位。

主色与状态文字使用映射后的可读 `ink`，实色背景保持原值。Input / Select 聚焦使用主题色边框，其他字段保留中性聚焦；显式文字色、焦点色与交互色配置优先。CSS 颜色表达式按表达式保留，不通过 DOM 解析回数值。

ConfigProvider 负责区域内组件的样式，不会给页面的 `body` 自动添加背景。业务页面的背景和文字也需要跟随外观时，可使用下文的 [CSS 变量](#在业务样式中使用主题)。

### 加一个切换开关

主题是普通 React 参数，可以用状态更新。打开下面的开关，查看卡片、按钮和文字一起切换：


深色模式保存更改

appearance.tsx

复制代码

```tsx lineNumbers file="../../src/examples/theming/appearance.tsx"
import { Button, Card, ConfigProvider, Flex, Switch } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function ThemeAppearance() {
  const [dark, setDark] = useState(false);

  return (
    <ConfigProvider theme={{ appearance: dark ? 'dark' : 'light' }}>
      <Card>
        <Flex direction="column" gap="md" align="start">
          <Switch checked={dark} onChange={(event) => setDark(event.target.checked)}>
            深色模式
          </Switch>
          <Button>保存更改</Button>
        </Flex>
      </Card>
    </ConfigProvider>
  );
}
```

展开代码

### 跟随系统外观

希望随操作系统切换时，使用 `useSystemAppearance`，并把结果传给 `theme.appearance`：

```tsx
import { ConfigProvider, useSystemAppearance } from '@ifhover/leaf-ui';

export function AppTheme() {
  const appearance = useSystemAppearance('light');

  return (
    <ConfigProvider theme={{ appearance }}>
      <App />
    </ConfigProvider>
  );
}
```

这里的 `'light'` 是首次渲染使用的外观，挂载后会读取并监听系统偏好。用户手动选择外观时，由应用保存选择并决定是否继续跟随系统。

## 只调整一个区域

嵌套一个 ConfigProvider，就能为某块内容设置独立主题。内层只覆盖写出的字段，其他配置继续继承：


全局蓝色

局部紫色

scoped.tsx

复制代码

```tsx lineNumbers file="../../src/examples/theming/scoped.tsx"
import { Button, ConfigProvider, Flex } from '@ifhover/leaf-ui';

export function ThemeScoped() {
  return (
    <ConfigProvider theme={{ primaryColor: '#1677ff', borderRadius: 8 }}>
      <Flex direction="column" gap="md" align="start">
        <Button>全局蓝色</Button>
        <ConfigProvider theme={{ primaryColor: '#7654c6' }}>
          <Button>局部紫色</Button>
        </ConfigProvider>
      </Flex>
    </ConfigProvider>
  );
}
```

展开代码

示例中两个按钮的基础圆角都是 8px，内层只把主题色改成紫色。从该区域打开的 Select 浮层、Modal，以及通过 `useConfirm`、`useMessage` 创建的反馈也会使用所在区域的主题。

## 调整控件尺寸和密度

只调整一个控件时，优先使用它的 `size="sm"` 或 `size="lg"`。要让整个区域的控件更紧凑，可以设置 ConfigProvider 的 `density`：

```tsx
<ConfigProvider density="compact">
  <App />
</ConfigProvider>
```

`density` 与 `theme` 同级。默认值为 `'comfortable'`；`'compact'` 会同时收紧控件、表单和浮层的间距，基础控件高度从 34px 调整为 30px，字号保持不变。

需要指定高度时再设置 `theme.controlHeight`，它优先于密度预设。例如 `controlHeight: 40` 会生成 34px / 40px / 46px 三种控件高度。尺寸对比见 [ConfigProvider](https://ifhover.github.io/leaf-ui/components/config-provider.md#%E5%9F%BA%E7%A1%80%E9%AB%98%E5%BA%A6)。

## 进阶定制

下面的配置适合已有明确设计要求的项目。只改颜色、圆角或外观时，使用前面的基础参数即可。

### 单独覆盖颜色或尺寸

`theme.tokens` 用于修改基础参数之外的具体样式。例如只调整成功色、大圆角和动效时长：

```tsx
import type { LeafTheme } from '@ifhover/leaf-ui';

const theme = {
  primaryColor: '#7654c6',
  borderRadius: 8,
  tokens: {
    successColor: '#1e964f',
    borderRadiusLg: 18,
    motionDuration: 160,
  },
} satisfies LeafTheme;
```

将这个对象传给 `<ConfigProvider theme={theme}>`。这里的 `borderRadiusLg` 会覆盖自动生成的大圆角；`motionDuration` 的数字单位是毫秒。完整字段和说明见 [LeafThemeTokens](https://ifhover.github.io/leaf-ui/api/theme-tokens.md#leafthemetokens)。

如果使用很浅的主题色，可通过 `tokens.onPrimaryColor` 设置实色按钮上的文字色。自定义配色后，应检查正常、按下和禁用状态的可读性。`motion: false` 可以关闭区域动效，系统的“减少动态效果”偏好始终优先。

### 只调整某类组件的样式

`theme.components` 按组件名称设置样式。例如让按钮使用 4px 圆角，同时调整卡片内边距：

```tsx
<ConfigProvider
  theme={{
    components: {
      Button: { borderRadius: 4 },
      Card: { padding: 24 },
    },
  }}
>
  <App />
</ConfigProvider>
```

可用样式字段见 [LeafComponentTokens](https://ifhover.github.io/leaf-ui/api/theme-tokens.md#leafcomponenttokens)，具体组件支持的字段以其文档为准。

这里的 `theme.components` 调整样式。如果想统一按钮的 `size`、`variant` 或其他组件参数，使用 ConfigProvider 上的 `components`，见 [组件默认值](https://ifhover.github.io/leaf-ui/components/config-provider.md#%E7%BB%84%E4%BB%B6%E9%BB%98%E8%AE%A4%E5%80%BC)。

### 描边、阴影与交互状态

`tokens.borderWidth` 设置控件与内容表面的外框宽度；`controlShadow` 和 `surfaceShadow` 分别设置控件、内容表面的阴影。分区分隔线保持各自的细线样式。组件的 `borderWidth` 和 `shadow` 优先于全局值。

支持状态覆盖的组件还可用 `hover`、`active`、`focus`、`disabled` 调整颜色、背景、边框颜色和阴影：

```tsx
<ConfigProvider
  theme={{
    tokens: { borderWidth: 2, controlShadow: '3px 3px 0 #252525' },
    components: {
      Button: {
        borderColor: '#252525',
        hover: { shadow: '4px 4px 0 #252525' },
        active: { shadow: '1px 1px 0 #252525' },
        disabled: { shadow: 'none' },
      },
      Input: { focus: { borderColor: '#7654c6', shadow: '0 0 0 3px #7654c630' } },
    },
  }}
>
  <App />
</ConfigProvider>
```

状态配置只修改外观，不改变组件的事件、尺寸、禁用或只读行为，也不移除键盘焦点提示。嵌套区域按状态内的字段合并，`undefined` 继续继承。完整字段与支持范围见 [主题变量](https://ifhover.github.io/leaf-ui/api/theme-tokens.md#leafcomponenttokens)。

### 在业务样式中使用主题

ConfigProvider 会在它包裹的区域提供 `--leaf-*` CSS 变量。业务内容位于该区域内时，可以读取当前主题，随颜色和外观一起更新：

```tsx
<ConfigProvider theme={{ appearance: 'dark' }}>
  <section className="app-panel">业务内容</section>
</ConfigProvider>
```

```css
.app-panel {
  padding: 16px;
  color: var(--leaf-color-text);
  background: var(--leaf-color-surface);
  border: 1px solid var(--leaf-color-border);
  border-radius: var(--leaf-radius);
}
```

| 常用变量                                                                              | 用途                                                                     |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `--leaf-color-primary`                                                            | 当前主题色。                                                                 |
| `--leaf-color-<family>-{light-3,light-7,light-9,dark-1,dark-3,dark-7,dark-9}`     | 五个语义 family 的七档共享色；`<family>` 为 primary、success、danger、warning 或 info。 |
| `--leaf-color-neutral-{100..900}`                                                 | 中性色九档色阶，浅色与深色使用同一组值。                                                   |
| `--leaf-color-<family>-soft` / `-soft-hover` / `-soft-active`                     | 各语义的柔和背景及反馈底色。                                                         |
| `--leaf-color-<family>-border`                                                    | 各语义由色阶映射的边界色。                                                          |
| `--leaf-color-<family>-ink`                                                       | 各语义在普通表面上的可读文字色。                                                       |
| `--leaf-color-primary-indicator`                                                  | 选中、进度和轮廓的主色指示。                                                         |
| `--leaf-color-primary-focus`                                                      | 主色焦点提示；Input / Select 默认使用，其他字段与按钮保留各自的焦点样式。                           |
| `--leaf-color-primary-fill-border`                                                | 日期选中等主色区域的辅助边界；实底按钮不使用此角色。                                             |
| `--leaf-color-on-primary` / `on-success` / `on-danger` / `on-warning` / `on-info` | 各实色背景上的内容色。                                                            |
| `--leaf-color-text` / `--leaf-color-text-muted`                                   | 主要、次要文字色。                                                              |
| `--leaf-color-surface` / `--leaf-color-surface-muted`                             | 内容背景、辅助背景。                                                             |
| `--leaf-color-border`                                                             | 边框颜色。                                                                  |
| `--leaf-color-option-hover`                                                       | 普通选项、菜单和候选行的中性反馈底色。                                                    |
| `--leaf-border-width`                                                             | 外框宽度。                                                                  |
| `--leaf-control-shadow` / `--leaf-surface-shadow`                                 | 控件与内容表面阴影。                                                             |
| `--leaf-radius`                                                                   | 基础圆角。                                                                  |

`--leaf-color-primary-soft` 及同类 `*-soft` 角色始终由语义色映射生成；`primarySoftColor` 等配置只用于显式覆盖。`ink` 优先使用达到 4.5:1 的原色，否则选择可读的派生色；主色指示优先使用达到 3:1 的原色，否则选择可读的派生色。业务代码优先使用用途角色，不直接拼装色阶。

调整 Leaf UI 组件的主题仍通过 ConfigProvider，业务 CSS 用这些变量读取结果。仅修改某个基础 CSS 变量，不会重新生成整套交互颜色。

使用 Tailwind CSS 时，可直接引入包提供的配置，通过 `bg-leaf-surface`、`text-leaf-primary` 等工具类复用主题。Tailwind 3 / 4 的接入方式见 [Tailwind CSS](https://ifhover.github.io/leaf-ui/guide/tailwindcss.md)。

## 服务端渲染

服务端和客户端首次渲染应使用相同的外观。需要记住用户选择时，可由服务端读取 Cookie 并传入初始值；使用系统外观时，挂载后再更新。

主题色推荐使用具体的 HEX、RGB 或 HSL。实底字色默认白色，请自行检查前景对比度。表达式保持为 CSS 表达式，不在挂载后解析为数值，也不监听 DOM 变化。

安装见 [安装&快速开始](https://ifhover.github.io/leaf-ui/guide/getting-started.md)，Next.js 等框架的接入见 [服务端渲染](https://ifhover.github.io/leaf-ui/guide/ssr.md)，支持范围见 [浏览器兼容性](https://ifhover.github.io/leaf-ui/guide/compatibility.md)。
