shadcn-theming

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

shadcn Theming

shadcn 主题配置

Agent Workflow (MANDATORY)

Agent 工作流程（强制要求）

Before theming work, use

TeamCreate

fuse-ai-pilot:explore-codebase - Find existing theme tokens
fuse-ai-pilot:research-expert - Verify OKLCH patterns via Context7

After: Run fuse-ai-pilot:sniper for validation.

在进行主题配置工作前，请使用

TeamCreate

：

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

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

Overview

概述

Feature	Description
CSS Variables	`--background` , `--foreground` , `--primary`
OKLCH Colors	Wide-gamut P3 color space
Dark Mode	`.dark` class or `prefers-color-scheme`
Tailwind v4	`@theme` directive integration

特性	描述
CSS 变量	`--background` 、 `--foreground` 、 `--primary`
OKLCH 色彩	广色域 P3 色彩空间
暗色模式	`.dark` 类或 `prefers-color-scheme` 媒体查询
Tailwind v4	集成 `@theme` 指令

Critical Rules

核心规则

ALWAYS use OKLCH color space for all tokens
ALWAYS define dark mode overrides for every token
NEVER hard-code hex or rgb in components
USE @theme directive for Tailwind v4 integration
MAP semantic tokens to primitive OKLCH values

始终使用 OKLCH 色彩空间定义所有令牌
始终为每个令牌定义 暗色模式覆盖样式
绝对不要在组件中硬编码 十六进制或 RGB 颜色值
使用 @theme 指令 实现 Tailwind v4 集成
将语义化令牌映射 到基础 OKLCH 颜色值

Architecture

架构

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

-> See theme-setup.md for complete theme

app/
├── globals.css         # :root 和 .dark 下的令牌定义
└── tailwind.config.ts  # 可选（v3）或用于 @theme 指令（v4）

-> 查看 theme-setup.md 获取完整主题配置

Token Hierarchy

令牌层级

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

组件层: --card, --card-foreground, --button-*
    ↑
语义层: --primary, --secondary, --accent, --muted
    ↑
基础层: oklch(55% 0.20 260), oklch(98% 0.01 260)

Validation Checklist

验证检查清单

[ ] 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
[ ] No hard-coded hex in components

[ ] 在 :root 中定义了 CSS 变量
[ ] 在 .dark 中配置了暗色模式覆盖样式
[ ] 使用了 OKLCH 色彩空间
[ ] 配置了图表变量（--chart-1 至 --chart-5）
[ ] 按需配置了侧边栏变量
[ ] 组件中无硬编码的十六进制颜色值

Best Practices

最佳实践

DO

建议做法

Use OKLCH for all colors
Define semantic tokens mapped to primitives
Provide dark mode overrides for all tokens
Use
```
@theme
```
for Tailwind v4 integration

所有色彩均使用 OKLCH
定义映射到基础颜色的语义化令牌
为所有令牌提供暗色模式覆盖样式
使用
```
@theme
```
指令实现 Tailwind v4 集成

DON'T

禁止做法

Hard-code hex or rgb values
Skip dark mode definitions
Mix color spaces (hex + oklch)
Define tokens only in Tailwind config

硬编码十六进制或 RGB 颜色值
省略暗色模式定义
混合使用不同色彩空间（如十六进制 + OKLCH）
仅在 Tailwind 配置文件中定义令牌

Reference Guide

参考指南

Concepts

核心概念

Topic	Reference	When to Consult
Theming Guide	theming-guide.md	CSS variables and OKLCH setup

主题	参考文档	适用场景
主题配置指南	theming-guide.md	CSS 变量与 OKLCH 配置

Templates

模板

Template	When to Use
theme-setup.md	Complete theme configuration

模板	适用场景
theme-setup.md	完整主题配置