mcpField
S
shadcn-theming

shadcn-theming

github.com/fusengine设计与 UI3456 次安装2 周前更新
代码仓库

关于 shadcn-theming

为 shadcn/ui 项目提供主题设计指导，涵盖 CSS 令牌、OKLCH 颜色和深浅模式。内容包括 Tailwind v4 集成、预设配置及主题校验，并适用于 Base UI、Radix 和 React Aria 基础。

主要功能

  1. 01CSS 令牌层级
  2. 02OKLCH 颜色令牌
  3. 03深浅模式配置
  4. 04Tailwind v4 @theme 集成
  5. 05预设与基础色工作流
  6. 06主题校验清单

适用场景

  1. 01配置新的 shadcn/ui 主题
  2. 02应用或切换项目预设
  3. 03添加带深色模式覆盖的令牌
  4. 04检查主题中的硬编码颜色

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/fusengine/agents --skill shadcn-theming

安装后在 Claude Code 中输入/shadcn-theming确认已加载。

附带文件references/templates/theme-setup.mdreferences/theming-guide.md

详细介绍

shadcn/ui 的设计令牌和主题设置：CSS 自定义属性（`--background`、`--primary` 等）、OKLCH 广色域颜色、通过 `.dark` 类或 `prefers-color-scheme` 实现的深色／浅色模式，以及 Tailwind v4 `@theme` 指令集成——适用于 Base UI、Radix 和 React Aria 基础。还涵盖 7 种基础颜色、预设（`init --preset`、`apply --preset --only theme,font`）、`migrate base-color`、`shadcn/tailwind.css`／`eject`，以及用于渲染 Markdown 的 shadcn/typeset。

介绍令牌层级（组件 → 语义 → 原始 OKLCH 值）和验证清单（深色模式覆盖、图表／侧边栏变量、不使用硬编码十六进制值）。

shadcn 主题设置

Agent 工作流（强制）

开始主题设置工作前，并行启动 Agent，每个调用一个 Agent，并指定 name：

  1. fuse-ai-pilot:explore-codebase - 查找现有主题令牌
  2. fuse-ai-pilot:research-expert - 通过 Context7 验证 OKLCH 模式

完成后：运行 fuse-ai-pilot:sniper 进行验证。

概览

功能描述
CSS 变量--background、--foreground、--primary
OKLCH 颜色广色域 P3 色彩空间
深色模式.dark 类或 prefers-color-scheme
Tailwind v4@theme inline 指令集成 + @custom-variant dark
基础颜色tailwind.baseColor：neutral、stone、zinc、mauve、olive、mist、taupe（在初始化时设置；使用 migrate base-color --to <c> 切换）
预设将样式、基础颜色、主题、图表颜色、图标、字体、圆角、菜单颜色／强调色打包成简码（基于 ui.shadcn.com/create 构建）
圆角比例--radius 通过 @theme inline 驱动 --radius-sm ... --radius-4xl

主题 CLI（已在 shadcn 4.21.0 上验证）

{runner} shadcn@latest init --preset <code>                 # new project from a preset
{runner} shadcn@latest apply --preset <code>                # switch preset: reinstalls components, keeps base + RTL
{runner} shadcn@latest apply --preset <code> --only theme   # or --only font, --only theme,font
{runner} shadcn@latest preset decode <code>                 # also: resolve (current project), url, open
{runner} shadcn@latest migrate base-color --to zinc --yes   # rewrite theme CSS vars + baseColor
{runner} shadcn@latest init --no-css-variables              # inline utilities instead of tokens (install-time only)
{runner} shadcn@latest init --pointer                       # cursor: pointer on buttons (not part of presets)
{runner} shadcn@latest eject                                # inline shadcn/tailwind.css, drop the shadcn dependency

关键规则

  1. 始终使用 OKLCH 色彩空间定义所有令牌
  2. 始终为每个令牌定义深色模式覆盖
  3. 绝不在组件中硬编码十六进制或 rgb 值
  4. 使用 @theme inline 指令集成 Tailwind v4
  5. 将语义令牌映射到原始 OKLCH 值

架构

app/
├── globals.css         # :root + .dark token definitions
└── tailwind.config.ts  # Optional (v3) or @theme (v4)

-> 完整主题请参见 theme-setup.md

令牌层级

Component: --card, --card-foreground, --button-*
    ↑
Semantic: --primary, --secondary, --accent, --muted
    ↑
Primitive: oklch(55% 0.20 260), oklch(98% 0.01 260)

验证清单

[ ] CSS variables defined in :root
[ ] Dark mode overrides in .dark
[ ] OKLCH color space used
[ ] Chart variables (--chart-1 to --chart-5)
[ ] Sidebar variables if applicable
[ ] New tokens defined in :root + .dark AND exposed in @theme inline (--color-*)
[ ] No hard-coded hex in components

最佳实践

应做
  • 所有颜色均使用 OKLCH
  • 定义映射到原始值的语义令牌
  • 为所有令牌提供深色模式覆盖
  • 使用 @theme inline 集成 Tailwind v4
不应做
  • 硬编码十六进制或 rgb 值
  • 跳过深色模式定义
  • 混用色彩空间（十六进制 + oklch）
  • 只在 Tailwind 配置中定义令牌

参考指南

概念
主题参考资料查阅时机
主题设置指南theming-guide.mdCSS 变量、OKLCH、基础颜色、新令牌、typeset
模板
模板使用时机
theme-setup.md完整主题配置

评论

支持 Markdown