Initial commit

2025-11-30 08:25:32 +08:00
commit 6c7fa6696d
14 changed files with 2262 additions and 0 deletions
--- a/references/architecture.md
+++ b/references/architecture.md
@@ -0,0 +1,206 @@
+# Tailwind v4 + shadcn/ui Theming Architecture
+
+## The Four-Step Pattern
+
+Tailwind v4 requires a specific architecture for CSS variable-based theming. This pattern is **mandatory** - skipping or modifying steps will break your theme.
+
+### Step 1: Define CSS Variables at Root Level
+
+```css
+:root {
+  --background: hsl(0 0% 100%);
+  --foreground: hsl(222.2 84% 4.9%);
+  /* ... more colors */
+}
+
+.dark {
+  --background: hsl(222.2 84% 4.9%);
+  --foreground: hsl(210 40% 98%);
+  /* ... dark mode colors */
+}
+```
+
+**Critical Rules:**
+- ✅ Define at root level (NOT inside `@layer base`)
+- ✅ Use `hsl()` wrapper on all color values
+- ✅ Use `.dark` for dark mode overrides (NOT `.dark { @theme { } }`)
+- ❌ Never put `:root` or `.dark` inside `@layer base`
+
+### Step 2: Map Variables to Tailwind Utilities
+
+```css
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  /* ... map all CSS variables */
+}
+```
+
+**Why This Is Required:**
+- Tailwind v4 doesn't read `tailwind.config.ts` for colors
+- `@theme inline` generates utility classes (`bg-background`, `text-foreground`)
+- Without this, utilities like `bg-primary` won't exist
+
+### Step 3: Apply Base Styles
+
+```css
+@layer base {
+  body {
+    background-color: var(--background);  /* NO hsl() wrapper here */
+    color: var(--foreground);
+  }
+}
+```
+
+**Critical Rules:**
+- ✅ Reference variables directly: `var(--background)`
+- ❌ Never double-wrap: `hsl(var(--background))` (already has hsl)
+
+### Step 4: Result - Automatic Dark Mode
+
+With this architecture:
+- `<div className="bg-background text-foreground">` works automatically
+- No `dark:` variants needed in components
+- Theme switches via `.dark` class on `<html>`
+- Single source of truth for all colors
+
+---
+
+## Why This Architecture Works
+
+### Color Variable Flow
+
+```
+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)
+  ↓
+Tailwind utilities reference updated variables
+  ↓
+UI updates without re-render
+```
+
+---
+
+## Common Mistakes
+
+### ❌ Mistake 1: Variables Inside @layer base
+
+```css
+/* WRONG */
+@layer base {
+  :root {
+    --background: hsl(0 0% 100%);
+  }
+}
+```
+
+**Why It Fails:** Tailwind v4 strips CSS outside `@theme`/`@layer`, but `:root` must be at root level to persist.
+
+### ❌ Mistake 2: Using .dark { @theme { } }
+
+```css
+/* WRONG */
+@theme {
+  --color-primary: hsl(0 0% 0%);
+}
+
+.dark {
+  @theme {
+    --color-primary: hsl(0 0% 100%);
+  }
+}
+```
+
+**Why It Fails:** Tailwind v4 doesn't support nested `@theme` directives.
+
+### ❌ Mistake 3: Double hsl() Wrapping
+
+```css
+/* WRONG */
+@layer base {
+  body {
+    background-color: hsl(var(--background));
+  }
+}
+```
+
+**Why It Fails:** `--background` already contains `hsl()`, results in `hsl(hsl(...))`.
+
+### ❌ Mistake 4: Config-Based Colors
+
+```typescript
+// WRONG (tailwind.config.ts)
+export default {
+  theme: {
+    extend: {
+      colors: {
+        primary: 'hsl(var(--primary))'
+      }
+    }
+  }
+}
+```
+
+**Why It Fails:** Tailwind v4 completely ignores `theme.extend.colors` in config files.
+
+---
+
+## Best Practices
+
+### 1. Semantic Color Names
+
+Use semantic names, not color values:
+```css
+--primary      /* ✅ Semantic */
+--blue-500     /* ❌ Not semantic */
+```
+
+### 2. Foreground Pairing
+
+Every background color needs a foreground:
+```css
+--primary: hsl(...);
+--primary-foreground: hsl(...);
+```
+
+### 3. WCAG Contrast Ratios
+
+Ensure proper contrast:
+- Normal text: 4.5:1 minimum
+- Large text: 3:1 minimum
+- UI components: 3:1 minimum
+
+### 4. Chart Colors
+
+Charts need separate variables (don't use hsl wrapper in components):
+```css
+:root {
+  --chart-1: hsl(12 76% 61%);
+}
+
+@theme inline {
+  --color-chart-1: var(--chart-1);
+}
+```
+
+Use in components:
+```tsx
+<div style={{ backgroundColor: 'var(--chart-1)' }} />
+```
+
+---
+
+## Official Documentation
+
+- shadcn/ui Tailwind v4 Guide: https://ui.shadcn.com/docs/tailwind-v4
+- Tailwind v4 Docs: https://tailwindcss.com/docs
+- shadcn/ui Theming: https://ui.shadcn.com/docs/theming
--- a/references/common-gotchas.md
+++ b/references/common-gotchas.md
@@ -0,0 +1,469 @@
+# Common Gotchas & Solutions
+
+## Critical Failures (Will Break Your Build)
+
+### 1. `:root` Inside `@layer base`
+
+❌ **WRONG:**
+```css
+@layer base {
+  :root {
+    --background: hsl(0 0% 100%);
+  }
+}
+```
+
+✅ **CORRECT:**
+```css
+:root {
+  --background: hsl(0 0% 100%);
+}
+
+@layer base {
+  body {
+    background-color: var(--background);
+  }
+}
+```
+
+**Why:** Tailwind v4 strips CSS outside `@theme`/`@layer`, but `:root` must be at root level.
+
+---
+
+### 2. Nested `@theme` Directive
+
+❌ **WRONG:**
+```css
+@theme {
+  --color-primary: hsl(0 0% 0%);
+}
+
+.dark {
+  @theme {
+    --color-primary: hsl(0 0% 100%);
+  }
+}
+```
+
+✅ **CORRECT:**
+```css
+:root {
+  --primary: hsl(0 0% 0%);
+}
+
+.dark {
+  --primary: hsl(0 0% 100%);
+}
+
+@theme inline {
+  --color-primary: var(--primary);
+}
+```
+
+**Why:** Tailwind v4 doesn't support `@theme` inside selectors.
+
+---
+
+### 3. Double `hsl()` Wrapping
+
+❌ **WRONG:**
+```css
+@layer base {
+  body {
+    background-color: hsl(var(--background));
+  }
+}
+```
+
+✅ **CORRECT:**
+```css
+@layer base {
+  body {
+    background-color: var(--background);  /* Already has hsl() */
+  }
+}
+```
+
+**Why:** Variables already contain `hsl()`, double-wrapping creates `hsl(hsl(...))`.
+
+---
+
+### 4. Colors in `tailwind.config.ts`
+
+❌ **WRONG:**
+```typescript
+// tailwind.config.ts
+export default {
+  theme: {
+    extend: {
+      colors: {
+        primary: 'hsl(var(--primary))'
+      }
+    }
+  }
+}
+```
+
+✅ **CORRECT:**
+```typescript
+// Delete tailwind.config.ts entirely OR leave it empty
+export default {}
+
+// components.json
+{
+  "tailwind": {
+    "config": ""  // ← Empty string
+  }
+}
+```
+
+**Why:** Tailwind v4 completely ignores `theme.extend.colors`.
+
+---
+
+### 5. Missing `@theme inline` Mapping
+
+❌ **WRONG:**
+```css
+:root {
+  --background: hsl(0 0% 100%);
+}
+
+/* No @theme inline block */
+```
+
+Result: `bg-background` class doesn't exist
+
+✅ **CORRECT:**
+```css
+:root {
+  --background: hsl(0 0% 100%);
+}
+
+@theme inline {
+  --color-background: var(--background);
+}
+```
+
+**Why:** `@theme inline` generates the utility classes.
+
+---
+
+## Configuration Gotchas
+
+### 6. Wrong components.json Config
+
+❌ **WRONG:**
+```json
+{
+  "tailwind": {
+    "config": "tailwind.config.ts"  // ← No!
+  }
+}
+```
+
+✅ **CORRECT:**
+```json
+{
+  "tailwind": {
+    "config": ""  // ← Empty for v4
+  }
+}
+```
+
+---
+
+### 7. Using PostCSS Instead of Vite Plugin
+
+❌ **WRONG:**
+```typescript
+// vite.config.ts
+export default defineConfig({
+  css: {
+    postcss: './postcss.config.js'  // Old v3 way
+  }
+})
+```
+
+✅ **CORRECT:**
+```typescript
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()]  // v4 way
+})
+```
+
+---
+
+### 8. Missing Path Aliases
+
+❌ **WRONG:**
+```typescript
+// tsconfig.json has no paths
+import { Button } from '../../components/ui/button'
+```
+
+✅ **CORRECT:**
+```json
+// tsconfig.app.json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+```typescript
+import { Button } from '@/components/ui/button'
+```
+
+---
+
+## Color System Gotchas
+
+### 9. Using `dark:` Variants for Semantic Colors
+
+❌ **WRONG:**
+```tsx
+<div className="bg-primary dark:bg-primary-dark" />
+```
+
+✅ **CORRECT:**
+```tsx
+<div className="bg-primary" />
+```
+
+**Why:** With proper CSS variable setup, `bg-primary` automatically responds to theme.
+
+---
+
+### 10. Hardcoded Color Values
+
+❌ **WRONG:**
+```tsx
+<div className="bg-blue-600 dark:bg-blue-400" />
+```
+
+✅ **CORRECT:**
+```tsx
+<div className="bg-primary" />  {/* Or bg-info, bg-success, etc. */}
+```
+
+**Why:** Semantic tokens enable theme switching and reduce repetition.
+
+---
+
+## Component Gotchas
+
+### 11. Missing `cn()` Utility
+
+❌ **WRONG:**
+```tsx
+<div className={`base ${isActive && 'active'}`} />
+```
+
+✅ **CORRECT:**
+```tsx
+import { cn } from '@/lib/utils'
+<div className={cn("base", isActive && "active")} />
+```
+
+**Why:** `cn()` properly merges and deduplicates Tailwind classes.
+
+---
+
+### 12. Empty String in Radix Select
+
+❌ **WRONG:**
+```tsx
+<SelectItem value="">Select an option</SelectItem>
+```
+
+✅ **CORRECT:**
+```tsx
+<SelectItem value="placeholder">Select an option</SelectItem>
+```
+
+**Why:** Radix UI Select doesn't allow empty string values.
+
+---
+
+## Installation Gotchas
+
+### 13. Wrong Tailwind Package
+
+❌ **WRONG:**
+```bash
+npm install tailwindcss@^3.4.0  # v3
+```
+
+✅ **CORRECT:**
+```bash
+npm install tailwindcss@^4.1.0  # v4
+npm install @tailwindcss/vite
+```
+
+---
+
+### 14. Missing Dependencies
+
+❌ **WRONG:**
+```json
+{
+  "dependencies": {
+    "tailwindcss": "^4.1.0"
+    // Missing @tailwindcss/vite
+  }
+}
+```
+
+✅ **CORRECT:**
+```json
+{
+  "dependencies": {
+    "tailwindcss": "^4.1.0",
+    "@tailwindcss/vite": "^4.1.0",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0"
+  }
+}
+```
+
+---
+
+### 17. tw-animate-css Import Error (REAL-WORLD ISSUE)
+
+❌ **WRONG:**
+```bash
+npm install tailwindcss-animate  # Deprecated package
+```
+
+```css
+@import "tw-animate-css";  # Package doesn't exist in v4
+```
+
+✅ **CORRECT:**
+```bash
+# Don't install tailwindcss-animate at all
+# Use native CSS animations or @tailwindcss/motion
+```
+
+**Why:**
+- `tailwindcss-animate` is deprecated in Tailwind v4
+- Causes import errors during build
+- shadcn/ui docs may still reference it (outdated)
+- The skill handles animations differently in v4
+
+**Impact:** Build failure, requires manual CSS file cleanup
+
+---
+
+### 18. Duplicate @layer base After shadcn init (REAL-WORLD ISSUE)
+
+❌ **WRONG:**
+```css
+/* After running shadcn init, you might have: */
+@layer base {
+  body {
+    background-color: var(--background);
+  }
+}
+
+@layer base {  /* ← Duplicate added by shadcn init */
+  * {
+    border-color: hsl(var(--border));
+  }
+}
+```
+
+✅ **CORRECT:**
+```css
+/* Merge into single @layer base block */
+@layer base {
+  * {
+    border-color: var(--border);
+  }
+
+  body {
+    background-color: var(--background);
+    color: var(--foreground);
+  }
+}
+```
+
+**Why:**
+- `shadcn init` adds its own `@layer base` block
+- Results in duplicate layer declarations
+- Can cause unexpected CSS priority issues
+- Easy to miss during setup
+
+**Prevention:**
+- Check `src/index.css` immediately after running `shadcn init`
+- Merge any duplicate `@layer base` blocks
+- Keep only one base layer section
+
+**Impact:** CSS priority issues, harder to debug styling problems
+
+---
+
+## Testing Gotchas
+
+### 15. Not Testing Both Themes
+
+❌ **WRONG:**
+Only testing in light mode
+
+✅ **CORRECT:**
+Test in:
+- Light mode
+- Dark mode
+- System mode
+- Both initial load and toggle
+
+---
+
+### 16. Not Checking Contrast
+
+❌ **WRONG:**
+Colors look good but fail WCAG
+
+✅ **CORRECT:**
+- Use browser DevTools Lighthouse
+- Check contrast ratios (4.5:1 minimum)
+- Test with actual users
+
+---
+
+## Quick Diagnosis
+
+**Symptoms → Likely Cause:**
+
+| Symptom | Likely Cause |
+|---------|-------------|
+| `bg-primary` doesn't work | Missing `@theme inline` mapping |
+| Colors all black/white | Double `hsl()` wrapping |
+| Dark mode not switching | Missing ThemeProvider |
+| Build fails | `tailwind.config.ts` exists with theme config |
+| Text invisible | Wrong contrast colors |
+| `@/` imports fail | Missing path aliases in tsconfig |
+
+---
+
+## Prevention Checklist
+
+Before deploying:
+- [ ] No `tailwind.config.ts` file (or it's empty)
+- [ ] `components.json` has `"config": ""`
+- [ ] All colors have `hsl()` wrapper in `:root`
+- [ ] `@theme inline` maps all variables
+- [ ] `@layer base` doesn't wrap `:root`
+- [ ] Theme provider wraps app
+- [ ] Tested in both light and dark modes
+- [ ] All text has sufficient contrast
--- a/references/dark-mode.md
+++ b/references/dark-mode.md
@@ -0,0 +1,239 @@
+# Dark Mode Implementation
+
+## Overview
+
+Tailwind v4 + shadcn/ui dark mode requires:
+1. `ThemeProvider` component to manage state
+2. `.dark` class toggling on `<html>` element
+3. localStorage persistence
+4. System theme detection
+
+---
+
+## ThemeProvider Component
+
+### Full Implementation
+
+```typescript
+// src/components/theme-provider.tsx
+import { createContext, useContext, useEffect, useState, ReactNode } from 'react'
+
+type Theme = 'dark' | 'light' | 'system'
+
+type ThemeProviderProps = {
+  children: ReactNode
+  defaultTheme?: Theme
+  storageKey?: string
+}
+
+type ThemeProviderState = {
+  theme: Theme
+  setTheme: (theme: Theme) => void
+}
+
+const initialState: ThemeProviderState = {
+  theme: 'system',
+  setTheme: () => null,
+}
+
+const ThemeProviderContext = createContext<ThemeProviderState>(initialState)
+
+export function ThemeProvider({
+  children,
+  defaultTheme = 'system',
+  storageKey = 'vite-ui-theme',
+  ...props
+}: ThemeProviderProps) {
+  const [theme, setTheme] = useState<Theme>(() => {
+    try {
+      return (localStorage.getItem(storageKey) as Theme) || defaultTheme
+    } catch (e) {
+      return defaultTheme
+    }
+  })
+
+  useEffect(() => {
+    const root = window.document.documentElement
+    root.classList.remove('light', 'dark')
+
+    if (theme === 'system') {
+      const systemTheme = window.matchMedia('(prefers-color-scheme: dark)')
+        .matches ? 'dark' : 'light'
+      root.classList.add(systemTheme)
+      return
+    }
+
+    root.classList.add(theme)
+  }, [theme])
+
+  const value = {
+    theme,
+    setTheme: (theme: Theme) => {
+      try {
+        localStorage.setItem(storageKey, theme)
+      } catch (e) {
+        console.warn('Storage unavailable')
+      }
+      setTheme(theme)
+    },
+  }
+
+  return (
+    <ThemeProviderContext.Provider {...props} value={value}>
+      {children}
+    </ThemeProviderContext.Provider>
+  )
+}
+
+export const useTheme = () => {
+  const context = useContext(ThemeProviderContext)
+  if (context === undefined)
+    throw new Error('useTheme must be used within a ThemeProvider')
+  return context
+}
+```
+
+### Wrap Your App
+
+```typescript
+// src/main.tsx
+import { ThemeProvider } from '@/components/theme-provider'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <ThemeProvider defaultTheme="dark" storageKey="vite-ui-theme">
+      <App />
+    </ThemeProvider>
+  </React.StrictMode>,
+)
+```
+
+---
+
+## Theme Toggle Component
+
+### Using shadcn/ui Dropdown Menu
+
+```bash
+pnpm dlx shadcn@latest add dropdown-menu
+```
+
+```typescript
+// src/components/mode-toggle.tsx
+import { Moon, Sun } from "lucide-react"
+import { Button } from "@/components/ui/button"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu"
+import { useTheme } from "@/components/theme-provider"
+
+export function ModeToggle() {
+  const { setTheme } = useTheme()
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="outline" size="icon">
+          <Sun className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
+          <Moon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
+          <span className="sr-only">Toggle theme</span>
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end">
+        <DropdownMenuItem onClick={() => setTheme("light")}>
+          Light
+        </DropdownMenuItem>
+        <DropdownMenuItem onClick={() => setTheme("dark")}>
+          Dark
+        </DropdownMenuItem>
+        <DropdownMenuItem onClick={() => setTheme("system")}>
+          System
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+```
+
+---
+
+## How It Works
+
+### Theme Flow
+
+```
+User selects theme → setTheme() called
+  ↓
+Save to localStorage
+  ↓
+Update state
+  ↓
+useEffect triggers
+  ↓
+Remove existing classes (.light, .dark)
+  ↓
+Add new class to <html>
+  ↓
+CSS variables update (.dark overrides :root)
+  ↓
+UI updates automatically
+```
+
+### System Theme Detection
+
+```typescript
+if (theme === 'system') {
+  const systemTheme = window.matchMedia('(prefers-color-scheme: dark)')
+    .matches ? 'dark' : 'light'
+  root.classList.add(systemTheme)
+}
+```
+
+This respects the user's OS preference when "System" is selected.
+
+---
+
+## Common Issues
+
+### Issue: Dark mode not switching
+
+**Cause:** Theme provider not wrapping app
+**Fix:** Ensure `<ThemeProvider>` wraps your app in `main.tsx`
+
+### Issue: Theme resets on page refresh
+
+**Cause:** localStorage not working
+**Fix:** Check browser privacy settings, add sessionStorage fallback
+
+### Issue: Flash of wrong theme on load
+
+**Cause:** Theme applied after initial render
+**Fix:** Add inline script to `index.html` (advanced)
+
+### Issue: Icons not changing
+
+**Cause:** CSS transitions not working
+**Fix:** Verify icon classes use `dark:` variants for animations
+
+---
+
+## Testing Checklist
+
+- [ ] Light mode displays correctly
+- [ ] Dark mode displays correctly
+- [ ] System mode respects OS setting
+- [ ] Theme persists after page refresh
+- [ ] Toggle component shows current state
+- [ ] All text has proper contrast
+- [ ] No flash of wrong theme on load
+- [ ] Works in incognito mode (graceful fallback)
+
+---
+
+## Official Documentation
+
+- shadcn/ui Dark Mode (Vite): https://ui.shadcn.com/docs/dark-mode/vite
+- Tailwind Dark Mode: https://tailwindcss.com/docs/dark-mode
--- a/references/migration-guide.md
+++ b/references/migration-guide.md
@@ -0,0 +1,313 @@
+# 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!