主题

使用 CSS 变量和全局样式自定义 HeroUI 的设计系统

HeroUI 使用 CSS 变量和 BEM 类来实现主题化。你可以使用标准 CSS 自定义从颜色到组件样式的所有内容。

想要创建你自己的主题？ 试试主题构建器，以可视化方式自定义颜色、圆角、字体等，然后导出 CSS 用于你的项目。

工作原理

HeroUI 的主题系统构建于 Tailwind CSS v4 的主题之上。当你导入 @lenso/tokens 时，它会使用 Tailwind 的内置调色板，将其映射到语义化变量，自动在浅色和深色主题之间切换，并使用 CSS 层和 @theme 指令进行组织。

命名规则：

不带后缀的颜色用作背景（例如 --accent）
带 -foreground 后缀的颜色用于该背景上的文本（例如 --accent-foreground）

快速开始

应用主题： 将主题类添加到 HTML 并将颜色应用到 body 上：

1<html class="light" data-theme="light">2  <body class="bg-background text-foreground">3    <!-- Your app -->4  </body>5</html>

切换主题：

1<!-- Light theme -->2<html class="light" data-theme="light">3
4<!-- Dark theme -->5<html class="dark" data-theme="dark">

使用 next-themes 以编程方式切换主题（适用于 Next.js）：

首先，用 ThemeProvider 包装你的应用：

1// app/providers.tsx2"use client";3
4import { ThemeProvider } from "next-themes";5
6export function Providers({ children }: { children: React.ReactNode }) {7  return (8    <ThemeProvider attribute="class" defaultTheme="light">9      {children}10    </ThemeProvider>11  );12}

1// app/layout.tsx2import { Providers } from "./providers";3
4export default function RootLayout({ children }: { children: React.ReactNode }) {5  return (6    <html lang="en" suppressHydrationWarning>7      <body className="bg-background text-foreground">8        <Providers>{children}</Providers>9      </body>10    </html>11  );12}

然后使用 useTheme 在主题之间切换：

1"use client";2
3import { useTheme } from "next-themes";4
5export function ThemeSwitch() {6  const { theme, setTheme } = useTheme();7
8  return (9    <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>10      Toggle {theme === "dark" ? "Light" : "Dark"} Mode11    </button>12  );13}

覆盖颜色：

1/* app/globals.css */2@import "tailwindcss";3@import "@lenso/tokens";4
5:root {6  /* Override any color variable */7  --accent: oklch(0.7 0.25 260);8  --success: oklch(0.65 0.15 155);9}

注意：完整的调色板和视觉参考请参见颜色。

深色模式：如需基于 next-themes 与 HeroUI useTheme 钩子的完整配置指南，请参见深色模式。

创建你自己的主题：

View code

使用你的主题：

1/* app/globals.css */2@layer theme, base, components, utilities;3
4@import "tailwindcss";5@import "@lenso/tokens";6
7@import "./src/themes/ocean.css" layer(theme); /* [!code highlight]*/

应用你的主题：

1<!-- index.html -->2
3<!-- Light ocean -->4<html data-theme="ocean">5
6<!-- Dark ocean -->7<html data-theme="ocean-dark">

自定义组件

全局组件样式： 使用 BEM 类覆盖任何组件：

1@layer components {2  /* Customize buttons */3  .button {4    @apply font-semibold tracking-wide;5  }6
7  .button--primary {8    @apply bg-blue-600 hover:bg-blue-700;9  }10
11  /* Customize accordions */12  .accordion__trigger {13    @apply text-lg font-bold;14  }15}

注意：完整的样式参考请参见样式。

查找组件类名： 每个组件文档页面都会列出所有可用的类名（基类、修饰符、元素、状态）。示例：Button 类名

导入策略

完整导入（推荐）： 两行代码即可获得全部内容：

1@import "tailwindcss";2@import "@lenso/tokens";

按需导入： 只导入你需要的内容：

1/* Define layers */2@layer theme, base, components, utilities;3
4/* Base requirements */5@import "tailwindcss";6@import "@lenso/tokens/base" layer(base);7/* OR specific base file */8@import "@lenso/tokens/base/base.css" layer(base);9
10/* Theme variables */11@import "@lenso/tokens/themes/shared/theme.css" layer(theme);12@import "@lenso/tokens/themes/default" layer(theme);13/* OR specific theme files */14@import "@lenso/tokens/themes/default/index.css" layer(theme);15@import "@lenso/tokens/themes/default/variables.css" layer(theme);16
17/* Components (all components) */18@import "@lenso/tokens/components" layer(components);19/* OR specific component files */20@import "@lenso/tokens/components/index.css" layer(components);21@import "@lenso/tokens/components/button.css" layer(components);22@import "@lenso/tokens/components/accordion.css" layer(components);23
24/* Utilities (optional) */25@import "@lenso/tokens/utilities" layer(utilities);26
27/* Variants (optional) */28@import "@lenso/tokens/variants" layer(utilities);

注意：目录导入（例如 @lenso/tokens/components）会自动解析为其对应的 index.css 文件。使用显式文件路径（例如 @lenso/tokens/components/button.css）来导入单个组件的样式。

