Customization & Theming

Components reference semantic CSS variable tokens. Change the variables to change every component.

Contents

• How it works (CSS variables → Tailwind utilities → components)
• Color variables and OKLCH format
• Dark mode setup
• Changing the theme (presets, CSS variables)
• Adding custom colors (Tailwind v3 and v4)
• Border radius
• Customizing components (variants, className, wrappers)
• Checking for updates

How It Works

1. CSS variables defined in :root (light) and .dark (dark mode).
2. Tailwind maps them to utilities: bg-primary, text-muted-foreground, etc.
3. Components use these utilities — changing a variable changes all components that reference it.

Color Variables

Every color follows the name / name-foreground convention. The base variable is for backgrounds, -foreground is for text/icons on that background.

Colors use OKLCH: --primary: oklch(0.205 0 0) where values are lightness (0–1), chroma (0 = gray), and hue (0–360).

Dark Mode

Class-based toggle via .dark on the root element. In Next.js, use next-themes:

import { ThemeProvider } from "next-themes"
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>  {children}</ThemeProvider>

Changing the Theme

# Apply a preset code from ui.shadcn.com.npx shadcn@latest apply --preset a2r6bw
# Positional shorthand also works.npx shadcn@latest apply a2r6bw
# Switch to a named preset and overwrite existing components.npx shadcn@latest apply --preset nova
# Preserve existing components instead.npx shadcn@latest init --preset nova --force --no-reinstall
# Use a custom theme URL.npx shadcn@latest apply --preset "https://ui.shadcn.com/init?base=radix&style=nova&theme=blue&..."

Or edit CSS variables directly in globals.css.

Adding Custom Colors

Add variables to the file at tailwindCssFile from npx shadcn@latest info (typically globals.css). Never create a new CSS file for this.

/* 1. Define in the global CSS file. */: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);}

/* 2a. Register with Tailwind v4 (@theme inline). */@theme inline {  --color-warning: var(--warning);  --color-warning-foreground: var(--warning-foreground);}

When tailwindVersion is "v3" (check via npx shadcn@latest info), register in tailwind.config.js instead:

// 2b. Register with Tailwind v3 (tailwind.config.js).module.exports = {  theme: {    extend: {      colors: {        warning: "oklch(var(--warning) / <alpha-value>)",        "warning-foreground":          "oklch(var(--warning-foreground) / <alpha-value>)",      },    },  },}

// 3. Use in components.<div className="bg-warning text-warning-foreground">Warning</div>

Border Radius

--radius controls border radius globally. Components derive values from it (rounded-lg = var(--radius), rounded-md = calc(var(--radius) - 2px)).

When a brand spec defines its own radius scale, pin each step in @theme inline (--radius-sm … --radius-4xl) instead of deriving from --radius. See design-system.md.

Customizing Components

See also: rules/styling.md for Incorrect/Correct examples.

Prefer these approaches in order:

1. Built-in variants

<Button variant="outline" size="sm">  Click</Button>

2. Tailwind classes via className

<Card className="mx-auto max-w-md">...</Card>

3. Add a new variant

Edit the component source to add a variant via cva:

// components/ui/button.tsxwarning: "bg-warning text-warning-foreground hover:bg-warning/90",

4. Wrapper components

Compose shadcn/ui primitives into higher-level components:

export function ConfirmDialog({ title, description, onConfirm, children }) {  return (    <AlertDialog>      <AlertDialogTrigger asChild>{children}</AlertDialogTrigger>      <AlertDialogContent>        <AlertDialogHeader>          <AlertDialogTitle>{title}</AlertDialogTitle>          <AlertDialogDescription>{description}</AlertDialogDescription>        </AlertDialogHeader>        <AlertDialogFooter>          <AlertDialogCancel>Cancel</AlertDialogCancel>          <AlertDialogAction onClick={onConfirm}>Confirm</AlertDialogAction>        </AlertDialogFooter>      </AlertDialogContent>    </AlertDialog>  )}

Checking for Updates

npx shadcn@latest add button --diff

To preview exactly what would change before updating, use --dry-run and --diff:

npx shadcn@latest add button --dry-run        # see all affected filesnpx shadcn@latest add button --diff button.tsx # see the diff for a specific file

See Updating Components in SKILL.md for the full smart merge workflow.