> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/api/theme-tokens.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.primaryColor`、`theme.borderRadius` 和 `theme.controlHeight`，其他样式会自动派生，见[定制主题](https://ifhover.github.io/leaf-ui/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`           | —                                     | 分区分隔线颜色；默认从边框和表面颜色派生。                       |
| `borderWidth`            | `number \| string` | —                                     | 控件、内容表面和浮层的边框宽度；数字为 px。                     |
| `controlShadow`          | `string`           | —                                     | 可交互控件的默认阴影。                                 |
| `surfaceShadow`          | `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` 按组件名称覆盖样式。各组件支持的字段以组件文档为准。

交互状态使用 `hover`、`active`、`focus`、`disabled`，字段类型见 [LeafComponentStateTokens](#leafcomponentstatetokens)。组件参数的默认值仍通过 ConfigProvider 的 `components` 设置。

| 覆盖范围    | 配置键与作用区域                                                                                                                                    |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| 四种交互状态  | `Button`、`Input`、`InputNumber`、`Textarea`、`Select`、`AutoComplete`、`Cascader`、`TreeSelect`、`ColorPicker`、`DatePicker`。                       |
| 选择控件    | `Checkbox`、`Radio` 设置原生选择控件的外观与标签文字色；`Switch` 设置轨道与标签文字色；`Tabs` 设置标签按钮。                                                                     |
| 内容和反馈表面 | Card、Alert、Table、Modal、Drawer、Confirm、Message 等支持基础描边与阴影，不消费四种交互状态。                                                                         |
| 浮层      | `Floating` 设置共享浮层；Select、AutoComplete、Cascader、TreeSelect、ColorPicker、DatePicker、TimePicker、Dropdown、Mentions、Popover 可覆盖所属浮层的背景、文字色、边框与阴影。 |

日期、时间、范围选择器复用 `DatePicker` 的输入外壳状态；例如 TimePicker 的输入聚焦样式通过 `DatePicker.focus` 配置，所属面板的外观通过 `TimePicker` 配置。`InputOTP` 不支持完整的四种状态覆盖。状态用于表中指定的控件区域，不会递归修改组件内部的所有子节点。

| 属性                 | 类型                                                      | 说明                 |
| ------------------ | ------------------------------------------------------- | ------------------ |
| `borderRadius`     | `string \| number`                                      | 圆角；数字表示像素。         |
| `borderWidth`      | `string \| number`                                      | 此组件的边框宽度；数字为 px。   |
| `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 的值。 |
| `hover`            | [`LeafComponentStateTokens`](#leafcomponentstatetokens) | 悬停状态覆盖；嵌套区域逐字段合并。  |
| `active`           | [`LeafComponentStateTokens`](#leafcomponentstatetokens) | 按下状态覆盖；嵌套区域逐字段合并。  |
| `focus`            | [`LeafComponentStateTokens`](#leafcomponentstatetokens) | 键盘聚焦状态覆盖；保留可见焦点轮廓。 |
| `disabled`         | [`LeafComponentStateTokens`](#leafcomponentstatetokens) | 禁用状态覆盖；不改变禁用行为。    |

## LeafComponentStateTokens

状态只覆盖明确设置的外观字段。嵌套主题按字段继承，不修改父配置；`undefined` 不覆盖已有值。禁用状态优先于悬停、按下和聚焦，原生禁用行为与键盘焦点轮廓继续生效。

| 属性            | 类型       | 说明                    |
| ------------- | -------- | --------------------- |
| `color`       | `string` | 当前状态的文字颜色。            |
| `background`  | `string` | 当前状态的背景。              |
| `borderColor` | `string` | 当前状态的边框颜色。            |
| `shadow`      | `string` | 当前状态的 CSS box-shadow。 |

## LeafThemeStyle

带 `--leaf-*` 自定义属性的 React 样式类型。业务 CSS 读取变量的示例见 [定制主题](https://ifhover.github.io/leaf-ui/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 自定义属性。 |