Initial commit
This commit is contained in:
Zhongwei Li
313
references/migration-guide.md
Normal file
313
references/migration-guide.md
Normal file
@@ -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!
|
||||
Reference in New Issue
Block a user