在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

shadcn-ui/ui

菜单

主题定制

相关源文件

本文档涵盖了 shadcn/ui 中的主题定制系统，包括 CSS 变量配置、颜色面板管理和自定义主题创建。有关 CSS 变量实现细节的信息，请参阅 CSS 变量系统。有关暗黑模式功能，请参阅 暗黑模式。

概述

shadcn/ui 的主题系统提供了两种主要的主题定制方法：CSS 变量（推荐）和 Tailwind 实用工具类。该系统支持通过结构化的变量命名约定来定制颜色面板、基础颜色配置和注册表级别的主题覆盖。

配置方法

CSS 变量方法

CSS 变量方法使用 CSS 自定义属性进行动态主题化。此方法通过 components.json 中的 tailwind.cssVariables 属性进行配置。

来源: apps/www/content/docs/theming.mdx14-35 apps/www/content/docs/components-json.mdx88-104

实用工具类方法

实用工具类方法使用带有暗黑模式变体的直接 Tailwind 颜色类

来源: apps/www/content/docs/theming.mdx37-64

颜色变量系统

命名约定

该系统遵循 background/foreground 的约定，其中背景颜色省略了 background 后缀。

CSS 变量用法类目的
--primarybg-primary主要背景颜色
--primary-foregroundtext-primary-foreground主要文本颜色
--secondarybg-secondary次要背景颜色
--secondary-foregroundtext-secondary-foreground次要文本颜色

来源: apps/www/content/docs/theming.mdx66-88

核心变量集

主题系统为一致的组件样式定义了一套全面的 CSS 变量

来源: apps/www/content/docs/theming.mdx89-162 apps/www/content/docs/components-json.mdx76-86

基础颜色面板

该系统提供了五种基础颜色面板，每种都有亮色和暗色模式变体。基础颜色通过 components.json 中的 tailwind.baseColor 配置。

基础颜色配置值用例
Neutral"neutral"极简，纯灰度
Zinc"zinc"冷色调灰度
Slate"slate"蓝调灰度
Stone"stone"暖色调灰度
Gray"gray"平衡灰度

来源: apps/www/content/docs/theming.mdx195-562 apps/www/content/docs/components-json.mdx76-86

自定义颜色添加

CSS 变量方法

添加自定义颜色需要更新 CSS 变量和 Tailwind 配置

来源: apps/www/content/docs/theming.mdx164-189

注册表集成

注册表项可以通过注册表项定义中的 cssVars 属性定义自定义 CSS 变量。

来源: apps/www/content/docs/registry/registry-item-json.mdx241-259 apps/www/content/docs/registry/faq.mdx50-86

CLI 集成

初始化配置

CLI 的 init 命令通过命令行选项配置主题行为

CLI 选项效果配置目标
--css-variables启用 CSS 变量模式tailwind.cssVariables: true
--no-css-variables启用实用工具类模式tailwind.cssVariables: false

来源: apps/www/content/docs/cli.mdx34-36

组件安装

CLI 的 add 命令会尊重现有的主题配置，并在注册表项定义自定义颜色时更新 CSS 变量。

来源: apps/www/content/docs/cli.mdx66-67 apps/www/content/docs/registry/faq.mdx86

配置文件集成

components.json Schema

主题配置集中在 components.json 中，结构如下：

来源: apps/www/content/docs/components-json.mdx46-104

Tailwind 集成

该主题系统通过 CSS 变量引用和实用工具类生成与 Tailwind CSS 集成，从而在保持框架兼容性的同时，实现跨组件的一致性设计标记使用。

来源: apps/www/content/docs/theming.mdx1-563 apps/www/content/docs/components-json.mdx1-214