> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06
> Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/api/theme-tokens.html

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

# 主题变量

日常定制优先设置 ConfigProvider 的 `theme.primaryColor`、`theme.borderRadius` 和 `theme.controlHeight`，其他样式会自动派生，见[定制主题](https://ifhover.github.io/leaf-ui/v/0.6.0/guide/theming.md)。

## LeafThemeTokens

需要单独调整某个派生值时，再通过 `theme.tokens` 覆盖。所有字段均可选，嵌套区域继承未设置的字段。长度为数字时按 px 处理，动效时长为数字时按 ms 处理。

| 属性                       | 类型                 | 默认值                                   | 说明                                          |
| ------------------------ | ------------------ | ------------------------------------- | ------------------------------------------- |
| `onPrimaryColor`         | `string`           | 按主题生成                                 | 主题背景上的文字色                                   |
| `dangerColor`            | `string`           | 按外观生成                                 | 危险色 / 危险背景上的文字色                             |
| `onDangerColor`          | `string`           | 按外观生成                                 | 危险色 / 危险背景上的文字色                             |
| `successColor`           | `string`           | 按外观生成                                 | 成功 / 警告 / 信息颜色                              |
| `warningColor`           | `string`           | 按外观生成                                 | 成功 / 警告 / 信息颜色                              |
| `infoColor`              | `string`           | 按外观生成                                 | 成功 / 警告 / 信息颜色                              |
| `textColor`              | `string`           | 按外观生成                                 | 主要 / 次要文字                                   |
| `mutedTextColor`         | `string`           | 按外观生成                                 | 主要 / 次要文字                                   |
| `subtleTextColor`        | `string`           | —                                     | 更轻的辅助文字色。                                   |
| `surfaceColor`           | `string`           | 按外观生成                                 | 表面 / 次级表面                                   |
| `mutedSurfaceColor`      | `string`           | 按外观生成                                 | 表面 / 次级表面                                   |
| `raisedSurfaceColor`     | `string`           | —                                     | 浮层与抬升表面色。                                   |
| `borderColor`            | `string`           | 按外观生成                                 | 中性边框                                        |
| `borderHoverColor`       | `string`           | —                                     | 悬停时的中性边框色。                                  |
| `dividerColor`           | `string`           | —                                     | 分区分隔线颜色；默认从边框和表面颜色派生。                       |
| `borderRadiusSm`         | `number \| string` | `基础圆角 × 0.6`                          | 单独覆盖小 / 大圆角                                 |
| `borderRadiusMd`         | `number \| string` | `基础圆角 × 1.2`                          | 单独覆盖卡片、提示等内容表面的中圆角                          |
| `borderRadiusLg`         | `number \| string` | 基础圆角 × 1.6                            | 单独覆盖大圆角                                     |
| `controlHeightSm`        | `number \| string` | 基础高度 − 6px，最小 1px                     | 单独覆盖小尺寸控件高度                                 |
| `controlHeightLg`        | `number \| string` | 基础高度 + 6px                            | 单独覆盖大尺寸控件高度                                 |
| `fontSizeSm`             | `number \| string` | `基础字号 − 1px`                          | 单独覆盖小 / 大字号                                 |
| `fontSizeLg`             | `number \| string` | 基础字号 + 2px                            | 单独覆盖大字号                                     |
| `fontWeight`             | `number`           | `500`                                 | 按钮、标签与组件标题的强调字重                             |
| `motionDuration`         | `number \| string` | `200`                                 | 基础过渡时间；数字为 ms，也支持 CSS 时间。motion=false 时为 0。 |
| `motionEasing`           | `string`           | `'cubic-bezier(0.22, 1, 0.36, 1)'`    | 悬停、内容与普通过渡的曲线。                              |
| `motionSpring`           | `string`           | `'cubic-bezier(0.22, 1.28, 0.36, 1)'` | 选择与形状变化的轻微弹性曲线。                             |
| `popupZIndex`            | `number`           | `1000`                                | 浮层 / 弹窗 / 消息层级                              |
| `modalZIndex`            | `number`           | `1100`                                | 浮层 / 弹窗 / 消息层级                              |
| `messageZIndex`          | `number`           | `1200`                                | 浮层 / 弹窗 / 消息层级                              |
| `buttonBorderRadius`     | `number \| string` | 当前控件尺寸                                | 仅按钮的圆角 / 共用高度覆盖                             |
| `buttonHeight`           | `number \| string` | 当前控件尺寸                                | 仅按钮的圆角 / 共用高度覆盖                             |
| `choiceBorderRadius`     | `number \| string` | 基础圆角 × 0.5                            | 复选框圆角                                       |
| `focusColor`             | `string`           | 当前语义色自动生成                             | 焦点轮廓颜色                                      |
| `primaryHoverColor`      | `string`           | 主题色自动生成                               | 主色悬停 / 按下                                   |
| `primaryActiveColor`     | `string`           | 主题色自动生成                               | 主色悬停 / 按下                                   |
| `primarySoftColor`       | `string`           | 主题色自动生成                               | 主色柔和背景与交互状态                                 |
| `primarySoftHoverColor`  | `string`           | 主题色自动生成                               | 主色柔和背景与交互状态                                 |
| `primarySoftActiveColor` | `string`           | 主题色自动生成                               | 主色柔和背景与交互状态                                 |
| `primaryBorderColor`     | `string`           | 主题色自动生成                               | 主题色边框                                       |
| `dangerHoverColor`       | `string`           | 危险色自动生成                               | 危险状态悬停 / 按下                                 |
| `dangerActiveColor`      | `string`           | 危险色自动生成                               | 危险状态悬停 / 按下                                 |
| `spacingSm`              | `number \| string` | —                                     | 设置 spacingSm。                               |
| `spacingLg`              | `number \| string` | —                                     | 设置 spacingLg。                               |
| `shadowSm`               | `string`           | —                                     | 设置 shadowSm。                                |
| `shadowXs`               | `string`           | —                                     | 最轻的表面阴影。                                    |
| `shadowMd`               | `string`           | —                                     | 设置 shadowMd。                                |
| `shadowLg`               | `string`           | —                                     | 设置 shadowLg。                                |
| `lineHeight`             | `number`           | —                                     | 正文行高。                                       |

## 类型导入

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

const tokens = {
  controlHeightSm: 28,
  borderRadiusLg: 14,
} satisfies LeafThemeTokens;
```

将该对象传给 `<ConfigProvider theme={{ tokens }}>`。

## LeafComponentTokens

供 `theme.components` 按组件名称覆盖样式。各组件支持的字段以组件文档为准。

| 属性                 | 类型                 | 说明                 |
| ------------------ | ------------------ | ------------------ |
| `borderRadius`     | `string \| number` | 圆角；数字表示像素。         |
| `controlHeight`    | `string \| number` | 控件高度；数字表示像素。       |
| `padding`          | `string \| number` | 内容内边距。             |
| `gap`              | `string \| number` | 子项之间的间距。           |
| `fontSize`         | `string \| number` | 字号；数字表示像素。         |
| `color`            | `string`           | 颜色或语义色。            |
| `background`       | `string`           | 组件表面背景。            |
| `borderColor`      | `string`           | 外层边框与分区分隔线颜色。      |
| `headerBackground` | `string`           | 标题区域背景。            |
| `footerBackground` | `string`           | 底部操作区域背景。          |
| `shadow`           | `string`           | CSS box-shadow 的值。 |

## LeafThemeStyle

带 `--leaf-*` 自定义属性的 React 样式类型。业务 CSS 读取变量的示例见 [定制主题](https://ifhover.github.io/leaf-ui/v/0.6.0/guide/theming.md#%E5%9C%A8%E4%B8%9A%E5%8A%A1%E6%A0%B7%E5%BC%8F%E4%B8%AD%E4%BD%BF%E7%94%A8%E4%B8%BB%E9%A2%98)。

| 属性                            | 类型                              | 说明              |
| ----------------------------- | ------------------------------- | --------------- |
| ``[key: `--leaf-${string}`]`` | `string \| number \| undefined` | 可复用的 CSS 自定义属性。 |