aljaz/boris

Fork 0

mirror of https://github.com/dergigi/boris.git synced 2026-01-01 22:14:20 +01:00

Files

Gigi b145aee29d docs: add comprehensive Tailwind color migration plan

2025-10-13 22:54:22 +02:00

6.1 KiB

Raw Blame History

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)

Extend Tailwind config with semantic color names

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',
    }
  }
}

Update CSS variables in variables.css to reference Tailwind colors

: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)

Layout components (app.css, sidebar.css, highlights.css)
- Replace #333, #2a2a2a, #1a1a1a with zinc scale
- Replace #646cff with indigo-500
- ~83 replacements
Interactive components (icon-button.css, forms.css, cards.css)
- Buttons, inputs, cards
- ~45 replacements
Content components (reader.css, modals.css, toast.css)
- Reader interface, overlays
- ~35 replacements

Medium Priority

Utility classes (utilities.css, animations.css)
- Helper classes
- ~20 replacements
Profile and settings (profile.css, settings.css, me.css)
- User-facing settings
- ~25 replacements

Low Priority

Legacy styles (legacy.css)
- Already minimal, keep for now
- Only ~5 colors used

Phase 3: Component Files (1-2 hours)

Replace arbitrary color values in TSX files

// Before
className="bg-[#2a2a2a]"

// After
className="bg-zinc-800"

Update inline styles that use hex colors

// Before
style={{ backgroundColor: '#646cff' }}

// After
style={{ backgroundColor: 'rgb(var(--color-indigo-500))' }}

Phase 4: Testing & Validation (30 min)

Visual regression check on all pages
Test dark mode (if/when implemented)
Verify user-settable colors still work
Check color contrast ratios for accessibility

Implementation Steps

Step 1: Extend Tailwind Config

# Edit tailwind.config.js

Step 2: Update CSS Variables

# Edit src/styles/base/variables.css

Step 3: Systematic File Updates

# Use find & replace with regex
# Pattern: #([0-9a-fA-F]{3,6})
# Test each file before committing

Step 4: Update Components

# Search for className with arbitrary values
# Pattern: bg-\[#|text-\[#|border-\[#

Benefits

Maintainability: Semantic color names (zinc-800 vs #2a2a2a)
Consistency: Same color palette across entire app
Dark Mode Ready: Easy to add dark: variants later
Type Safety: Tailwind's autocomplete in editors
Performance: No need for arbitrary value parsing
Documentation: Colors self-document their purpose
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:

/* 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:

Git revert is available (commit per phase)
CSS variables provide abstraction layer
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

6.1 KiB Raw Blame History