mmainguy/slideshare
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1a3b096cf9
slideshare/RESTYLE.md

10 KiB
Raw Blame History

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