shadcn/ui 定制与主题系统详解从 CSS 变量 Token 到 Preset 应用的完整实践指南【免费下载链接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.项目地址: https://gitcode.com/GitHub_Trending/ui/ui在 shadcn/ui 项目中组件并不写死颜色与圆角而是引用一组语义化 CSS 变量 Token改变变量即可改变所有引用它的组件。本篇基于官方技能文档 customization.md系统讲解这套「CSS 变量 → Tailwind 工具类 → 组件」的主题体系变量命名约定与 OKLCH 颜色格式、class 式暗色模式、apply命令应用 Preset 的多种用法、Tailwind v3/v4 下新增自定义颜色的正确姿势以及组件级定制的四级优先策略。读完后你可以独立完成主题换肤、品牌色定制和组件升级预览且改动可复制、可运行。主题机制CSS 变量、Tailwind 工具类与组件的三层链路shadcn/ui 的定制能力建立在一条清晰的链路上CSS 变量定义在:root浅色模式与.dark暗色模式中Tailwind 将它们映射为工具类如bg-primary、text-muted-foreground组件内部只使用这些工具类——修改某个变量所有引用它的组件会随之变化。以本仓库官网自身为例全局样式文件 完整展示了这条链路。第 44 行的theme inline块把每个语义变量注册为 Tailwind 颜色theme inline { --color-background: var(--background); --color-foreground: var(--foreground); --color-primary: var(--primary); --color-primary-foreground: var(--primary-foreground); --color-muted: var(--muted); /* ... 其余 token */ }随后:root与.dark两个选择器分别给出两套实际取值例如:root中--background: oklch(1 0 0).dark中--background: oklch(0.145 0 0)。这就是「改一个变量、全站组件跟着变」的底层原因组件类名引用的是--color-primary这类 Tailwind 颜色而它们最终指向的var(--primary)在暗色模式下会自动切换到.dark的取值。在components.json中tailwind.cssVariables: true默认值即表示启用这一 CSS 变量主题模式。颜色变量name / name-foreground 约定与 OKLCH 格式每个颜色都遵循name/name-foreground约定基础变量用于背景带-foreground后缀的用于该背景之上的文字与图标。官方文档给出的完整变量清单如下变量用途--background/--foreground页面背景与默认文字--card/--card-foreground卡片表面--primary/--primary-foreground主按钮与主操作--secondary/--secondary-foreground次级操作--muted/--muted-foreground弱化/禁用状态--accent/--accent-foreground悬停与强调状态--destructive/--destructive-foreground错误与危险操作--border默认边框颜色--input表单输入框边框--ring焦点环颜色--chart-1至--chart-5图表/数据可视化配色--sidebar-*侧边栏专属颜色--surface/--surface-foreground次级表面颜色统一使用 OKLCH 色彩空间例如--primary: oklch(0.205 0 0)三个数值依次为亮度lightness0–1、色度chroma0 表示无彩灰度、色相hue0–360。OKLCH 的优势在于相同亮度值下的人眼感知亮度一致便于系统地构建明暗两套配色。实际仓库中的取值可作为参照。全局样式 的:root中:root { --primary: oklch(0% 0 0); --primary-foreground: oklch(0.985 0 0); --secondary: oklch(0.97 0 0); --muted-foreground: oklch(0.556 0 0); --destructive: oklch(0.577 0.245 27.325); --border: oklch(0.922 0 0); --ring: oklch(0.708 0 0); }可以看到chroma为 0 的变量都是纯灰阶只有--destructive这类强调色才带有明显色相与色度。此外仓库的 暗色模式 区块中--border: oklch(1 0 0 / 10%)还使用了带透明度的写法——暗色模式下边框常用半透明白色而非实色。官方文档站点还提供了更完整的 Token 说明theming 文档/theming.mdx)其中补充了popover系列浮层表面、chart-1到chart-5图表默认调色板等变量的具体使用场景可作为本文变量表的延伸参考。暗色模式class 策略 next-themes暗色模式采用 class 策略在根元素上切换.dark类配合 CSS 中.dark选择器覆盖同一组变量。由于组件全部引用语义 Token不需要手动写dark:颜色覆盖——这正是 shadcn/ui 官方规则 styling.md 中「No manualdark:color overrides」的由来正确写法是bg-background text-foreground而不是bg-white dark:bg-gray-950。在 Next.js 中推荐用next-themes管理切换import { ThemeProvider } from next-themes ThemeProvider attributeclass defaultThemesystem enableSystem {children} /ThemeProvider三个属性各自的含义attributeclass通过 class而非 data 属性切换主题与.dark选择器约定一致defaultThemesystem无用户偏好时默认跟随系统enableSystem启用系统级监听系统切换明暗时页面自动跟随。本仓库的 主题 Provider 与 主题切换器 即为该模式的实际实现可作对照阅读。更换主题npx shadcn apply 的 Preset 工作流不想手动逐个调变量时可以直接应用 Preset。官方文档给出的命令全集如下# 应用来自 ui.shadcn.com 的 preset 码 npx shadcnlatest apply --preset a2r6bw # 位置参数简写同样有效 npx shadcnlatest apply a2r6bw # 切换到命名 preset 并覆盖现有组件 npx shadcnlatest apply --preset nova # 保留现有组件仅更新配置 npx shadcnlatest init --preset nova --force --no-reinstall # 使用自定义主题 URL npx shadcnlatest apply --preset https://ui.shadcn.com/init?baseradixstylenovathemeblue...也可以跳过 CLI直接编辑globals.css中的 CSS 变量完成手工换肤。从源码看 apply 命令的实际行为apply 命令实现 补充了几个文档中未展开、但实操时必须知道的行为细节只适用于已有项目。apply会做 preflight 检查若目录不存在或找不到components.json会报错并提示先运行init见 apply.ts。位置参数与--preset二选一。同时传两个不同的值会直接报错退出resolveApplyPresetapply.ts。自动保留当前 base。resolveApplyInitUrl会从现有components.json读取basebase或radix并写入初始化 URLPreset 码本身并不编码 baseapply.ts。写入前备份。整个runInit过程包裹在withFileBackup(components.json)中失败时自动回滚apply.ts。--only只支持theme与font。源码中APPLY_ONLY_VALUES [theme, font]fonts是font的别名icon被刻意排除因为更换图标库可能触发整组件重装与变换apply.ts。即npx shadcnlatest apply code --only theme,font可以只更新主题部分而不重装 UI 组件。monorepo 会同步工作区配置。syncApplyWorkspaceConfigs会把style、tailwind.baseColor、cssVariables、iconLibrary等字段同步到其他 workspace 的components.jsonapply.ts。切换 preset 的四种策略SKILL.md 进一步把「切换 preset」归纳为需要先与用户确认的四种策略可视为 apply 命令的决策框架Overwrite覆盖npx shadcnlatest apply code覆盖已检测到的组件、字体与 CSS 变量Partial部分npx shadcnlatest apply code --only theme,font只更新选中部分Merge合并npx shadcnlatest init --preset code --force --no-reinstall后对每个已安装组件用--dry-run和--diff逐个智能合并Skip跳过仅更新配置与 CSS组件保持原样。新增自定义颜色定义变量 → 注册到 Tailwind → 使用官方文档强调新增变量必须加到npx shadcnlatest info输出的tailwindCssFile指向的文件中通常是globals.css绝不要为此新建 CSS 文件。完整三步流程如下。第 1 步在全局 CSS 中定义变量/* 1. 在全局 CSS 文件中定义。 */ :root { --warning: oklch(0.84 0.16 84); --warning-foreground: oklch(0.28 0.07 46); } .dark { --warning: oklch(0.41 0.11 46); --warning-foreground: oklch(0.99 0.02 95); }注意明暗两套都要给浅色下--warning是高明度琥珀色lightness 0.84暗色下换为低明度0.41以避免刺眼-foreground也相应反转。第 2 步按 Tailwind 版本注册Tailwind v4tailwindVersion为v4使用theme inline/* 2a. Tailwind v4 注册theme inline。 */ theme inline { --color-warning: var(--warning); --color-warning-foreground: var(--warning-foreground); }Tailwind v3npx shadcnlatest info中tailwindVersion为v3则在tailwind.config.js中注册// 2b. Tailwind v3 注册tailwind.config.js。 module.exports { theme: { extend: { colors: { warning: oklch(var(--warning) / alpha-value), warning-foreground: oklch(var(--warning-foreground) / alpha-value), }, }, }, }alpha-value占位符保证bg-warning/50这类透明度修饰仍然生效——这是 v3 下把变量接到 Tailwind 颜色的标准写法。第 3 步在组件中使用// 3. 在组件中使用。 div classNamebg-warning text-warning-foregroundWarning/div本仓库的 theming 文档/theming.mdx) 使用完全相同的warning示例并在「Adding New Tokens」一节确认了同一套三步流程可作为交叉验证。官方规则文件 styling.md 也指出当需要 success/positive 这类不存在的语义色时正确路径就是按本文档添加自定义 CSS 变量而不是临时使用原始 Tailwind 颜色。圆角一个 --radius 驱动整套圆角刻度--radius全局控制圆角组件从中派生取值rounded-lg即var(--radius)rounded-md即calc(var(--radius) - 2px)。仓库实际实现比文档示例更进一步globals.css 与 theming 文档/theming.mdx) 中定义的完整刻度为theme inline { --radius-sm: calc(var(--radius) * 0.6); --radius-md: calc(var(--radius) * 0.8); --radius-lg: var(--radius); --radius-xl: calc(var(--radius) * 1.4); --radius-2xl: calc(var(--radius) * 1.8); --radius-3xl: calc(var(--radius) * 2.2); --radius-4xl: calc(var(--radius) * 2.6); }其含义是radius-lg是基准值更小的圆角向下缩放、更大的向上放大修改:root中的--radius如0.625rem即可一次性更新整套圆角系统——这是「单一事实来源」的典型应用。组件级定制四级优先策略官方文档 customization.md 与规则文件 styling.md 给出一致的建议定制组件时按以下顺序选择手段能靠前就不要靠后。第 1 级优先使用内建 variantsButton variantoutline sizesm Click /Buttonstyling.md中给出的反例是Button classNameborder border-input bg-transparent hover:bg-accent——用className硬凑一个已有 variant 的外观这属于「用 className 做样式」而非「做布局」是明确反对的做法。第 2 级用 className 追加 Tailwind 布局类Card classNamemx-auto max-w-md.../Card注意边界className只应用于布局max-w-md、mx-auto、mt-4等不应用于覆盖组件颜色或排版。反例是Card classNamebg-blue-100 text-blue-900 font-bold正确做法是换语义 Token 或 variant。第 3 级编辑组件源码新增 variant直接修改已安装到项目中的组件源码组件是源码分发改就是改本地文件通过cva添加 variant// components/ui/button.tsx warning: bg-warning text-warning-foreground hover:bg-warning/90,第 4 级组合式 wrapper 组件把 shadcn/ui 原语组合成更高层组件是官方推荐的最终形态。文档中的完整示例——ConfirmDialog封装AlertDialogexport function ConfirmDialog({ title, description, onConfirm, children }) { return ( AlertDialog AlertDialogTrigger asChild{children}/AlertDialogTrigger AlertDialogContent AlertDialogHeader AlertDialogTitle{title}/AlertDialogTitle AlertDialogDescription{description}/AlertDialogDescription /AlertDialogHeader AlertDialogFooter AlertDialogCancelCancel/AlertDialogCancel AlertDialogAction onClick{onConfirm}Confirm/AlertDialogAction /AlertDialogFooter /AlertDialogContent /AlertDialog ) }组合而非重写Compose, dont reinvent是贯穿 SKILL.md 的核心原则设置页 Tabs Card 表单控件仪表盘 Sidebar Card Chart Table。同时该文件要求Dialog、Sheet、Drawer必须带 Title可用classNamesr-only视觉隐藏、浮层组件不手动加z-index、条件类名一律用cn()而非模板字符串三元——这些规则与本文的定制策略互相咬合值得配合阅读。检查组件更新--dry-run 与 --diff组件上游有新版时先预览、再更新。文档给出的命令是npx shadcnlatest add button --diff要精确预览更新会改动什么组合--dry-run与--diffnpx shadcnlatest add button --dry-run # 查看所有受影响文件 npx shadcnlatest add button --diff button.tsx # 查看某个具体文件的 diff这两个选项在 add 命令源码 中定义为--dry-run「preview changes without writing files」和--diff [path]「show diff for a file」并且源码注释明确--diff和--view会隐含--dry-run即传了--diff就不会真的写文件。而 SKILL.md 的「Updating Components」章节给出了完整的智能合并工作流四条铁律是先npx shadcnlatest add component --dry-run看全部受影响文件对每个文件npx shadcnlatest add component --diff file对比上游与本地差异按 diff 逐文件决策无本地改动可直接覆盖有本地改动则分析后保留本地修改地合并上游更新用户明确说「全更新」时可用--overwrite但需先确认未获用户明确同意绝不使用--overwrite也绝不绕过 CLI 手动抓取 GitHub 原始文件。值得补充的是独立shadcn diff命令在当前 CLI 中已标记为弃用见 diff.ts 的[DEPRECATED]说明其「拉取 registry 内容 → 经过 transform 管线import/RSC/CSS 变量/图标等变换→ 与本地文件做diffLines对比」的逻辑已并入add --diff与文档推荐的用法一致。小结shadcn/ui 的定制体系可以用三层来概括变量层:root/.dark下的语义 Token OKLCH 取值 --radius派生刻度、工具层theme inline或tailwind.config.js把变量注册为 Tailwind 颜色、组件层variant → className 布局 → 源码加 variant → wrapper 组合的升级路径。配合apply/init的 Preset 命令完成整站换肤再配合add --dry-run --diff安全跟进上游更新就构成了一个从「改一行变量」到「整项目主题迁移」的完整闭环。相关参考customization.md、styling.md、SKILL.md、globals.css、apply.ts。【免费下载链接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.项目地址: https://gitcode.com/GitHub_Trending/ui/ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 shadcn/ui 定制与主题系统详解：从 CSS 变量 Token 到 Preset 应用的完整实践指南
shadcn/ui 定制与主题系统详解从 CSS 变量 Token 到 Preset 应用的完整实践指南【免费下载链接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.项目地址: https://gitcode.com/GitHub_Trending/ui/ui在 shadcn/ui 项目中组件并不写死颜色与圆角而是引用一组语义化 CSS 变量 Token改变变量即可改变所有引用它的组件。本篇基于官方技能文档 customization.md系统讲解这套「CSS 变量 → Tailwind 工具类 → 组件」的主题体系变量命名约定与 OKLCH 颜色格式、class 式暗色模式、apply命令应用 Preset 的多种用法、Tailwind v3/v4 下新增自定义颜色的正确姿势以及组件级定制的四级优先策略。读完后你可以独立完成主题换肤、品牌色定制和组件升级预览且改动可复制、可运行。主题机制CSS 变量、Tailwind 工具类与组件的三层链路shadcn/ui 的定制能力建立在一条清晰的链路上CSS 变量定义在:root浅色模式与.dark暗色模式中Tailwind 将它们映射为工具类如bg-primary、text-muted-foreground组件内部只使用这些工具类——修改某个变量所有引用它的组件会随之变化。以本仓库官网自身为例全局样式文件 完整展示了这条链路。第 44 行的theme inline块把每个语义变量注册为 Tailwind 颜色theme inline { --color-background: var(--background); --color-foreground: var(--foreground); --color-primary: var(--primary); --color-primary-foreground: var(--primary-foreground); --color-muted: var(--muted); /* ... 其余 token */ }随后:root与.dark两个选择器分别给出两套实际取值例如:root中--background: oklch(1 0 0).dark中--background: oklch(0.145 0 0)。这就是「改一个变量、全站组件跟着变」的底层原因组件类名引用的是--color-primary这类 Tailwind 颜色而它们最终指向的var(--primary)在暗色模式下会自动切换到.dark的取值。在components.json中tailwind.cssVariables: true默认值即表示启用这一 CSS 变量主题模式。颜色变量name / name-foreground 约定与 OKLCH 格式每个颜色都遵循name/name-foreground约定基础变量用于背景带-foreground后缀的用于该背景之上的文字与图标。官方文档给出的完整变量清单如下变量用途--background/--foreground页面背景与默认文字--card/--card-foreground卡片表面--primary/--primary-foreground主按钮与主操作--secondary/--secondary-foreground次级操作--muted/--muted-foreground弱化/禁用状态--accent/--accent-foreground悬停与强调状态--destructive/--destructive-foreground错误与危险操作--border默认边框颜色--input表单输入框边框--ring焦点环颜色--chart-1至--chart-5图表/数据可视化配色--sidebar-*侧边栏专属颜色--surface/--surface-foreground次级表面颜色统一使用 OKLCH 色彩空间例如--primary: oklch(0.205 0 0)三个数值依次为亮度lightness0–1、色度chroma0 表示无彩灰度、色相hue0–360。OKLCH 的优势在于相同亮度值下的人眼感知亮度一致便于系统地构建明暗两套配色。实际仓库中的取值可作为参照。全局样式 的:root中:root { --primary: oklch(0% 0 0); --primary-foreground: oklch(0.985 0 0); --secondary: oklch(0.97 0 0); --muted-foreground: oklch(0.556 0 0); --destructive: oklch(0.577 0.245 27.325); --border: oklch(0.922 0 0); --ring: oklch(0.708 0 0); }可以看到chroma为 0 的变量都是纯灰阶只有--destructive这类强调色才带有明显色相与色度。此外仓库的 暗色模式 区块中--border: oklch(1 0 0 / 10%)还使用了带透明度的写法——暗色模式下边框常用半透明白色而非实色。官方文档站点还提供了更完整的 Token 说明theming 文档/theming.mdx)其中补充了popover系列浮层表面、chart-1到chart-5图表默认调色板等变量的具体使用场景可作为本文变量表的延伸参考。暗色模式class 策略 next-themes暗色模式采用 class 策略在根元素上切换.dark类配合 CSS 中.dark选择器覆盖同一组变量。由于组件全部引用语义 Token不需要手动写dark:颜色覆盖——这正是 shadcn/ui 官方规则 styling.md 中「No manualdark:color overrides」的由来正确写法是bg-background text-foreground而不是bg-white dark:bg-gray-950。在 Next.js 中推荐用next-themes管理切换import { ThemeProvider } from next-themes ThemeProvider attributeclass defaultThemesystem enableSystem {children} /ThemeProvider三个属性各自的含义attributeclass通过 class而非 data 属性切换主题与.dark选择器约定一致defaultThemesystem无用户偏好时默认跟随系统enableSystem启用系统级监听系统切换明暗时页面自动跟随。本仓库的 主题 Provider 与 主题切换器 即为该模式的实际实现可作对照阅读。更换主题npx shadcn apply 的 Preset 工作流不想手动逐个调变量时可以直接应用 Preset。官方文档给出的命令全集如下# 应用来自 ui.shadcn.com 的 preset 码 npx shadcnlatest apply --preset a2r6bw # 位置参数简写同样有效 npx shadcnlatest apply a2r6bw # 切换到命名 preset 并覆盖现有组件 npx shadcnlatest apply --preset nova # 保留现有组件仅更新配置 npx shadcnlatest init --preset nova --force --no-reinstall # 使用自定义主题 URL npx shadcnlatest apply --preset https://ui.shadcn.com/init?baseradixstylenovathemeblue...也可以跳过 CLI直接编辑globals.css中的 CSS 变量完成手工换肤。从源码看 apply 命令的实际行为apply 命令实现 补充了几个文档中未展开、但实操时必须知道的行为细节只适用于已有项目。apply会做 preflight 检查若目录不存在或找不到components.json会报错并提示先运行init见 apply.ts。位置参数与--preset二选一。同时传两个不同的值会直接报错退出resolveApplyPresetapply.ts。自动保留当前 base。resolveApplyInitUrl会从现有components.json读取basebase或radix并写入初始化 URLPreset 码本身并不编码 baseapply.ts。写入前备份。整个runInit过程包裹在withFileBackup(components.json)中失败时自动回滚apply.ts。--only只支持theme与font。源码中APPLY_ONLY_VALUES [theme, font]fonts是font的别名icon被刻意排除因为更换图标库可能触发整组件重装与变换apply.ts。即npx shadcnlatest apply code --only theme,font可以只更新主题部分而不重装 UI 组件。monorepo 会同步工作区配置。syncApplyWorkspaceConfigs会把style、tailwind.baseColor、cssVariables、iconLibrary等字段同步到其他 workspace 的components.jsonapply.ts。切换 preset 的四种策略SKILL.md 进一步把「切换 preset」归纳为需要先与用户确认的四种策略可视为 apply 命令的决策框架Overwrite覆盖npx shadcnlatest apply code覆盖已检测到的组件、字体与 CSS 变量Partial部分npx shadcnlatest apply code --only theme,font只更新选中部分Merge合并npx shadcnlatest init --preset code --force --no-reinstall后对每个已安装组件用--dry-run和--diff逐个智能合并Skip跳过仅更新配置与 CSS组件保持原样。新增自定义颜色定义变量 → 注册到 Tailwind → 使用官方文档强调新增变量必须加到npx shadcnlatest info输出的tailwindCssFile指向的文件中通常是globals.css绝不要为此新建 CSS 文件。完整三步流程如下。第 1 步在全局 CSS 中定义变量/* 1. 在全局 CSS 文件中定义。 */ :root { --warning: oklch(0.84 0.16 84); --warning-foreground: oklch(0.28 0.07 46); } .dark { --warning: oklch(0.41 0.11 46); --warning-foreground: oklch(0.99 0.02 95); }注意明暗两套都要给浅色下--warning是高明度琥珀色lightness 0.84暗色下换为低明度0.41以避免刺眼-foreground也相应反转。第 2 步按 Tailwind 版本注册Tailwind v4tailwindVersion为v4使用theme inline/* 2a. Tailwind v4 注册theme inline。 */ theme inline { --color-warning: var(--warning); --color-warning-foreground: var(--warning-foreground); }Tailwind v3npx shadcnlatest info中tailwindVersion为v3则在tailwind.config.js中注册// 2b. Tailwind v3 注册tailwind.config.js。 module.exports { theme: { extend: { colors: { warning: oklch(var(--warning) / alpha-value), warning-foreground: oklch(var(--warning-foreground) / alpha-value), }, }, }, }alpha-value占位符保证bg-warning/50这类透明度修饰仍然生效——这是 v3 下把变量接到 Tailwind 颜色的标准写法。第 3 步在组件中使用// 3. 在组件中使用。 div classNamebg-warning text-warning-foregroundWarning/div本仓库的 theming 文档/theming.mdx) 使用完全相同的warning示例并在「Adding New Tokens」一节确认了同一套三步流程可作为交叉验证。官方规则文件 styling.md 也指出当需要 success/positive 这类不存在的语义色时正确路径就是按本文档添加自定义 CSS 变量而不是临时使用原始 Tailwind 颜色。圆角一个 --radius 驱动整套圆角刻度--radius全局控制圆角组件从中派生取值rounded-lg即var(--radius)rounded-md即calc(var(--radius) - 2px)。仓库实际实现比文档示例更进一步globals.css 与 theming 文档/theming.mdx) 中定义的完整刻度为theme inline { --radius-sm: calc(var(--radius) * 0.6); --radius-md: calc(var(--radius) * 0.8); --radius-lg: var(--radius); --radius-xl: calc(var(--radius) * 1.4); --radius-2xl: calc(var(--radius) * 1.8); --radius-3xl: calc(var(--radius) * 2.2); --radius-4xl: calc(var(--radius) * 2.6); }其含义是radius-lg是基准值更小的圆角向下缩放、更大的向上放大修改:root中的--radius如0.625rem即可一次性更新整套圆角系统——这是「单一事实来源」的典型应用。组件级定制四级优先策略官方文档 customization.md 与规则文件 styling.md 给出一致的建议定制组件时按以下顺序选择手段能靠前就不要靠后。第 1 级优先使用内建 variantsButton variantoutline sizesm Click /Buttonstyling.md中给出的反例是Button classNameborder border-input bg-transparent hover:bg-accent——用className硬凑一个已有 variant 的外观这属于「用 className 做样式」而非「做布局」是明确反对的做法。第 2 级用 className 追加 Tailwind 布局类Card classNamemx-auto max-w-md.../Card注意边界className只应用于布局max-w-md、mx-auto、mt-4等不应用于覆盖组件颜色或排版。反例是Card classNamebg-blue-100 text-blue-900 font-bold正确做法是换语义 Token 或 variant。第 3 级编辑组件源码新增 variant直接修改已安装到项目中的组件源码组件是源码分发改就是改本地文件通过cva添加 variant// components/ui/button.tsx warning: bg-warning text-warning-foreground hover:bg-warning/90,第 4 级组合式 wrapper 组件把 shadcn/ui 原语组合成更高层组件是官方推荐的最终形态。文档中的完整示例——ConfirmDialog封装AlertDialogexport function ConfirmDialog({ title, description, onConfirm, children }) { return ( AlertDialog AlertDialogTrigger asChild{children}/AlertDialogTrigger AlertDialogContent AlertDialogHeader AlertDialogTitle{title}/AlertDialogTitle AlertDialogDescription{description}/AlertDialogDescription /AlertDialogHeader AlertDialogFooter AlertDialogCancelCancel/AlertDialogCancel AlertDialogAction onClick{onConfirm}Confirm/AlertDialogAction /AlertDialogFooter /AlertDialogContent /AlertDialog ) }组合而非重写Compose, dont reinvent是贯穿 SKILL.md 的核心原则设置页 Tabs Card 表单控件仪表盘 Sidebar Card Chart Table。同时该文件要求Dialog、Sheet、Drawer必须带 Title可用classNamesr-only视觉隐藏、浮层组件不手动加z-index、条件类名一律用cn()而非模板字符串三元——这些规则与本文的定制策略互相咬合值得配合阅读。检查组件更新--dry-run 与 --diff组件上游有新版时先预览、再更新。文档给出的命令是npx shadcnlatest add button --diff要精确预览更新会改动什么组合--dry-run与--diffnpx shadcnlatest add button --dry-run # 查看所有受影响文件 npx shadcnlatest add button --diff button.tsx # 查看某个具体文件的 diff这两个选项在 add 命令源码 中定义为--dry-run「preview changes without writing files」和--diff [path]「show diff for a file」并且源码注释明确--diff和--view会隐含--dry-run即传了--diff就不会真的写文件。而 SKILL.md 的「Updating Components」章节给出了完整的智能合并工作流四条铁律是先npx shadcnlatest add component --dry-run看全部受影响文件对每个文件npx shadcnlatest add component --diff file对比上游与本地差异按 diff 逐文件决策无本地改动可直接覆盖有本地改动则分析后保留本地修改地合并上游更新用户明确说「全更新」时可用--overwrite但需先确认未获用户明确同意绝不使用--overwrite也绝不绕过 CLI 手动抓取 GitHub 原始文件。值得补充的是独立shadcn diff命令在当前 CLI 中已标记为弃用见 diff.ts 的[DEPRECATED]说明其「拉取 registry 内容 → 经过 transform 管线import/RSC/CSS 变量/图标等变换→ 与本地文件做diffLines对比」的逻辑已并入add --diff与文档推荐的用法一致。小结shadcn/ui 的定制体系可以用三层来概括变量层:root/.dark下的语义 Token OKLCH 取值 --radius派生刻度、工具层theme inline或tailwind.config.js把变量注册为 Tailwind 颜色、组件层variant → className 布局 → 源码加 variant → wrapper 组合的升级路径。配合apply/init的 Preset 命令完成整站换肤再配合add --dry-run --diff安全跟进上游更新就构成了一个从「改一行变量」到「整项目主题迁移」的完整闭环。相关参考customization.md、styling.md、SKILL.md、globals.css、apply.ts。【免费下载链接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.项目地址: https://gitcode.com/GitHub_Trending/ui/ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考