248 lines
10 KiB
Markdown
248 lines
10 KiB
Markdown
# 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*
|