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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/guide/theming.md.

定制主题

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

改颜色和圆角

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

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'设置主题基色并生成七档语义色;原色不会被改写。
borderRadius10调整基础圆角,0 为直角。
appearance'light' / 'dark'设置浅色或深色外观。
controlHeight40调整单行控件的基础高度,小、大尺寸同步变化。
fontSize14设置组件基础字号。
lineHeight20设置正文行高;数字默认为 px,1–4 保留旧倍率语义,也支持 CSS 长度。
fontFamily'Inter, sans-serif'设置字体;字体文件由应用加载。
motionfalse关闭当前区域的动效,保留正常操作。

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

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

复制主题示例

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

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

你的下一份灵感

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' 恢复浅色:

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

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

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

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

加一个切换开关

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

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:

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

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

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

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

只调整一个区域

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

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:

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

density 与 theme 同级。默认值为 'comfortable';'compact' 会同时收紧控件、表单和浮层的间距,基础控件高度从 34px 调整为 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: '#1e964f',
    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,见 组件默认值。

描边、阴影与交互状态

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

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

<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 继续继承。完整字段与支持范围见 主题变量。

在业务样式中使用主题

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-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。

服务端渲染

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

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

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