# Tailwind Theme Builder

Set up Tailwind v4 + shadcn/ui themed UI with dark mode.

- Repository: https://github.com/jezweb/claude-skills (1094 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-09
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add jezweb/claude-skills --skill tailwind-theme-builder -g -a claude-code -y`
Codex: `npx skills add jezweb/claude-skills --skill tailwind-theme-builder -g -a codex -y`
Cursor: `npx skills add jezweb/claude-skills --skill tailwind-theme-builder -g -a cursor -y`
Gemini CLI: `npx skills add jezweb/claude-skills --skill tailwind-theme-builder -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add jezweb/claude-skills`

## Description

Set up Tailwind v4 + shadcn/ui themed UI with dark mode. Install deps, configure CSS variables via @theme inline, wire dark mode toggle, verify. Use whenever the user mentions Tailwind v4, setting up Tailwind theming, shadcn/ui colours, dark mode, or troubleshooting colours not working, tw-animate-css errors, @theme inline conflicts, @apply breaking after upgrade, or v3 → v4 migration issues.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Tailwind Theme Builder

Set up a fully themed Tailwind v4 + shadcn/ui project with dark mode. Produces configured CSS, theme provider, and working component library.

## Architecture: The Four-Step Pattern

Tailwind v4 requires a specific architecture for CSS variable-based theming. This pattern is **mandatory** -- skipping or modifying steps breaks the theme.

### How It Works

```
CSS Variable Definition --> @theme inline Mapping --> Tailwind Utility Class
--background           --> --color-background     --> bg-background
(with hsl() wrapper)      (references variable)     (generated class)
```

Dark mode switching:
```
ThemeProvider toggles .dark class on <html>
  --> CSS variables update automatically (.dark overrides :root)
  --> Tailwind utilities reference updated variables
  --> UI updates without re-render
```

### Best Practices

- **Semantic names:** Use `--primary` not `--blue-500`
- **Foreground pairing:** Every background colour needs a foreground (`--primary` + `--primary-foreground`)
- **WCAG contrast:** Normal text 4.5:1, large text 3:1, UI components 3:1
- **Chart colours:** Use separate variables with `@theme inline` mapping, reference via `var(--chart-1)` in style props

---

## Workflow

### Step 1: Install Dependencies

```bash
pnpm add tailwindcss @tailwindcss/vite
pnpm add -D @types/node tw-animate-css
pnpm dlx shadcn@latest init

# Delete v3 config if it exists
rm -f tailwind.config.ts
```

### Step 2: Configure Vite

Copy `assets/vite.config.ts` or add the Tailwind plugin:

```typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: { alias: { '@': path.resolve(__dirname, './src') } }
})
```

### Step 3: Four-Step CSS Architecture (Mandatory)

This exact order is required. Skipping steps breaks the theme.

**src/index.css:**

The rest: https://github.com/jezweb/claude-skills/blob/HEAD/plugins/frontend/skills/tailwind-theme-builder/SKILL.md