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/migration-guide.md

View on GitHub
# Migration Guide: Hardcoded Colors → CSS Variables

## Overview

This guide helps you migrate from hardcoded Tailwind colors (`bg-blue-600`) to semantic CSS variables (`bg-primary`).

**Benefits:**

- Automatic dark mode support
- Consistent color usage
- Single source of truth
- Easy theme customization
- Better accessibility

---

## Semantic Color Mapping

| Hardcoded Color                 | CSS Variable                          | Use Case                                |
| ------------------------------- | ------------------------------------- | --------------------------------------- |
| `bg-red-*` / `text-red-*`       | `bg-destructive` / `text-destructive` | Critical issues, errors, delete actions |
| `bg-green-*` / `text-green-*`   | `bg-success` / `text-success`         | Success states, positive metrics        |
| `bg-yellow-*` / `text-yellow-*` | `bg-warning` / `text-warning`         | Warnings, moderate issues               |
| `bg-blue-*` / `text-blue-*`     | `bg-info` or `bg-primary`             | Info boxes, primary actions             |
| `bg-gray-*` / `text-gray-*`     | `bg-muted` / `text-muted-foreground`  | Backgrounds, secondary text             |
| `bg-purple-*`                   | `bg-info`                             | Remove - use blue instead               |
| `bg-orange-*`                   | `bg-warning`                          | Remove - use yellow instead             |
| `bg-emerald-*`                  | `bg-success`                          | Remove - use green instead              |

---

## Migration Patterns

### Pattern 1: Solid Backgrounds

❌ **Before:**

```tsx
<div className="bg-blue-50 dark:bg-blue-950/20 text-blue-700 dark:text-blue-300">
```

✅ **After:**

```tsx
<div className="bg-info/10 text-info">
```

**Note:** `/10` creates 10% opacity

---

### Pattern 2: Borders

❌ **Before:**

```tsx
<div className="border-2 border-green-200 dark:border-green-800">
```

✅ **After:**

```tsx
<div className="border-2 border-success/30">
```

---

### Pattern 3: Text Colors

❌ **Before:**

```tsx
<span className="text-red-600 dark:text-red-400">
```

✅ **After:**

```tsx
<span className="text-destructive">
```

---

### Pattern 4: Icons

❌ **Before:**

```tsx
<AlertCircle className="text-yellow-500" />
```

✅ **After:**

```tsx
<AlertCircle className="text-warning" />
```

---

### Pattern 5: Gradients

❌ **Before:**

```tsx
<div className="bg-gradient-to-r from-green-50 to-emerald-50 dark:from-green-950/20 dark:to-emerald-950/20">
```

✅ **After:**

```tsx
<div className="bg-gradient-to-r from-success/10 to-success/20">
```

---

## Step-by-Step Migration

### Step 1: Add Semantic Colors to CSS

```css
/* src/index.css */
:root {
	/* Add these if not already present */
	--destructive: hsl(0 84.2% 60.2%);
	--destructive-foreground: hsl(210 40% 98%);
	--success: hsl(142.1 76.2% 36.3%);
	--success-foreground: hsl(210 40% 98%);
	--warning: hsl(38 92% 50%);
	--warning-foreground: hsl(222.2 47.4% 11.2%);
	--info: hsl(221.2 83.2% 53.3%);
	--info-foreground: hsl(210 40% 98%);
}

.dark {
	--destructive: hsl(0 62.8% 30.6%);
	--destructive-foreground: hsl(210 40% 98%);
	--success: hsl(142.1 70.6% 45.3%);
	--success-foreground: hsl(222.2 47.4% 11.2%);
	--warning: hsl(38 92% 55%);
	--warning-foreground: hsl(222.2 47.4% 11.2%);
	--info: hsl(217.2 91.2% 59.8%);
	--info-foreground: hsl(222.2 47.4% 11.2%);
}

@theme inline {
	--color-destructive: var(--destructive);
	--color-destructive-foreground: var(--destructive-foreground);
	--color-success: var(--success);
	--color-success-foreground: var(--success-foreground);
	--color-warning: var(--warning);
	--color-warning-foreground: var(--warning-foreground);
	--color-info: var(--info);
	--color-info-foreground: var(--info-foreground);
}
```