Headless 模式： 从头开始构建你自己的样式：

1@import "tailwindcss";2@import "@lenso/tokens/base/base.css";3
4/* Your custom styles */5.button {6  /* Your button styles */7}

添加自定义颜色

将你自己的语义化颜色添加到主题中：

1/* Define in both light and dark themes */2:root,3[data-theme="light"] {4  --info: oklch(0.6 0.15 210);5  --info-foreground: oklch(0.98 0 0);6}7
8.dark,9[data-theme="dark"] {10  --info: oklch(0.7 0.12 210);11  --info-foreground: oklch(0.15 0 0);12}13
14/* Make the color available to Tailwind */15@theme inline {16  --color-info: var(--info);17  --color-info-foreground: var(--info-foreground);18}

现在你可以在组件中使用它：

1<div className="bg-info text-info-foreground">Info message</div>

变量参考

HeroUI 在 variables.css 中定义了三种类型的变量：

基础变量（Base Variables） — 不会变化的值，例如 --white、--black、间距以及排版
主题变量（Theme Variables） — 在浅色 / 深色主题之间切换的颜色，以及滚动条令牌（--scrollbar-thumb、--scrollbar-width 等）
计算变量（Calculated Variables） — 悬停状态、柔和（soft）变体以及边框 / 分隔线层级（每个浅色 / 深色主题中的 Calculated Colors 区块，使用 color-mix() 计算）

如需完整参考，请查阅：颜色文档、默认主题变量、共享主题工具

Tailwind 主题桥接（@theme inline）：

themes/shared/theme.css 将语义化变量映射为 Tailwind 令牌（--color-*、--radius-*、--ease-*）。计算颜色引用的是 variables.css 中的底层变量（例如 --surface-hover、--accent-soft）—— 它们并不会在该文件中通过 color-mix() 内联展开：

View code

表单控件依赖 --field-* 主题变量。悬停、聚焦及边框变体定义于 variables.css 的 Calculated Colors 区块中，并在 theme.css 中映射到 Tailwind 令牌（例如 --color-field-hover: var(--field-hover)）。在你的主题中覆盖 --field-background、--field-hover 及相关令牌，即可重新设计输入框、复选框、单选框和 OTP 输入槽的样式，而不会影响按钮或卡片等表面（surface）。

滚动条

HeroUI 为组件中的滚动区域（表格、弹出框、抽屉等）应用统一的滚动条样式。滚动条使用标准 CSS 属性（scrollbar-width、scrollbar-color、scrollbar-gutter），不再依赖 ::-webkit-scrollbar 覆盖。

模式 — 在 <html>、组件根元素或滚动插槽上设置 data-scrollbar：

模式	`data-scrollbar`	行为
HeroUI 纤细	（未设置）或 `thin`	使用主题令牌呈现的纤细滑块
操作系统 / 浏览器	`default`	原生滚动条（`auto`）
隐藏	`none`	不显示滚动条（`scrollbar-width: none`）

1<!-- 全局使用原生滚动条 -->2<html data-scrollbar="default">3
4<!-- 在某个子树中恢复 HeroUI 滚动条 -->5<main data-scrollbar="thin">6  ...7</main>8
9<!-- 在某个子树中隐藏滚动条（例如弹出框） -->10<div data-scrollbar="none">11  ...12</div>

主题变量 — 在 variables.css 的浅色与深色主题区块中定义：

变量	描述
`--scrollbar-thumb`	滑块颜色（默认通过 `color-mix` 混入 15% 的 `--foreground`）
`--scrollbar-track`	轨道颜色（默认 `transparent`）
`--scrollbar-gutter`	滚动条间隙（默认 `auto`）
`--scrollbar-width`	`scrollbar-width` 属性（默认 `thin`）
`--scrollbar-color`	`scrollbar-color` 属性（默认为滑块颜色 + 轨道颜色）
`--scrollbar`	`--scrollbar-thumb` 的旧版别名

全局自定义：

1/* app/globals.css */2:root {3  --scrollbar-thumb: color-mix(in oklch, var(--accent) 30%, transparent);4  --scrollbar-gutter: auto;5}

按滚动插槽 — 在组件上传入 data-scrollbar，或在外层包裹元素上覆盖相关令牌：

1<Table data-scrollbar="default">2  ...3</Table>4
5<Drawer.Content data-scrollbar="thin" />6
7<Calendar.YearPickerGrid data-scrollbar="none" />

自定义溢出区域 — 在自己的元素上使用 @lenso/tokens 提供的 scrollbar、scrollbar-thin、scrollbar-default 或 scrollbar-none 工具类。基于类的覆盖方式详见样式。

注意：部分组件默认隐藏滚动条（日期选择器弹出框、颜色选择器、次级标签页）。嵌套的滚动插槽（例如日期选择器内部的日历年份选择器）会保留 HeroUI 滚动条，因为 scrollbar-none 只作用于其所在的元素本身，不会影响使用 @apply scrollbar 的后代元素。