用法

请始终使用语义化 token，而不是原始的 Tailwind 颜色。这样可以确保你的 UI 自动适配浅色模式和深色模式，并让组件在各主题之间保持一致。

正确

<div className="bg-lark-base text-lark-default border-lark-hairline">
  <button className="bg-lark-brand text-white">Primary</button>
  <button className="bg-lark-control text-lark-default">Secondary</button>
</div>

错误

{
  /* Never use raw Tailwind colors */
}
<div className="bg-white dark:bg-gray-900 text-black dark:text-white">
  <button className="bg-blue-500">Primary</button>
</div>;

Lint 规则会强制执行这一点：no-primitive-colors 规则会标记任何原始 Tailwind 颜色，例如 bg-blue-500。

模式

在父元素上设置 data-mode 即可控制浅色/深色模式。请不要使用 Tailwind 的 dark: 变体——语义化 token 已通过 CSS 的 light-dark() 自动处理深色模式。

// Set mode on html or body
<html data-mode="light">  // Light mode
<html data-mode="dark">   // Dark mode

// Components automatically adapt - no dark: variants needed
<div className="bg-lark-base text-lark-default" />

主题

主题会在保持 token 名称不变的前提下覆盖语义化 token 的值。在父元素上设置 data-theme 即可应用主题。

可用主题

• lark——默认的 Universe Design 主题（无需设置属性）

// The default theme is applied automatically; data-theme is optional
<div data-theme="lark">
  <Button>Lark Styled</Button>
</div>

// Themes work with both light and dark mode
<html data-mode="dark" data-theme="lark">

主题生成器

主题在一个集中配置中定义，并生成为 CSS 文件。主题生成器确保所有主题之间保持一致。

# List all tokens and their theme overrides

pnpm --filter @lark-ui/core codegen:themes --list

# Generate theme CSS files

pnpm --filter @lark-ui/core codegen:themes

# Preview changes without writing files

pnpm --filter @lark-ui/core codegen:themes --dry-run

主题配置：packages/lark/scripts/theme-generator/config.ts

创建新主题

在配置文件中添加主题覆盖项。只覆盖需要改动的 token——其他所有 token 都继承自基础的 lark 主题。

// In scripts/theme-generator/config.ts
export const THEME_CONFIG: ThemeConfig = {
  color: {
    "lark-base": {
      newName: "",
      theme: {
        lark: {
          light: "var(--color-white, #fff)",
          dark: "var(--color-black, #000)",
        },
        // Add your theme override
        myTheme: {
          light: "#f0f4f8",
          dark: "#1a1f2e",
        },
      },
    },
    // ... other tokens
  },
};

// Add to available themes
export const AVAILABLE_THEMES = ["lark", "myTheme"] as const;

然后运行 pnpm codegen:themes 生成 CSS。

语义化 token

我们使用语义化 token 按用途对颜色进行分组。请选择与元素角色相匹配的 token，而不是你想要达到的具体颜色。

语义化 token 是按角色命名的，而不是按色相命名。像 bg-lark-danger 这样的 token 传达的是意图——它并不暗指某种特定的红色，其具体数值可以随主题或颜色模式变化，而无需改动你的组件代码。

表面层级

表面层级用于在 UI 中建立深度和层次。请从最外层背景开始，按顺序向内使用。

品牌色

语义化状态色

每种状态色都有两个变体：用于图标和指示器的实色，以及用于内容背后背景填充的 -tint 变体（即 Badge 徽标或 Banner 通告栏）。

状态圆点使用实色 token bg-lark-*，图标使用 fill-lark-*，边框和描边使用 border-lark-*、ring-lark-*。通告栏和徽标使用 -tint 变体，并搭配不同的透明度数值。

import { WarningIcon } from "@phosphor-icons/react";

export function StatusBannerDemo() {
  return (
    <div className="flex items-center gap-2 rounded-lg bg-lark-danger-tint/70 p-4">
      <WarningIcon weight="fill" className="fill-lark-danger" />
      <span className="text-sm text-lark-danger">出错了。</span>
    </div>
  );
}

文字颜色

语义化文字颜色（即 text-lark-success）默认更深，以便在 tint-* 背景上提供更好的对比度和可读性。

边框与描边

token 参考

在页头切换主题，即可查看 token 如何适配。标记为「global」的 token 是需要显式启用的类，无论使用哪个主题都可用。