boris/TAILWIND_MIGRATION.md

Tailwind CSS Migration Status

✅ Completed (Core Infrastructure)

Phase 1: Setup & Foundation

• Install Tailwind CSS with PostCSS and Autoprefixer
• Configure tailwind.config.js with content globs and custom keyframes
• Create src/styles/tailwind.css with base/components/utilities
• Import Tailwind before existing CSS in main.tsx
• Enable Tailwind preflight (CSS reset)

Phase 2: Base Styles Reconciliation

• Add CSS variables for user-settable theme colors
  • --highlight-color-mine, --highlight-color-friends, --highlight-color-nostrverse
  • --reading-font, --reading-font-size
• Simplify global.css to work with Tailwind preflight
• Remove redundant base styles handled by Tailwind
• Keep app-specific overrides (mobile sidebar lock, loading states)

Phase 3: Layout System Refactor ⭐ CRITICAL FIX

• Switch from pane-scrolling to document-scrolling
• Make sidebars sticky on desktop (position: sticky)
• Update app.css to remove fixed container heights
• Update ThreePaneLayout.tsx to use window scroll
• Fix reading position tracking to work with document scroll
• Maintain mobile overlay behavior

Phase 4: Component Migrations

• ReadingProgressIndicator: Full Tailwind conversion

  • Removed 80+ lines of CSS
  • Added shimmer animation to Tailwind config
  • Z-index layering maintained (1102)

• Mobile UI Elements: Tailwind utilities

  • Mobile hamburger button
  • Mobile highlights button
  • Mobile backdrop
  • Removed 60+ lines of CSS

• App Container: Tailwind utilities

  • Responsive padding (p-0 md:p-4)
  • Min-height viewport support

📊 Impact & Metrics

Lines of CSS Removed

• global.css: ~50 lines removed
• reader.css: ~80 lines removed (progress indicator)
• app.css: ~30 lines removed (mobile buttons/backdrop)
• sidebar.css: ~30 lines removed (mobile hamburger)
• Total: ~190 lines removed

Key Achievements

1. Fixed Core Issue: Reading position tracking now works correctly with document scroll
2. Tailwind Integration: Fully functional with preflight enabled
3. No Breaking Changes: All existing functionality preserved
4. Type Safety: TypeScript checks passing
5. Lint Clean: ESLint checks passing
6. Responsive: Mobile/tablet/desktop layouts working

🔄 Remaining Work (Incremental)

The following migrations are optional enhancements that can be done as components are touched:

High-Value Components

• ContentPanel - Large component, high impact

  • Reader header, meta info, loading states
  • Mark as read button
  • Article/video menus

• BookmarkList & BookmarkItem - Core UI

  • Card layouts (compact/cards/large views)
  • Bookmark metadata display
  • Interactive states

• HighlightsPanel - Feature-rich

  • Header with toggles
  • Highlight items
  • Level-based styling

• Settings Components - Forms & controls

  • Color pickers
  • Font selectors
  • Toggle switches
  • Sliders

CSS Files to Prune

• src/index.css - Contains many inline bookmark/highlight styles (~3000+ lines)
• src/styles/components/cards.css - Bookmark card styles
• src/styles/components/modals.css - Modal dialogs
• src/styles/layout/highlights.css - Highlight panel layout

🎯 Migration Strategy

For New Components

Use Tailwind utilities from the start. Reference:

// Good: Tailwind utilities
<div className="flex items-center gap-2 p-4 bg-gray-800 rounded-lg">
  
// Avoid: New CSS classes
<div className="custom-component">

For Existing Components

Migrate incrementally when touching files:

1. Replace layout utilities (flex, grid, spacing, sizing)
2. Replace color/background utilities
3. Replace typography utilities
4. Replace responsive variants
5. Remove old CSS rules
6. Keep file under 210 lines

CSS Variable Usage

Dynamic values should still use CSS variables or inline styles:

// User-settable colors
style={{ backgroundColor: settings.highlightColorMine }}

// Or reference CSS variable
className="bg-[var(--highlight-color-mine)]"

📝 Technical Notes

Z-Index Layering

• Mobile sidepanes: z-[1001]
• Mobile backdrop: z-[999]
• Progress indicator: z-[1102]
• Mobile buttons: z-[900]
• Relay status: z-[999]
• Modals: z-[10000]

Responsive Breakpoints

• Mobile: < 768px
• Tablet: 768px - 1024px
• Desktop: > 1024px

Use Tailwind: md: (768px), lg: (1024px)

Safe Area Insets

Mobile notch support:

style={{ 
  top: 'calc(1rem + env(safe-area-inset-top))',
  left: 'calc(1rem + env(safe-area-inset-left))'
}}

Custom Animations

Add to tailwind.config.js:

keyframes: {
  shimmer: {
    '0%': { transform: 'translateX(-100%)' },
    '100%': { transform: 'translateX(100%)' },
  },
}

✅ Success Criteria Met

• Tailwind CSS fully integrated and functional
• Document scrolling working correctly
• Reading position tracking accurate
• Progress indicator always visible
• No TypeScript errors
• No linting errors
• Mobile responsiveness maintained
• Theme colors (user settings) working
• All existing features functional

🚀 Next Steps

1. Ship It: Current state is production-ready
2. Incremental Migration: Convert components as you touch them
3. Monitor: Watch for any CSS conflicts
4. Cleanup: Eventually remove unused CSS files
5. Document: Update component docs with Tailwind patterns

---

Status: ✅ CORE MIGRATION COMPLETE
Date: 2025-01-14
Commits: 8 conventional commits
Lines Removed: ~190 lines of CSS
Breaking Changes: None