Skip to content

ever-co/ever-works / .agents/skills/tailwind-v4-shadcn

tailwind-v4-shadcn

Verified

Production-tested setup for Tailwind CSS v4 with shadcn/ui, Vite, and React. Use when: initializing React projects with Tailwind v4, setting up shadcn/ui, implementing dark mode, debugging CSS variable issues, fixing theme switching, migrating from Tailwind v3, or encountering color/theming problems. Covers: @theme inline pattern, CSS variable architecture, dark mode with ThemeProvider, component composition, vite.config setup, common v4 gotchas, and production-tested patterns. Keywords: Tailwind v4, shadcn/ui, @tailwindcss/vite, @theme inline, dark mode, CSS variables, hsl() wrapper, components.json, React theming, theme switching, colors not working, variables broken, theme not applying, @plugin directive, typography plugin, forms plugin, prose class, @tailwindcss/typography, @tailwindcss/forms

references/advanced-usage.md

View on GitHub
# Advanced Usage Patterns

**Purpose**: Advanced customization and component patterns for experienced Tailwind v4 + shadcn/ui developers
**When to Load**: User asks for custom colors beyond defaults, advanced component patterns, composition best practices, or component customization

---

## Custom Colors

Add new semantic colors beyond the default palette:

```css
:root {
	--brand: hsl(280 65% 60%);
	--brand-foreground: hsl(0 0% 100%);
}

.dark {
	--brand: hsl(280 75% 70%);
	--brand-foreground: hsl(280 20% 10%);
}

@theme inline {
	--color-brand: var(--brand);
	--color-brand-foreground: var(--brand-foreground);
}
```

**Usage:**

```tsx
<div className="bg-brand text-brand-foreground">Branded Component</div>
```

**Key Pattern**: Define CSS variable in `:root`/`.dark`, then reference in `@theme inline` with `--color-` prefix.

---

## Migration from Tailwind v3

For complete v3 → v4 migration steps, see `references/migration-guide.md`.

**Quick Summary**:

- Remove `tailwind.config.js` (v4 uses CSS configuration)
- Convert hardcoded colors to CSS variables
- Update plugin syntax: `require('tailwindcss/plugin')(plugin)` in v3 config → `@plugin "plugin-name"` in CSS
- Change Vite plugin: `require('tailwindcss')` or `import tailwindcss from 'tailwindcss'` in v3 → `import tailwindcss from '@tailwindcss/vite'` in v4

---

## Component Best Practices

### 1. Always Use Semantic Tokens

**✅ CORRECT:**

```tsx
<Button variant="destructive">Delete</Button>
```

**❌ WRONG:**

```tsx
<Button className="bg-red-600">Delete</Button>
```

**Why**: Semantic tokens (`destructive`, `primary`, `secondary`) adapt to theme changes. Hardcoded colors break dark mode and theme customization.

---

### 2. Use `cn()` for Conditional Styling

**Import:**

```tsx
import { cn } from '@/lib/utils';
```

**Usage:**

```tsx
<div className={cn('base-class', isActive && 'active-class', hasError && 'error-class')} />
```

**What `cn()` does**: Merges Tailwind classes intelligently (later classes override earlier ones).

---

### 3. Compose shadcn/ui Components

**Pattern:**

```tsx
<Dialog>
	<DialogTrigger asChild>
		<Button>Open</Button>
	</DialogTrigger>
	<DialogContent>
		<DialogHeader>
			<DialogTitle>Title</DialogTitle>
		</DialogHeader>
	</DialogContent>
</Dialog>
```

**Key Concept**: Use composition (wrapping components) rather than customization (passing props).

---

## Advanced Patterns

### Conditional Theme Variables

Apply different variables based on state:

```tsx
<div
	className={cn(
		'rounded-lg p-4',
		variant === 'success' && 'bg-success text-success-foreground',
		variant === 'error' && 'bg-destructive text-destructive-foreground'
	)}
/>
```

### Custom Radius Tokens

Add semantic border radius:

```css
@theme inline {
	--radius-sm: 0.25rem;
	--radius-md: 0.5rem;
	--radius-lg: 1rem;
}
```

Usage: `className="rounded-[var(--radius-lg)]"`

### Component Variants Pattern

Use `cva()` from `class-variance-authority` for complex variants:

```tsx
import { cva } from 'class-variance-authority';

const buttonVariants = cva('inline-flex items-center justify-center rounded-md', {
	variants: {
		variant: {
			default: 'bg-primary text-primary-foreground',
			destructive: 'bg-destructive text-destructive-foreground'
		},
		size: {
			default: 'h-10 px-4 py-2',
			sm: 'h-9 px-3',
			lg: 'h-11 px-8'
		}
	},
	defaultVariants: {
		variant: 'default',
		size: 'default'
	}
});
```

---

## Official Resources

- Tailwind v4 Docs: https://tailwindcss.com/blog/tailwindcss-v4-beta
- shadcn/ui: https://ui.shadcn.com
- class-variance-authority: https://cva.style/docs
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall