daisyui-5

daisyUI 5

适用于 Tailwind CSS 4 的 CSS 组件库。为常见 UI 组件提供语义化类名。

安装

1. 需要 Tailwind CSS 4。无需使用 tailwind.config.js（在 v4 中已弃用）。
2. 安装：npm i -D daisyui@latest
3. CSS 文件：

@import "tailwindcss";
@plugin "daisyui";

4. CDN 替代方案：

<link href="https://cdn.jsdelivr.net/npm/daisyui@5" rel="stylesheet" type="text/css" />
<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

使用规则

1. 通过组合以下类来设置元素样式：组件类 + 部分类 + 修饰类
2. 当 daisyUI 类不够用时，使用 Tailwind 工具类进行自定义（例如 btn px-10）
3. 仅在最后手段中使用工具类的 ! 后缀来提高优先级（例如 btn bg-red-500!）
4. 如果 daisyUI 中没有相应组件，则使用 Tailwind 工具类构建
5. 在 flex/grid 布局中使用 Tailwind 响应式前缀
6. 仅使用 daisyUI 类名或 Tailwind 工具类，不使用自定义 CSS
7. 使用 https://picsum.photos/{w}/{h} 作为占位图片
8. 除非必要，否则不要添加自定义字体
9. 除非必要，否则不要向 body 添加 bg-base-100 text-base-content
10. 设计决策遵循 Refactoring UI 最佳实践

类名类别

• component：必需的组件类
• part：组件的子部分
• style：设置特定样式
• behavior：更改行为
• color：设置特定颜色
• size：设置特定尺寸
• placement/direction：设置位置/方向
• modifier：修改组件
• variant：条件前缀（variant:utility-class）

颜色

语义颜色名称

颜色	用途
primary / primary-content	主品牌色 / primary 上的前景色
secondary / secondary-content	次要品牌色 / 前景色
accent / accent-content	强调品牌色 / 前景色
neutral / neutral-content	非饱和 UI / 前景色
base-100/200/300 / base-content	表面颜色（从浅到深）/ 前景色
info / info-content	信息提示 / 前景色
success / success-content	成功提示 / 前景色
warning / warning-content	警告提示 / 前景色
error / error-content	错误提示 / 前景色

颜色规则

1. 在 Tailwind 工具类中使用 daisyUI 颜色名称：bg-primary、text-base-content
2. 颜色会随主题自动变化，无需 dark: 前缀
3. 避免使用 Tailwind 颜色名称（例如 text-gray-800），因为它们不会适配主题
4. 页面的大部分区域使用 base-* 颜色，重要元素使用 primary
5. *-content 颜色必须与对应颜色形成良好对比

配置

@plugin "daisyui"; /* no config */

@plugin "daisyui" {
  themes: light --default, dark --prefersdark;
  root: ":root";
  include: ;
  exclude: ;
  prefix: ;
  logs: true;
}

配置选项：themes（启用/设置默认主题）、root、include/exclude（组件）、prefix（例如 daisy-）、logs。

自定义主题

@plugin "daisyui/theme" {
  name: "mytheme";
  default: true;
  prefersdark: false;
  color-scheme: light;
  --color-base-100: oklch(98% 0.02 240);
  --color-base-200: oklch(95% 0.03 240);
  --color-base-300: oklch(92% 0.04 240);
  --color-base-content: oklch(20% 0.05 240);
  --color-primary: oklch(55% 0.3 240);
  --color-primary-content: oklch(98% 0.01 240);
  --color-secondary: oklch(70% 0.25 200);
  --color-secondary-content: oklch(98% 0.01 200);
  --color-accent: oklch(65% 0.25 160);
  --color-accent-content: oklch(98% 0.01 160);
  --color-neutral: oklch(50% 0.05 240);
  --color-neutral-content: oklch(98% 0.01 240);
  --color-info: oklch(70% 0.2 220);
  --color-info-content: oklch(98% 0.01 220);
  --color-success: oklch(65% 0.25 140);
  --color-success-content: oklch(98% 0.01 140);
  --color-warning: oklch(80% 0.25 80);
  --color-warning-content: oklch(20% 0.05 80);
  --color-error: oklch(65% 0.3 30);
  --color-error-content: oklch(98% 0.01 30);
  --radius-selector: 1rem;
  --radius-field: 0.25rem;
  --radius-box: 0.5rem;
  --size-selector: 0.25rem;
  --size-field: 0.25rem;
  --border: 1px;
  --depth: 1;
  --noise: 0;
}

