tailwind-theme-builder

1# Tailwind Theme Builder
2 
3Set up a fully themed Tailwind v4 + shadcn/ui project with dark mode. Produces configured CSS, theme provider, and working component library.
4 
5## Architecture: The Four-Step Pattern
6 
7Tailwind v4 requires a specific architecture for CSS variable-based theming. This pattern is **mandatory** -- skipping or modifying steps breaks the theme.
8 
9### How It Works
10 
11```
12CSS Variable Definition --> @theme inline Mapping --> Tailwind Utility Class
13--background           --> --color-background     --> bg-background
14(with hsl() wrapper)      (references variable)     (generated class)
15```
16 
17Dark mode switching:
18```
19ThemeProvider toggles .dark class on <html>
20  --> CSS variables update automatically (.dark overrides :root)
21  --> Tailwind utilities reference updated variables
22  --> UI updates without re-render
23```
24 
25### Best Practices
26 
27- **Semantic names:** Use `--primary` not `--blue-500`
28- **Foreground pairing:** Every background colour needs a foreground (`--primary` + `--primary-foreground`)
29- **WCAG contrast:** Normal text 4.5:1, large text 3:1, UI components 3:1
30- **Chart colours:** Use separate variables with `@theme inline` mapping, reference via `var(--chart-1)` in style props
31 
32---
33 
34## Workflow
35 
36### Step 1: Install Dependencies
37 
38```bash
39pnpm add tailwindcss @tailwindcss/vite
40pnpm add -D @types/node tw-animate-css
41pnpm dlx shadcn@latest init
42 
43# Delete v3 config if it exists
44rm -f tailwind.config.ts
45```
46 
47### Step 2: Configure Vite
48…