# Semantic Styling Framework Refactoring Checklist This document tracks the refactoring of our CSS and TSX files to use the semantic styling framework, eliminating duplicate CSS and creating consistent component patterns. ## Framework Overview Our semantic styling framework consists of: - **`colors.css`** - CSS variables and color system - **`semantic-components.css`** - Semantic component classes (cards, badges, actions, drag-and-drop, etc.) - **`application.css`** - Utility classes and base component styles - **`aspectRatios.css`** - Dedicated aspect ratio styling for slides (preserved) ## Refactoring Principles 1. **Use semantic classes** instead of component-specific CSS 2. **Leverage CSS variables** for colors, spacing, and typography 3. **Eliminate duplicate styles** by consolidating common patterns 4. **Preserve presentation/theme CSS** - slides should NOT use semantic framework 5. **Only keep minimal component-specific CSS** when absolutely necessary --- ## ✅ COMPLETED REFACTORING ### Core Framework Files - **`src/styles/colors.css`** ✅ - Comprehensive CSS variable system - **`src/styles/semantic-components.css`** ✅ - Semantic component classes - **`src/styles/application.css`** ✅ - Utility classes and base styles - **`src/styles/aspectRatios.css`** ✅ - Preserved dedicated slide aspect ratios ### Presentation Components - **`src/components/presentations/PresentationEditor.tsx`** ✅ - Uses semantic classes - **`src/components/presentations/PresentationEditor.css`** ✅ - Reduced by ~85%, only layout-specific CSS - **`src/components/presentations/SlidesSidebar.tsx`** ✅ - Uses semantic classes - **`src/components/presentations/SlidesSidebar.css`** ✅ - Minimal component-specific CSS - **`src/components/presentations/shared/SlideThumbnail.tsx`** ✅ - Uses semantic classes - **`src/components/presentations/shared/SlideThumbnail.css`** ✅ - Minimal component overrides - **`src/components/presentations/PresentationMode.tsx`** ✅ - Uses semantic classes for UI - **`src/components/presentations/PresentationMode.css`** ✅ - Isolated slide content from semantic framework - **`src/components/presentations/shared/LoadingState.tsx`** ✅ - Uses semantic classes - **`src/components/presentations/shared/LoadingState.css`** ✅ - Minimal overrides - **`src/components/presentations/shared/ErrorState.tsx`** ✅ - Uses semantic classes (slide-editor version) - **`src/components/presentations/shared/ErrorState.css`** ✅ - Minimal overrides ### Slide Operations - **`src/hooks/useSlideOperations.ts`** ✅ - Added drag-and-drop reordering functionality --- ## 🚧 NEEDS REFACTORING ### High Priority - Presentation Components #### **`src/components/presentations/NewPresentationPage.tsx`** - **Status**: Partially refactored (documented in CSS) - **Needs**: Full TSX refactoring to use semantic classes - **Current Issues**: Uses custom classes that could be semantic utilities #### **`src/components/presentations/NewPresentationPage.css`** - **Status**: Has some semantic references but needs full refactoring - **Needs**: Remove duplicate styles, use semantic framework - **Current Issues**: Custom `.creation-form`, `.aspect-ratio-card` styles #### **`src/components/presentations/ThemeSelector.tsx`** - **Status**: Not refactored - **Needs**: Use semantic classes for cards, grids, badges - **Current Issues**: Likely uses hardcoded CSS classes #### **`src/components/presentations/ThemeSelector.css`** - **Status**: Partially refactored (hardcoded colors removed) - **Needs**: Complete semantic class integration - **Current Issues**: Custom `.theme-card`, `.themes-grid` could use semantic classes #### **`src/components/presentations/PresentationsList.tsx`** - **Status**: Not examined/refactored - **Needs**: Full refactoring assessment - **Likely Issues**: Custom card layouts, button styles #### **`src/components/presentations/PresentationsList.css`** - **Status**: Not examined/refactored - **Needs**: Full refactoring assessment - **Likely Issues**: Duplicate card, button, grid styles ### Medium Priority - Form Components #### **`src/components/presentations/PresentationDetailsForm.tsx`** - **Status**: Not examined/refactored - **Needs**: Use semantic form classes - **Likely Issues**: Custom form styling #### **`src/components/presentations/PresentationDetailsForm.css`** - **Status**: Not examined/refactored - **Needs**: Use `.form-group`, `.form-input`, `.form-label` semantic classes - **Likely Issues**: Duplicate form styles #### **`src/components/presentations/AspectRatioSelector.tsx`** - **Status**: Not examined/refactored - **Needs**: Use semantic card and selection classes - **Likely Issues**: Custom card selection UI #### **`src/components/presentations/AspectRatioSelector.css`** - **Status**: Not examined/refactored - **Needs**: Use semantic `.card-interactive` and selection states - **Likely Issues**: Custom card hover/selection styles ### Lower Priority - Supporting Components #### **`src/components/presentations/CreationActions.tsx`** - **Status**: Not examined/refactored - **Needs**: Use semantic button classes - **Likely Issues**: Custom button layouts #### **`src/components/presentations/CreationActions.css`** - **Status**: Not examined/refactored - **Needs**: Use `.btn`, `.btn-primary`, `.btn-secondary` classes - **Likely Issues**: Duplicate button styles #### **`src/components/presentations/ThemeSelectionSection.tsx`** - **Status**: Not examined/refactored - **Needs**: Use semantic layout and card classes - **Likely Issues**: Custom section layouts #### **`src/components/presentations/ThemeSelectionSection.css`** - **Status**: Not examined/refactored - **Needs**: Use semantic grid and card classes - **Likely Issues**: Custom grid layouts #### **`src/components/presentations/EmptyPresentationState.tsx`** - **Status**: Not examined/refactored - **Needs**: Use semantic empty state classes - **Likely Issues**: Custom empty state styling #### **`src/components/presentations/EmptyPresentationState.css`** - **Status**: Not examined/refactored - **Needs**: Use `.empty-content` semantic class - **Likely Issues**: Duplicate empty state styles ### Slide Editor Components (Lower Priority) #### **`src/components/slide-editor/SlideEditor.tsx`** - **Status**: Not examined/refactored - **Needs**: Assessment for semantic class usage - **Note**: May have complex layout requirements #### **`src/components/slide-editor/SlideEditor.css`** - **Status**: Not examined/refactored - **Needs**: Assessment for consolidation opportunities - **Note**: May need to preserve slide-specific styling ### Theme Components #### **`src/components/themes/` (Multiple files)** - **Status**: Not examined for this refactoring - **Priority**: Low (theme browsing is separate from presentations) - **Needs**: Future assessment ### UI Components #### **`src/components/ui/` (Multiple files)** - **Status**: Not examined for this refactoring - **Priority**: Medium (shared components should use semantic framework) - **Needs**: Future assessment for modal, dialog, form components --- ## 🎯 NEXT STEPS ### Immediate Priority (Sprint 1) 1. **NewPresentationPage.tsx** - Full semantic refactoring 2. **ThemeSelector.tsx** - Use semantic card and grid classes 3. **PresentationsList.tsx** - Assessment and refactoring ### Short Term (Sprint 2) 1. **Form Components** - PresentationDetailsForm, AspectRatioSelector 2. **Supporting Components** - CreationActions, ThemeSelectionSection 3. **Empty States** - EmptyPresentationState ### Long Term (Sprint 3) 1. **Slide Editor Components** - Assessment and selective refactoring 2. **UI Components** - Modal, dialog, form utilities 3. **Theme Components** - If needed for consistency --- ## 📋 REFACTORING CHECKLIST For each component refactoring, ensure: ### TSX File Updates - [ ] Replace custom CSS classes with semantic classes - [ ] Use utility classes for layout (`flex`, `gap-4`, `items-center`, etc.) - [ ] Use semantic typography classes (`text-lg`, `font-semibold`, etc.) - [ ] Use semantic color classes (`text-primary`, `bg-secondary`, etc.) - [ ] Use semantic component classes (`.card-interactive`, `.btn`, `.badge-secondary`, etc.) - [ ] Remove imports of CSS files that become empty ### CSS File Updates - [ ] Remove duplicate styles covered by semantic framework - [ ] Replace hardcoded colors with CSS variables - [ ] Keep only truly component-specific styling - [ ] Use semantic classes as base, add minimal overrides only - [ ] Document what semantic classes replace in comments - [ ] Delete CSS file if it becomes empty/unnecessary ### Testing Requirements - [ ] Visual consistency with existing design - [ ] Interactive states work correctly (hover, focus, disabled) - [ ] Responsive behavior maintained - [ ] No regression in functionality - [ ] Accessibility maintained (focus states, etc.) --- ## 🚨 SPECIAL CONSIDERATIONS ### Presentation/Slide Content Isolation - **Theme CSS** (`public/themes/default/style.css`) must remain completely isolated - **Slide content** should NEVER use semantic framework classes - **PresentationMode** must prevent semantic class interference with slide rendering - **AspectRatios.css** preserved for slide-specific aspect ratio handling ### Performance Considerations - **Bundle size reduction** achieved through elimination of duplicate CSS - **CSS loading order** maintained (colors → semantic-components → application) - **Critical CSS** identified and preserved for above-the-fold content ### Drag-and-Drop Functionality - **Semantic drag classes** implemented and working (`.draggable`, `.dragged`, `.drag-over`, `.drag-handle`) - **Slide reordering** functionality preserved and enhanced - **Visual feedback** consistent across all drag operations --- ## 📊 PROGRESS SUMMARY - **✅ Completed**: 14 files (Core framework + key presentation components) - **🚧 Needs Refactoring**: ~15-20 files (High and medium priority) - **📈 CSS Reduction**: ~85% reduction achieved in refactored files - **🎨 Consistency**: Semantic framework provides consistent design patterns - **⚡ Performance**: Reduced CSS bundle size and eliminated duplicates **Estimated Completion**: 2-3 sprints for high/medium priority items --- *Last Updated: September 28, 2025* *Framework Version: 1.0*