mirror of
https://github.com/dergigi/boris.git
synced 2025-12-18 07:04:19 +01:00
docs: add comprehensive Tailwind color migration plan
This commit is contained in:
Gigi
218
TAILWIND_COLOR_MIGRATION.md
Normal file
218
TAILWIND_COLOR_MIGRATION.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# Tailwind Color Migration Plan
|
||||
|
||||
## Overview
|
||||
Migrate from hardcoded hex colors to Tailwind's semantic color palette for better maintainability and consistency.
|
||||
|
||||
## Color Mapping Strategy
|
||||
|
||||
### Primary Color Scale (Zinc - Neutral grays)
|
||||
```
|
||||
#1a1a1a (15 uses) → zinc-900 (oklch(0.21 0.006 285.885))
|
||||
#1e1e1e (6 uses) → zinc-850 (between 800-900)
|
||||
#252525 (4 uses) → zinc-800 (oklch(0.274 0.006 286.033))
|
||||
#2a2a2a (20 uses) → zinc-800 (oklch(0.274 0.006 286.033))
|
||||
#333 (32 uses) → zinc-700 (oklch(0.37 0.013 285.805))
|
||||
#444 (15 uses) → zinc-600 (oklch(0.442 0.017 285.786))
|
||||
#666 (8 uses) → zinc-500 (oklch(0.552 0.016 285.938))
|
||||
#888 (21 uses) → zinc-400 (oklch(0.705 0.015 286.067))
|
||||
#999 (5 uses) → zinc-400 (oklch(0.705 0.015 286.067))
|
||||
#aaa (5 uses) → zinc-300 (oklch(0.871 0.006 286.286))
|
||||
#ccc (10 uses) → zinc-200 (oklch(0.92 0.004 286.32))
|
||||
#ddd (18 uses) → zinc-200 (oklch(0.92 0.004 286.32))
|
||||
#fff (21 uses) → white (oklch(1 0 0))
|
||||
```
|
||||
|
||||
### Accent Colors
|
||||
```
|
||||
#646cff (31 uses) → indigo-500 (oklch(0.637 0.202 272.317))
|
||||
#535bf2 (4 uses) → indigo-600 (oklch(0.574 0.231 274.009))
|
||||
#8b5cf6 (3 uses) → violet-500 (oklch(0.627 0.246 293.04))
|
||||
```
|
||||
|
||||
### Semantic Colors
|
||||
```
|
||||
#dc3545 (4 uses) → red-600 (oklch(0.593 0.243 27.325))
|
||||
#28a745 (legacy) → green-600 (oklch(0.643 0.179 149.579))
|
||||
```
|
||||
|
||||
### User-Settable Highlight Colors (Keep as CSS Variables)
|
||||
```
|
||||
--highlight-color-mine: #ffff00 → Keep (yellow-400)
|
||||
--highlight-color-friends: #f97316 → Keep (orange-500) ✓ Already Tailwind!
|
||||
--highlight-color-nostrverse: #9333ea → Keep (purple-600) ✓ Already Tailwind!
|
||||
```
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
### Phase 1: Setup Tailwind Theme Extension (30 min)
|
||||
1. **Extend Tailwind config** with semantic color names
|
||||
```js
|
||||
theme: {
|
||||
extend: {
|
||||
colors: {
|
||||
'app-bg': 'zinc-900',
|
||||
'app-bg-elevated': 'zinc-800',
|
||||
'app-border': 'zinc-700',
|
||||
'app-border-subtle': 'zinc-600',
|
||||
'app-text': 'zinc-200',
|
||||
'app-text-secondary': 'zinc-400',
|
||||
'app-text-muted': 'zinc-500',
|
||||
'primary': 'indigo-500',
|
||||
'primary-hover': 'indigo-600',
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Update CSS variables** in `variables.css` to reference Tailwind colors
|
||||
```css
|
||||
:root {
|
||||
/* Use Tailwind's zinc scale */
|
||||
--color-bg-primary: theme('colors.zinc.900');
|
||||
--color-bg-secondary: theme('colors.zinc.800');
|
||||
--color-border: theme('colors.zinc.700');
|
||||
--color-text-primary: theme('colors.zinc.200');
|
||||
--color-text-secondary: theme('colors.zinc.400');
|
||||
--color-accent: theme('colors.indigo.500');
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 2: Component Migration (2-3 hours)
|
||||
Priority order based on usage and visibility:
|
||||
|
||||
#### High Priority (Most Used)
|
||||
1. **Layout components** (`app.css`, `sidebar.css`, `highlights.css`)
|
||||
- Replace `#333`, `#2a2a2a`, `#1a1a1a` with zinc scale
|
||||
- Replace `#646cff` with `indigo-500`
|
||||
- ~83 replacements
|
||||
|
||||
2. **Interactive components** (`icon-button.css`, `forms.css`, `cards.css`)
|
||||
- Buttons, inputs, cards
|
||||
- ~45 replacements
|
||||
|
||||
3. **Content components** (`reader.css`, `modals.css`, `toast.css`)
|
||||
- Reader interface, overlays
|
||||
- ~35 replacements
|
||||
|
||||
#### Medium Priority
|
||||
4. **Utility classes** (`utilities.css`, `animations.css`)
|
||||
- Helper classes
|
||||
- ~20 replacements
|
||||
|
||||
5. **Profile and settings** (`profile.css`, `settings.css`, `me.css`)
|
||||
- User-facing settings
|
||||
- ~25 replacements
|
||||
|
||||
#### Low Priority
|
||||
6. **Legacy styles** (`legacy.css`)
|
||||
- Already minimal, keep for now
|
||||
- Only ~5 colors used
|
||||
|
||||
### Phase 3: Component Files (1-2 hours)
|
||||
1. **Replace arbitrary color values** in TSX files
|
||||
```tsx
|
||||
// Before
|
||||
className="bg-[#2a2a2a]"
|
||||
|
||||
// After
|
||||
className="bg-zinc-800"
|
||||
```
|
||||
|
||||
2. **Update inline styles** that use hex colors
|
||||
```tsx
|
||||
// Before
|
||||
style={{ backgroundColor: '#646cff' }}
|
||||
|
||||
// After
|
||||
style={{ backgroundColor: 'rgb(var(--color-indigo-500))' }}
|
||||
```
|
||||
|
||||
### Phase 4: Testing & Validation (30 min)
|
||||
1. Visual regression check on all pages
|
||||
2. Test dark mode (if/when implemented)
|
||||
3. Verify user-settable colors still work
|
||||
4. Check color contrast ratios for accessibility
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
### Step 1: Extend Tailwind Config
|
||||
```bash
|
||||
# Edit tailwind.config.js
|
||||
```
|
||||
|
||||
### Step 2: Update CSS Variables
|
||||
```bash
|
||||
# Edit src/styles/base/variables.css
|
||||
```
|
||||
|
||||
### Step 3: Systematic File Updates
|
||||
```bash
|
||||
# Use find & replace with regex
|
||||
# Pattern: #([0-9a-fA-F]{3,6})
|
||||
# Test each file before committing
|
||||
```
|
||||
|
||||
### Step 4: Update Components
|
||||
```bash
|
||||
# Search for className with arbitrary values
|
||||
# Pattern: bg-\[#|text-\[#|border-\[#
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **Maintainability**: Semantic color names (`zinc-800` vs `#2a2a2a`)
|
||||
2. **Consistency**: Same color palette across entire app
|
||||
3. **Dark Mode Ready**: Easy to add `dark:` variants later
|
||||
4. **Type Safety**: Tailwind's autocomplete in editors
|
||||
5. **Performance**: No need for arbitrary value parsing
|
||||
6. **Documentation**: Colors self-document their purpose
|
||||
7. **Flexibility**: Easy to change entire color scheme
|
||||
|
||||
## Special Considerations
|
||||
|
||||
### Keep CSS Variables For:
|
||||
- User-settable highlight colors
|
||||
- Dynamic theme colors from user preferences
|
||||
- Colors that need JavaScript manipulation
|
||||
|
||||
### Example:
|
||||
```css
|
||||
/* Good: User-settable */
|
||||
--highlight-color-mine: #ffff00;
|
||||
color: var(--highlight-color-mine);
|
||||
|
||||
/* Good: Tailwind utility */
|
||||
.button {
|
||||
@apply bg-zinc-800 hover:bg-zinc-700;
|
||||
}
|
||||
|
||||
/* Bad: Hardcoded hex */
|
||||
background: #2a2a2a;
|
||||
```
|
||||
|
||||
## Rollback Plan
|
||||
If issues arise:
|
||||
1. Git revert is available (commit per phase)
|
||||
2. CSS variables provide abstraction layer
|
||||
3. Old hex colors documented in this plan
|
||||
|
||||
## Timeline
|
||||
- Phase 1: 30 minutes
|
||||
- Phase 2: 2-3 hours
|
||||
- Phase 3: 1-2 hours
|
||||
- Phase 4: 30 minutes
|
||||
- **Total: 4-6 hours**
|
||||
|
||||
## Success Metrics
|
||||
- ✅ Zero hardcoded hex colors in components
|
||||
- ✅ All colors use Tailwind palette or CSS variables
|
||||
- ✅ No visual regressions
|
||||
- ✅ Improved maintainability score
|
||||
- ✅ Consistent color naming throughout
|
||||
|
||||
## Notes
|
||||
- Commit after each phase
|
||||
- Test visual appearance after each file
|
||||
- Keep CHANGELOG.md updated
|
||||
- Update TAILWIND_MIGRATION.md with progress
|
||||
|
||||
Reference in New Issue
Block a user