1# Customization & Theming
2 
3Components reference semantic CSS variable tokens. Change the variables to change every component.
4 
5## Contents
6 
7- How it works (CSS variables → Tailwind utilities → components)
8- Color variables and OKLCH format
9- Dark mode setup
10- Changing the theme (presets, CSS variables)
11- Adding custom colors (Tailwind v3 and v4)
12- Border radius
13- Customizing components (variants, className, wrappers)
14- Checking for updates
15 
16---
17 
18## How It Works
19 
201. CSS variables defined in `:root` (light) and `.dark` (dark mode).
212. Tailwind maps them to utilities: `bg-primary`, `text-muted-foreground`, etc.
223. Components use these utilities — changing a variable changes all components that reference it.
23 
24---
25 
26## Color Variables
27 
28Every color follows the `name` / `name-foreground` convention. The base variable is for backgrounds, `-foreground` is for text/icons on that background.
29 
30| Variable                                     | Purpose                          |
31| -------------------------------------------- | -------------------------------- |
32| `--background` / `--foreground`              | Page background and default text |
33| `--card` / `--card-foreground`               | Card surfaces                    |
34| `--primary` / `--primary-foreground`         | Primary buttons and actions      |
35| `--secondary` / `--secondary-foreground`     | Secondary actions                |
36| `--muted` / `--muted-foreground`             | Muted/disabled states            |
37| `--accent` / `--accent-foreground`           | Hover and accent states          |
38| `--destructive` / `--destructive-foreground` | Error and destructive actions    |
39| `--border`                                   | Default border color             |
40| `--input`                                    | Form input borders               |
41| `--ring`                                     | Focus ring color                 |
42| `--chart-1` through `--chart-5`              | Chart/data visualization         |
43| `--sidebar-*`                                | Sidebar-specific colors          |
44| `--surface` / `--surface-foreground`         | Secondary surface                |
45 
46Colors use OKLCH: `--primary: oklch(0.205 0 0)` where values are lightness (0–1), chroma (0 = gray), and hue (0–360).
47 
48---
49 
50## Dark Mode
51 
52Class-based toggle via `.dark` on the root element. In Next.js, use `next-themes`:
53 
54```tsx
55import { ThemeProvider } from "next-themes"
56 
57<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
58  {children}
59</ThemeProvider>
60```
61 
62---
63 
64## Changing the Theme
65 
66```bash
67# Apply a preset code from ui.shadcn.com.
68npx shadcn@latest apply --preset a2r6bw
69 
70# Positional shorthand also works.
71npx shadcn@latest apply a2r6bw
72 
73# Switch to a named preset and overwrite existing components.
74npx shadcn@latest apply --preset nova
75 
76# Preserve existing components instead.
77npx shadcn@latest init --preset nova --force --no-reinstall
78 
79# Use a custom theme URL.
80npx shadcn@latest apply --preset "https://ui.shadcn.com/init?base=radix&style=nova&theme=blue&..."
81```
82 
83Or edit CSS variables directly in `globals.css`.
84 
85---
86 
87## Adding Custom Colors
88 
89Add variables to the file at `tailwindCssFile` from `npx shadcn@latest info` (typically `globals.css`). Never create a new CSS file for this.
90 
91```css
92/* 1. Define in the global CSS file. */
93:root {
94  --warning: oklch(0.84 0.16 84);
95  --warning-foreground: oklch(0.28 0.07 46);
96}
97.dark {
98  --warning: oklch(0.41 0.11 46);
99  --warning-foreground: oklch(0.99 0.02 95);
100}
101```
102 
103```css
104/* 2a. Register with Tailwind v4 (@theme inline). */
105@theme inline {
106  --color-warning: var(--warning);
107  --color-warning-foreground: var(--warning-foreground);
108}
109```
110 
111When `tailwindVersion` is `"v3"` (check via `npx shadcn@latest info`), register in `tailwind.config.js` instead:
112 
113```js
114// 2b. Register with Tailwind v3 (tailwind.config.js).
115module.exports = {
116  theme: {
117    extend: {
118      colors: {
119        warning: "oklch(var(--warning) / <alpha-value>)",
120        "warning-foreground":
121          "oklch(var(--warning-foreground) / <alpha-value>)",
122      },
123    },
124  },
125}
126```
127 
128```tsx
129// 3. Use in components.
130<div className="bg-warning text-warning-foreground">Warning</div>
131```
132 
133---
134 
135## Border Radius
136 
137`--radius` controls border radius globally. Components derive values from it (`rounded-lg` = `var(--radius)`, `rounded-md` = `calc(var(--radius) - 2px)`).
138 
139---
140 
141## Customizing Components
142 
143See also: [rules/styling.md](./rules/styling.md) for Incorrect/Correct examples.
144 
145Prefer these approaches in order:
146 
147### 1. Built-in variants
148 
149```tsx
150<Button variant="outline" size="sm">
151  Click
152</Button>
153```
154 
155### 2. Tailwind classes via `className`
156 
157```tsx
158<Card className="mx-auto max-w-md">...</Card>
159```
160 
161### 3. Add a new variant
162 
163Edit the component source to add a variant via `cva`:
164 
165```tsx
166// components/ui/button.tsx
167warning: "bg-warning text-warning-foreground hover:bg-warning/90",
168```
169 
170### 4. Wrapper components
171 
172Compose shadcn/ui primitives into higher-level components:
173 
174```tsx
175export function ConfirmDialog({ title, description, onConfirm, children }) {
176  return (
177    <AlertDialog>
178      <AlertDialogTrigger asChild>{children}</AlertDialogTrigger>
179      <AlertDialogContent>
180        <AlertDialogHeader>
181          <AlertDialogTitle>{title}</AlertDialogTitle>
182          <AlertDialogDescription>{description}</AlertDialogDescription>
183        </AlertDialogHeader>
184        <AlertDialogFooter>
185          <AlertDialogCancel>Cancel</AlertDialogCancel>
186          <AlertDialogAction onClick={onConfirm}>Confirm</AlertDialogAction>
187        </AlertDialogFooter>
188      </AlertDialogContent>
189    </AlertDialog>
190  )
191}
192```
193 
194---
195 
196## Checking for Updates
197 
198```bash
199npx shadcn@latest add button --diff
200```
201 
202To preview exactly what would change before updating, use `--dry-run` and `--diff`:
203 
204```bash
205npx shadcn@latest add button --dry-run        # see all affected files
206npx shadcn@latest add button --diff button.tsx # see the diff for a specific file
207```
208 
209See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full smart merge workflow.
210