shadcn-impl-theming-custom

name	shadcn-impl-theming-custom
description	Use when building or customizing a theme in a shadcn ui project, wiring the dark mode toggle, replacing the default primary color with a brand color, copying the output of the ui.shadcn.com themes builder into globals.css, or overriding the styling of one specific component instance without touching the global tokens. This is the end-to-end workflow recipe : the token catalog, oklch versus HSL format split, and v3 versus v4 wiring rules live in shadcn-core-theming. Prevents the flash-of-unstyled-content on first paint that comes from a missing suppressHydrationWarning, the silent "bg-primary did not change" symptom that comes from editing tokens without re-running the dev server, the two-ThemeProvider double-mount that breaks the toggle, the next-themes attribute mismatch that disables Tailwind's dark variants, and the brand-color contrast trap that ships an inaccessible palette. Covers the three-step theme-builder workflow (pick base style and radius, pick primary, copy CSS), the Tailwind v3 globals.css plus tailwind.config.js paste-target, the Tailwind v4 single-file globals.css paste-target with the @theme inline mapping, the Next.js ThemeProvider mount on app/layout.tsx with the four required props, the Vite custom Context ThemeProvider mount on main.tsx, the ModeToggle component with light/dark/system items, the brand-color override pattern keeping the foreground pair in sync, the custom palette build path with WCAG-AA verification, and the per-component override via the data-slot attribute that ships on every v4 primitive. Keywords: custom theme shadcn, brand theme, brand color shadcn, dark mode toggle, dark mode shadcn, next-themes, theme provider, ThemeProvider, useTheme, mode-toggle component, ModeToggle, theme builder, ui.shadcn.com themes, how do I customize colors, how do I change the primary color, how do I add dark mode, theme flash unstyled content, FOUC, flash of unstyled content, hydration mismatch theme, suppressHydrationWarning, shadcn brand color, custom palette, per-component override shadcn, data-slot, data-slot card, oklch theme, HSL theme, paste theme CSS, globals.css theme, replace primary color, override token shadcn, ThemeProvider attribute class, system theme preference, light dark system toggle, useTheme hook, setTheme function, dark variant not working, my theme did not change, theme not applying, lucide Sun Moon icons toggle, DropdownMenu mode toggle, double ThemeProvider nested provider error.
license	MIT
compatibility	Designed for Claude Code. Requires shadcn ui evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

shadcn ui : Theming Custom (Workflow Recipe)

End-to-end recipe for building, pasting, and wiring a custom theme. This skill is the workflow ; the token mental model (oklch versus HSL, v3 versus v4 wiring, full token catalog, decision trees) lives in shadcn-core-theming. ALWAYS read that skill first when in doubt about a token format or wiring location.

Quick Reference : The three-step happy path

The shortest path from "we want a custom theme" to a working dark-mode-toggling app :

1. Pick : open https://ui.shadcn.com/themes, pick a base style (default, new-york, sera, luma), pick a radius (0.0rem, 0.25rem, 0.5rem, 0.75rem, 1.0rem), pick a primary color (Zinc, Slate, Stone, Gray, Neutral, Red, Rose, Orange, Green, Blue, Yellow, Violet).
2. Copy : click "Copy code". The builder emits a single CSS block containing :root { ... } and .dark { ... } blocks, formatted for the project's Tailwind generation (oklch for v4, HSL space-separated for v3).
3. Paste : open app/globals.css (Next.js) or src/index.css (Vite). Replace the existing :root { ... } and .dark { ... } blocks ONLY. Keep the @import "tailwindcss"; line, the @custom-variant dark line, the @theme inline { ... } block, and the @layer base { ... } block intact.

That is the ENTIRE happy path. If the project already has the ThemeProvider mounted, the new colors take effect on the next dev-server reload. If not, follow the framework-specific mount recipe below.

Five invariants

1. ALWAYS paste only the :root and .dark blocks from the theme builder ; NEVER paste the @theme inline mapping (it already lives in the project).
2. ALWAYS verify the builder output matches the project's Tailwind generation (oklch for v4, HSL space-separated for v3) BEFORE pasting. Wrong format = silent zero-style output.
3. ALWAYS mount exactly ONE ThemeProvider at the root layout. Nesting two providers (e.g. next-themes inside a custom Context) produces unpredictable toggle behavior.
4. ALWAYS pass to next-themes ; any other value (e.g. ) disables Tailwind's variant in shadcn projects because the selector targets a class, not an attribute.