#定制主题

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

#改颜色和圆角

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

import { Button, ConfigProvider } from '@ifhover/leaf-ui';

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

把示例中的 Button 换成你的应用内容即可。按钮、输入框、选择器及浮层会一起使用这份主题；悬停、按下和焦点颜色会自动生成。

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

#常用参数

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

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

完整参数见 LeafTheme。需要单独调整文字色、背景色或某个尺寸时，再查阅 LeafThemeTokens。

#使用深色模式

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

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

组件的文字、背景和边框会一起切换。显式设置的 primaryColor 会保留原色；没有指定时使用该外观的默认主题色。

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

#加一个切换开关

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

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：

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

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

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

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

#只调整一个区域

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

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：

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

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

需要指定高度时再设置 theme.controlHeight，它优先于密度预设。例如 controlHeight: 40 会生成 34px / 40px / 46px 三种控件高度。尺寸对比见 ConfigProvider。

#进阶定制

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

#单独覆盖颜色或尺寸

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

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

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

将这个对象传给 <ConfigProvider theme={theme}>。这里的 borderRadiusLg 会覆盖自动生成的大圆角；motionDuration 的数字单位是毫秒。完整字段和说明见 LeafThemeTokens。

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

#只调整某类组件的样式

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

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

可用样式字段见 LeafComponentTokens，具体组件支持的字段以其文档为准。

这里的 theme.components 调整样式。如果想统一按钮的 size、variant 或其他组件参数，使用 ConfigProvider 上的 components，见 组件默认值。

#在业务样式中使用主题

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

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

.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 UI 组件的主题仍通过 ConfigProvider，业务 CSS 用这些变量读取结果。仅修改某个基础 CSS 变量，不会重新生成整套交互颜色。

使用 Tailwind CSS 时，可直接引入包提供的配置，通过 bg-leaf-surface、text-leaf-primary 等工具类复用主题。Tailwind 3 / 4 的接入方式见 Tailwind CSS。

#服务端渲染

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

主题色优先传入具体的 HEX、RGB 或 HSL 颜色。var(--brand-color) 需要在浏览器挂载后解析，不能保证服务端首屏就得到对应的派生颜色。

安装见 安装&快速开始，Next.js 等框架的接入见 服务端渲染，支持范围见 浏览器兼容性。