docs: add comprehensive Tailwind color migration plan

TAILWIND_COLOR_MIGRATION.md

@@ -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
+