docs: add comprehensive Tailwind migration documentation

- Document completed migration phases (setup, base, layout, components) - Track metrics: 190+ lines of CSS removed - Define strategy for incremental component migrations - Document z-index layering and responsive breakpoints - Provide technical notes for future development - Mark core migration as complete and production-ready
2026-01-31 04:34:39 +01:00 · 2025-10-13 22:00:34 +02:00
parent f3f80449a6
commit a0e5ba3a63
1 changed files with 188 additions and 0 deletions
--- a/TAILWIND_MIGRATION.md
+++ b/TAILWIND_MIGRATION.md
@@ -0,0 +1,188 @@
+# Tailwind CSS Migration Status
+
+## ✅ Completed (Core Infrastructure)
+
+### Phase 1: Setup & Foundation
+- [x] Install Tailwind CSS with PostCSS and Autoprefixer
+- [x] Configure `tailwind.config.js` with content globs and custom keyframes
+- [x] Create `src/styles/tailwind.css` with base/components/utilities
+- [x] Import Tailwind before existing CSS in `main.tsx`
+- [x] Enable Tailwind preflight (CSS reset)
+
+### Phase 2: Base Styles Reconciliation
+- [x] Add CSS variables for user-settable theme colors
+  - `--highlight-color-mine`, `--highlight-color-friends`, `--highlight-color-nostrverse`
+  - `--reading-font`, `--reading-font-size`
+- [x] Simplify `global.css` to work with Tailwind preflight
+- [x] Remove redundant base styles handled by Tailwind
+- [x] Keep app-specific overrides (mobile sidebar lock, loading states)
+
+### Phase 3: Layout System Refactor ⭐ **CRITICAL FIX**
+- [x] Switch from pane-scrolling to document-scrolling
+- [x] Make sidebars sticky on desktop (`position: sticky`)
+- [x] Update `app.css` to remove fixed container heights
+- [x] Update `ThreePaneLayout.tsx` to use window scroll
+- [x] Fix reading position tracking to work with document scroll
+- [x] Maintain mobile overlay behavior
+
+### Phase 4: Component Migrations
+- [x] **ReadingProgressIndicator**: Full Tailwind conversion
+  - Removed 80+ lines of CSS
+  - Added shimmer animation to Tailwind config
+  - Z-index layering maintained (1102)
+  
+- [x] **Mobile UI Elements**: Tailwind utilities
+  - Mobile hamburger button
+  - Mobile highlights button  
+  - Mobile backdrop
+  - Removed 60+ lines of CSS
+
+- [x] **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:
+```tsx
+// 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:
+```tsx
+// 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:
+```tsx
+style={{ 
+  top: 'calc(1rem + env(safe-area-inset-top))',
+  left: 'calc(1rem + env(safe-area-inset-left))'
+}}
+```
+
+### Custom Animations
+Add to `tailwind.config.js`:
+```js
+keyframes: {
+  shimmer: {
+    '0%': { transform: 'translateX(-100%)' },
+    '100%': { transform: 'translateX(100%)' },
+  },
+}
+```
+
+## ✅ Success Criteria Met
+
+- [x] Tailwind CSS fully integrated and functional
+- [x] Document scrolling working correctly
+- [x] Reading position tracking accurate
+- [x] Progress indicator always visible
+- [x] No TypeScript errors
+- [x] No linting errors
+- [x] Mobile responsiveness maintained
+- [x] Theme colors (user settings) working
+- [x] 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
+