### Step 2: Find Hardcoded Colors

```bash
# Search for background colors
grep -r "bg-\(red\|yellow\|blue\|green\|purple\|orange\|pink\|emerald\)-[0-9]" src/

# Search for text colors
grep -r "text-\(red\|yellow\|blue\|green\|purple\|orange\|pink\|emerald\)-[0-9]" src/

# Search for border colors
grep -r "border-\(red\|yellow\|blue\|green\|purple\|orange\|pink\|emerald\)-[0-9]" src/
```

### Step 3: Replace Component by Component

Start with high-impact components:

1. Buttons
2. Badges
3. Alert boxes
4. Status indicators
5. Cards

### Step 4: Test Both Themes

After each component:

- [ ] Check light mode appearance
- [ ] Check dark mode appearance
- [ ] Verify text contrast
- [ ] Test hover/active states

---

## Example: Badge Component

❌ **Before:**

```tsx
const severityConfig = {
	critical: {
		color: 'text-red-500',
		bg: 'bg-red-500/10',
		border: 'border-red-500/20'
	},
	warning: {
		color: 'text-yellow-500',
		bg: 'bg-yellow-500/10',
		border: 'border-yellow-500/20'
	},
	info: {
		color: 'text-blue-500',
		bg: 'bg-blue-500/10',
		border: 'border-blue-500/20'
	}
};
```

✅ **After:**

```tsx
const severityConfig = {
	critical: {
		color: 'text-destructive',
		bg: 'bg-destructive/10',
		border: 'border-destructive/20'
	},
	warning: {
		color: 'text-warning',
		bg: 'bg-warning/10',
		border: 'border-warning/20'
	},
	info: {
		color: 'text-info',
		bg: 'bg-info/10',
		border: 'border-info/20'
	}
};
```

---

## Testing Checklist

After migration:

- [ ] All severity levels (critical/warning/info) visually distinct
- [ ] Text has proper contrast in both light and dark modes
- [ ] No hardcoded color classes remain
- [ ] Hover states work correctly
- [ ] Gradients render smoothly
- [ ] Icons are visible and colored correctly
- [ ] Borders are visible
- [ ] No visual regressions

---

## Verification Commands

```bash
# Should return 0 results when migration complete
grep -r "text-red-[0-9]" src/components/
grep -r "bg-blue-[0-9]" src/components/
grep -r "border-green-[0-9]" src/components/

# Verify semantic colors are used
grep -r "bg-destructive" src/components/
grep -r "text-success" src/components/
```

---

## Performance Impact

**Before:** Every component has `dark:` variants

```tsx
<div className="bg-blue-50 dark:bg-blue-950/20 text-blue-700 dark:text-blue-300 border-blue-200 dark:border-blue-800">
```

**After:** Single class, CSS handles switching

```tsx
<div className="bg-info/10 text-info border-info/30">
```

**Result:**

- 60% fewer CSS classes in markup
- Smaller HTML payload
- Faster rendering
- Easier to maintain

---

## Common Pitfalls

### 1. Forgetting to Map in @theme inline

Variables defined in `:root` but not mapped → utilities don't exist

### 2. Wrong Opacity Syntax

❌ `bg-success-10` (doesn't work)
✅ `bg-success/10` (correct)

### 3. Mixing Approaches

Don't mix hardcoded and semantic in same component - choose one approach.

### 4. Not Testing Dark Mode

Always test both themes during migration.

---

## Rollback Plan

If migration causes issues:

1. Keep original components in git history
2. Use feature flags to toggle new theme
3. Test with subset of users first
4. Have monitoring for visual regressions

---

## Further Customization

After migration, you can easily:

- Add new semantic colors
- Create theme variants (high contrast, etc.)
- Support multiple brand themes
- Implement user-selectable color schemes

All by editing CSS variables - no component changes needed!
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