shadcn-customization

name	shadcn-customization
description	Shadcn/ui theming and component customization — CSS variables, OKLCH colors, dark mode, variants, wrappers. Load for any ticket involving colors, theme, UI layout, or component styling.

Customization & Theming

Reference for theming and component customization. Components reference semantic CSS variable tokens change the variables to change every component. Read the relevant section, then check the Red Flags and Verification list.

When to Use

• Changing colors, theme, dark mode, or border radius.
• Adding a custom color token or a new component variant.
• Customizing or wrapping a shadcn/ui component.

For component architecture and where to import from, see Skill({skill: "frontend-dev"}).

---

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.

Variable	Purpose
--background / --foreground	Page background and default text
--card / --card-foreground	Card surfaces
--primary / --primary-foreground	Primary buttons and actions
--secondary / --secondary-foreground	Secondary actions
--muted / --muted-foreground	Muted/disabled states
--accent / --accent-foreground	Hover and accent states
--destructive / --destructive-foreground	Error and destructive actions
--border	Default border color
--input	Form input borders
--ring	Focus ring color
--chart-1 through --chart-5	Chart/data visualization
--sidebar-*	Sidebar-specific colors
--surface / --surface-foreground	Secondary surface

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. Atomic CRM wires this through its own ThemeProvider at src/components/admin/theme-provider.tsx, which is already mounted from src/components/admin/admin.tsx. To customize the palette, pass lightTheme / darkTheme props to the <CRM> component (see src/App.tsx).

---

Changing the Theme

# Apply a preset from ui.shadcn.com.
npx shadcn@latest apply --preset a2r6bw

# Positional shorthand also works.
npx shadcn@latest apply a2r6bw

# Switch to a named preset, 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);
}

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

// 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)).

---

Customizing Components

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.tsx
warning: "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
npx shadcn@latest add button --dry-run        # see all affected files
npx shadcn@latest add button --diff button.tsx # diff for a specific file

---

Red Flags

• A hardcoded hex/rgb color in a component instead of a semantic token (bg-primary, text-muted-foreground).
• A new CSS file created for custom colors instead of adding them to the global CSS file.
• A custom color used without registering it under @theme inline for Tailwind v4.
• Editing component source for a one-off when a variant or className would do.
• Palette changes wired anywhere but the lightTheme/darkTheme props on <CRM>.
• A token defined in :root but not in .dark (or vice versa) — one mode is left broken.

Verification

• Colors use semantic tokens, never hardcoded values.
• Custom colors live in the global CSS file and are registered under @theme inline.
• Every new token is defined in both :root and .dark.
• Customization uses the lowest-effort approach that works (variant → className → new variant → wrapper).
• Palette changes go through lightTheme/darkTheme on <CRM>.