主题变量

日常定制优先设置 ConfigProvider 的 theme.primaryColor、theme.borderRadius 和 theme.controlHeight，其他样式会自动派生，见定制主题。

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`	—	正文行高。

类型导入

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。组件参数的默认值仍通过 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`	悬停状态覆盖；嵌套区域逐字段合并。
`active`	`LeafComponentStateTokens`	按下状态覆盖；嵌套区域逐字段合并。
`focus`	`LeafComponentStateTokens`	键盘聚焦状态覆盖；保留可见焦点轮廓。
`disabled`	`LeafComponentStateTokens`	禁用状态覆盖；不改变禁用行为。

LeafComponentStateTokens

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

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

LeafThemeStyle

带 --leaf-* 自定义属性的 React 样式类型。业务 CSS 读取变量的示例见定制主题。

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

#主题变量

#LeafThemeTokens

#类型导入

#LeafComponentTokens