以上所有 CSS 变量均为必需项。颜色可以使用 OKLCH、十六进制或其他格式。

创建 DaisyUI 组件

创建或扩展封装 daisyUI 的 React 组件时，请遵循此工作流。有关详细模式、复合组件示例和测试模板，请参阅 references/creating-components.md。

1. 确定组件目录

检查 AGENTS.md 或 CLAUDE.md 中是否有 DAISY_COMPONENTS_DIR 变量。如果没有，则使用 src/components/daisy。

2. 确保基础文件存在

创建任何组件之前，请确认项目具备所需的基础设施。如果有缺失项，请根据随附的 scripts/ 模板创建。完整的初始化检查清单和文件内容请参阅 references/creating-components.md。

必需文件：

• <DAISY_COMPONENTS_DIR>/daisy-meta.ts — 使用随附的 scripts/daisy-meta.ts 创建
• generators/daisy/generate-daisy-safelist.ts — 使用随附的 scripts/generate-daisy-safelist.ts 创建（将导入路径更新为指向 daisy-meta.ts）
• src/app/styles/daisy.css — 必须导入 daisyUI 插件和生成的 safelist
• package.json 脚本 "generate:safelist" — 必须运行生成器
• 必须在根布局或全局 CSS 入口文件中导入 daisy.css

3. 在 daisy-meta.ts 中注册

将新组件的功能添加到 <DAISY_COMPONENTS_DIR>/daisy-meta.ts 中的 COMPONENT_CAPABILITIES。请参阅 daisyUI 文档（见下方的组件参考），了解它支持哪些修饰符。

4. 创建组件

• 遵循现有 <DAISY_COMPONENTS_DIR>/daisy* 文件中的模式
• 对于由多个部分组成的 daisyUI 组件（如 card、modal、dropdown 等），优先使用复合组件
• 复合组件中的每个子组件都应有自己的文件
• 有关复合组件结构，请参阅 references/creating-components.md

5. 生成 safelist

npm run generate:safelist

生成 src/app/styles/daisy-safelist.css。

6. 添加测试

使用项目的测试框架（检查 package.json，确认使用 jest 还是 vitest）。默认使用 Jest + React Testing Library。测试以下内容：渲染、prop 变化（颜色、尺寸、变体）、复合组件组合以及无障碍性。

7. 扩展 safelist 生成器

如果新组件引入了 generate-daisy-safelist.ts 尚未处理的功能修饰符，请更新 buildClassList()，使其遍历该修饰符。

组件参考

组件文档按类别划分。只需阅读相关文件：

• 布局组件：参阅 references/layout.md drawer、navbar、footer、hero、dock、divider、indicator、join、stack、fab
• 数据展示：参阅 references/data-display.md card、list、table、stat、badge、avatar、chat、timeline、countdown、diff、carousel、hover-3d、hover-gallery、text-rotate
• 输入组件：参阅 references/input.md button、input、textarea、select、checkbox、radio、toggle、range、rating、file-input、filter、fieldset、label、validator、calendar
• 反馈与覆盖层：参阅 references/feedback.md alert、modal、toast、loading、skeleton、progress、radial-progress、status、steps、swap、tab
• 导航与界面框架：参阅 references/navigation.md accordion、collapse、breadcrumbs、dropdown、tooltip、link、kbd、menu、mask、mockup-browser、mockup-code、mockup-phone、mockup-window、pagination、theme-controller