litlfred · litlfred · Oct 25, 2025 · Oct 24, 2025 · Oct 24, 2025 · Oct 24, 2025
diff --git a/IMAGE_OPTIMIZATION_GUIDE.md b/IMAGE_OPTIMIZATION_GUIDE.md
@@ -0,0 +1,237 @@
+# Image Optimization Guide
+
+## Table of Contents
+- [Overview](#overview)
+- [Summary](#summary)
+- [Generated Files](#generated-files)
+- [File Naming Convention](#file-naming-convention)
+- [Sample File Size Comparisons](#sample-file-size-comparisons)
+- [How It Works](#how-it-works)
+- [Regenerating Scaled Images](#regenerating-scaled-images)
+- [Technical Details](#technical-details)
+- [Performance Impact](#performance-impact)
+- [Original Files](#original-files)
+- [Browser Compatibility](#browser-compatibility)
+- [Testing](#testing)
+- [Troubleshooting](#troubleshooting)
+- [Future Improvements](#future-improvements)
+- [Related Files](#related-files)
+
+## Overview
+This guide documents the image optimization system implemented for SGeX Workbench to reduce file sizes and improve loading performance.
+
+## Summary
+Successfully generated scaled versions of PNG files over 200KB in the project. The original 37 large files were identified, and for each file we created both desktop (600px) and mobile (300px) versions, plus their dark theme variants, resulting in:
+- **Mobile**: ~93% file size reduction
+- **Desktop**: ~74% file size reduction
+
+## Generated Files
+- **Total scaled images**: 76 files
+  - 38 desktop versions (600px width) 
+  - 38 mobile versions (300px width)
+- All mobile versions are under 200KB ✅
+- Desktop versions range from 291KB to 580KB
+
+## File Naming Convention
+For each original image (e.g., `image.png`), the following versions are created:
+- `image_600.png` - Desktop version (600px width)
+- `image_300.png` - Mobile version (300px width)
+- `image_grey_tabby_600.png` - Desktop dark mode version
+- `image_grey_tabby_300.png` - Mobile dark mode version
+
+## Sample File Size Comparisons
+
+| File | Original | Desktop (600px) | Mobile (300px) | Desktop Savings | Mobile Savings |
+|------|----------|-----------------|----------------|-----------------|----------------|
+| sgex-mascot.png | 3.7MB | 380KB | 100KB | 89% | 97% |
+| authoring.png | 2.0MB | 564KB | 132KB | 72% | 93% |
+| collaboration.png | 2.0MB | 580KB | 144KB | 71% | 92% |
+| dak_interventions.png | 1.8MB | 528KB | 108KB | 71% | 94% |
+| pronunciation-guide.png | 3.7MB | 380KB | 100KB | 89% | 97% |
+
+## How It Works
+
+### Automatic Image Selection
+The `useThemeImage` hook (`src/hooks/useThemeImage.js`) automatically:
+1. Detects screen size (< 768px = mobile, >= 768px = desktop)
+2. Detects current theme (light/dark mode)
+3. Serves the appropriately scaled and themed image
+4. Responds to window resizes and theme changes
+
+### Browser Behavior
+- **Mobile screens (<768px)**: Loads 300px versions (~75-144KB each)
+- **Desktop screens (>=768px)**: Loads 600px versions (~291-580KB each)
+- **Dark mode**: Automatically uses `_grey_tabby` variants
+- **Retina displays**: 600px images remain sharp on high-DPI screens
+
+## Regenerating Scaled Images
+
+### When to Regenerate
+Regenerate scaled images when:
+- New PNG images are added to `public/` directory
+- Existing images are updated
+- Image quality needs adjustment
+
+### How to Regenerate
+
+1. **Install ImageMagick**:
+
+   **Ubuntu/Debian:**
+   ```bash
+   sudo apt-get install imagemagick
+   ```
+
+   **macOS (with Homebrew):**
+   ```bash
+   brew install imagemagick
+   ```
+
+   **Windows:**
+   Download and install from [ImageMagick website](https://imagemagick.org/script/download.php)
+
+2. **Run the generation script**:
+   ```bash
+   ./scripts/generate-scaled-images.sh
+   ```
+
+3. **Review the output** to ensure all images were processed correctly
+
+4. **Commit the new scaled images**:
+   ```bash
+   # Using git add with find command (works on all shells)
+   find public -name '*_300.png' -o -name '*_600.png' | xargs git add
+
+   # Or add all at once
+   git add public/
+
+   git commit -m "Regenerate scaled images"
+   ```
+
+### Customizing Image Sizes
+
+To change the target sizes, edit `scripts/generate-scaled-images.sh`:
+```bash
+DESKTOP_WIDTH=600   # Change this value for desktop size
+MOBILE_WIDTH=300    # Change this value for mobile size
+```
+
+## Technical Details
+
+### Image Generation Settings
+- **Tool**: ImageMagick
+- **Quality**: 85% compression
+- **Scaling**: Proportional (maintains aspect ratio)
+- **Format**: PNG with optimization
+
+### Code Implementation
+
+1. **Script**: `scripts/generate-scaled-images.sh`
+   - Finds all PNG files over 200KB
+   - Generates 600px and 300px versions
+   - Creates both light and dark theme variants
+   - Provides detailed output with file sizes
+
+2. **Hook**: `src/hooks/useThemeImage.js`
+   - Monitors screen size via `window.innerWidth`
+   - Listens for window resize events
+   - Observes theme changes via MutationObserver
+   - Returns appropriate image path
+
+### Component Usage
+Components use the hook like this:
+```javascript
+import useThemeImage from '../hooks/useThemeImage';
+
+const MyComponent = () => {
+  const imagePath = useThemeImage('my-image.png');
+  return <img src={imagePath} alt="My Image" />;
+};
+```
+
+The hook handles all the complexity of selecting the right image variant.
+
+## Performance Impact
+
+### Bandwidth Savings
+For a typical user viewing the DAK Dashboard with 9 component cards:
+- **Before**: ~14MB (9 cards × ~1.5MB average)
+- **After (Mobile)**: ~900KB (9 cards × ~100KB average)  
+- **After (Desktop)**: ~3.6MB (9 cards × ~400KB average)
+
+### Loading Time Improvements
+- **Mobile (3G)**: ~85 seconds → ~6 seconds (93% faster)
+- **Desktop (Cable)**: ~3 seconds → ~0.8 seconds (73% faster)
- **Mobile (3G)**: ~85 seconds → ~6 seconds (93% faster)
- **Desktop (Cable)**: ~3 seconds → ~0.8 seconds (73% faster)
+- **Mobile (3G)**: ~85 seconds → ~6 seconds (93% reduction in loading time, ~14x faster)
+- **Desktop (Cable)**: ~3 seconds → ~0.8 seconds (73% reduction in loading time, ~3.75x faster)
- **Mobile (3G)**: ~85 seconds → ~6 seconds (93% faster)
- **Desktop (Cable)**: ~3 seconds → ~0.8 seconds (73% faster)
+- **Mobile (3G)**: ~85 seconds → ~6 seconds (93% reduction in loading time, ~14x faster)
+- **Desktop (Cable)**: ~3 seconds → ~0.8 seconds (73% reduction in loading time, ~3.75x faster)
+
+## Original Files
+All original PNG files are retained in the repository for:
+- Future regeneration if needed
+- Reference for quality comparison
+- Archival purposes
+
+## Browser Compatibility
+The responsive image loading works on all modern browsers:
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Testing
+
+### Automated Tests
+Existing tests continue to work because:
+- Tests mock the `useThemeImage` hook
+- Mock returns test image paths
+- No changes needed to test files
+
+### Manual Testing Checklist
+To verify image optimization:
+- [ ] Open DevTools Network tab
+- [ ] Navigate to DAK Dashboard
+- [ ] Verify mobile versions load on small screens (<768px)
+- [ ] Verify desktop versions load on large screens (>=768px)
+- [ ] Toggle theme and verify `_grey_tabby` variants load
+- [ ] Check that images look sharp and clear
+- [ ] Resize window and verify images switch appropriately
+
+### Performance Testing
+To measure actual bandwidth savings:
+1. Clear browser cache
+2. Open DevTools Network tab
+3. Navigate to a page with many images
+4. Check total transferred data
+5. Compare with expected sizes
+
+## Troubleshooting
+
+### Images Not Loading
+If scaled images fail to load:
+1. Check browser console for 404 errors
+2. Verify scaled images exist in `public/` directory
+3. Run build and check `build/` directory for images
+4. Verify correct naming convention is used
+
+### Quality Issues
+If images appear blurry or pixelated:
+1. Adjust quality setting in generation script
+2. Increase target size (e.g., 800px for desktop)
+3. Regenerate images with new settings
+
+### Theme Switch Issues
+If dark mode images don't load:
+1. Verify `_grey_tabby` variants exist
+2. Check browser console for errors
+3. Test the `useThemeImage` hook directly
+
+## Future Improvements
+Potential enhancements:
+- [ ] Add WebP format support for better compression
+- [ ] Implement lazy loading for off-screen images
+- [ ] Add srcset/picture element support
+- [ ] Create automated CI/CD image optimization pipeline
+- [ ] Add visual regression testing
+
+## Related Files
+- `scripts/generate-scaled-images.sh` - Image generation script
+- `src/hooks/useThemeImage.js` - Responsive image selection hook
+- `public/*.png` - Original and scaled images
+- `.github/workflows/*.yml` - CI/CD configuration (future)
diff --git a/public/authoring_300.png b/public/authoring_300.png
diff --git a/public/authoring_600.png b/public/authoring_600.png
diff --git a/public/authoring_grey_tabby_300.png b/public/authoring_grey_tabby_300.png
diff --git a/public/authoring_grey_tabby_600.png b/public/authoring_grey_tabby_600.png
diff --git a/public/collaboration_300.png b/public/collaboration_300.png
diff --git a/public/collaboration_600.png b/public/collaboration_600.png
diff --git a/public/collaboration_grey_tabby_300.png b/public/collaboration_grey_tabby_300.png
diff --git a/public/collaboration_grey_tabby_600.png b/public/collaboration_grey_tabby_600.png
diff --git a/public/create_300.png b/public/create_300.png
diff --git a/public/create_600.png b/public/create_600.png
diff --git a/public/create_grey_tabby_300.png b/public/create_grey_tabby_300.png
diff --git a/public/create_grey_tabby_600.png b/public/create_grey_tabby_600.png
diff --git a/public/dashboard/dak_business_processes_300.png b/public/dashboard/dak_business_processes_300.png
diff --git a/public/dashboard/dak_business_processes_600.png b/public/dashboard/dak_business_processes_600.png
diff --git a/public/dashboard/dak_business_processes_grey_tabby_300.png b/public/dashboard/dak_business_processes_grey_tabby_300.png
diff --git a/public/dashboard/dak_business_processes_grey_tabby_600.png b/public/dashboard/dak_business_processes_grey_tabby_600.png
diff --git a/public/dashboard/dak_core_data_elements_300.png b/public/dashboard/dak_core_data_elements_300.png
diff --git a/public/dashboard/dak_core_data_elements_600.png b/public/dashboard/dak_core_data_elements_600.png
diff --git a/public/dashboard/dak_core_data_elements_grey_tabby_300.png b/public/dashboard/dak_core_data_elements_grey_tabby_300.png
diff --git a/public/dashboard/dak_core_data_elements_grey_tabby_600.png b/public/dashboard/dak_core_data_elements_grey_tabby_600.png
diff --git a/public/dashboard/dak_decision_support_logic_300.png b/public/dashboard/dak_decision_support_logic_300.png
diff --git a/public/dashboard/dak_decision_support_logic_600.png b/public/dashboard/dak_decision_support_logic_600.png
diff --git a/public/dashboard/dak_decision_support_logic_grey_tabby_300.png b/public/dashboard/dak_decision_support_logic_grey_tabby_300.png
diff --git a/public/dashboard/dak_decision_support_logic_grey_tabby_600.png b/public/dashboard/dak_decision_support_logic_grey_tabby_600.png
diff --git a/public/dashboard/dak_indicators_300.png b/public/dashboard/dak_indicators_300.png
diff --git a/public/dashboard/dak_indicators_600.png b/public/dashboard/dak_indicators_600.png
diff --git a/public/dashboard/dak_indicators_grey_tabby_300.png b/public/dashboard/dak_indicators_grey_tabby_300.png
diff --git a/public/dashboard/dak_indicators_grey_tabby_600.png b/public/dashboard/dak_indicators_grey_tabby_600.png
diff --git a/public/dashboard/dak_interventions_300.png b/public/dashboard/dak_interventions_300.png
diff --git a/public/dashboard/dak_interventions_600.png b/public/dashboard/dak_interventions_600.png
diff --git a/public/dashboard/dak_interventions_grey_tabby_300.png b/public/dashboard/dak_interventions_grey_tabby_300.png
diff --git a/public/dashboard/dak_interventions_grey_tabby_600.png b/public/dashboard/dak_interventions_grey_tabby_600.png
diff --git a/public/dashboard/dak_personas_300.png b/public/dashboard/dak_personas_300.png
diff --git a/public/dashboard/dak_personas_600.png b/public/dashboard/dak_personas_600.png
diff --git a/public/dashboard/dak_personas_grey_tabby_300.png b/public/dashboard/dak_personas_grey_tabby_300.png
diff --git a/public/dashboard/dak_personas_grey_tabby_600.png b/public/dashboard/dak_personas_grey_tabby_600.png
diff --git a/public/dashboard/dak_requirements_300.png b/public/dashboard/dak_requirements_300.png
diff --git a/public/dashboard/dak_requirements_600.png b/public/dashboard/dak_requirements_600.png
diff --git a/public/dashboard/dak_requirements_grey_tabby_300.png b/public/dashboard/dak_requirements_grey_tabby_300.png
diff --git a/public/dashboard/dak_requirements_grey_tabby_600.png b/public/dashboard/dak_requirements_grey_tabby_600.png
diff --git a/public/dashboard/dak_testing_300.png b/public/dashboard/dak_testing_300.png
diff --git a/public/dashboard/dak_testing_600.png b/public/dashboard/dak_testing_600.png
diff --git a/public/dashboard/dak_testing_grey_tabby_300.png b/public/dashboard/dak_testing_grey_tabby_300.png
diff --git a/public/dashboard/dak_testing_grey_tabby_600.png b/public/dashboard/dak_testing_grey_tabby_600.png
diff --git a/public/dashboard/dak_user_scenarios_300.png b/public/dashboard/dak_user_scenarios_300.png
diff --git a/public/dashboard/dak_user_scenarios_600.png b/public/dashboard/dak_user_scenarios_600.png
diff --git a/public/dashboard/dak_user_scenarios_grey_tabby_300.png b/public/dashboard/dak_user_scenarios_grey_tabby_300.png
diff --git a/public/dashboard/dak_user_scenarios_grey_tabby_600.png b/public/dashboard/dak_user_scenarios_grey_tabby_600.png
diff --git a/public/editing_300.png b/public/editing_300.png
diff --git a/public/editing_600.png b/public/editing_600.png
diff --git a/public/editing_grey_tabby_300.png b/public/editing_grey_tabby_300.png
diff --git a/public/editing_grey_tabby_600.png b/public/editing_grey_tabby_600.png
diff --git a/public/expirement_300.png b/public/expirement_300.png
diff --git a/public/expirement_600.png b/public/expirement_600.png
diff --git a/public/expirement_grey_tabby_300.png b/public/expirement_grey_tabby_300.png
diff --git a/public/expirement_grey_tabby_600.png b/public/expirement_grey_tabby_600.png
diff --git a/public/forking_300.png b/public/forking_300.png
diff --git a/public/forking_600.png b/public/forking_600.png
diff --git a/public/forking_grey_tabby_300.png b/public/forking_grey_tabby_300.png
diff --git a/public/forking_grey_tabby_600.png b/public/forking_grey_tabby_600.png
diff --git a/public/logo512_300.png b/public/logo512_300.png
diff --git a/public/logo512_600.png b/public/logo512_600.png
diff --git a/public/logo512_grey_tabby_300.png b/public/logo512_grey_tabby_300.png
diff --git a/public/logo512_grey_tabby_600.png b/public/logo512_grey_tabby_600.png
diff --git a/public/pat-login_300.png b/public/pat-login_300.png
diff --git a/public/pat-login_600.png b/public/pat-login_600.png
diff --git a/public/pat-login_grey_tabby_300.png b/public/pat-login_grey_tabby_300.png
diff --git a/public/pat-login_grey_tabby_600.png b/public/pat-login_grey_tabby_600.png
diff --git a/public/pronunciation-guide_300.png b/public/pronunciation-guide_300.png
diff --git a/public/pronunciation-guide_600.png b/public/pronunciation-guide_600.png
diff --git a/public/pronunciation-guide_grey_tabby_300.png b/public/pronunciation-guide_grey_tabby_300.png
diff --git a/public/pronunciation-guide_grey_tabby_600.png b/public/pronunciation-guide_grey_tabby_600.png
diff --git a/public/sgex-mascot_300.png b/public/sgex-mascot_300.png
diff --git a/public/sgex-mascot_600.png b/public/sgex-mascot_600.png
diff --git a/public/sgex-mascot_grey_tabby_300.png b/public/sgex-mascot_grey_tabby_300.png
diff --git a/public/sgex-mascot_grey_tabby_600.png b/public/sgex-mascot_grey_tabby_600.png
diff --git a/scripts/generate-scaled-images.sh b/scripts/generate-scaled-images.sh
@@ -0,0 +1,120 @@
+#!/bin/bash
+
+# Script to generate scaled versions of large PNG images for desktop and mobile
+# Usage: ./scripts/generate-scaled-images.sh
+
+set -e -o pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo "🖼️  Generating scaled image versions..."
+echo ""
+
+# Target sizes
+DESKTOP_WIDTH=600   # For desktop displays (retina-ready at ~300px display)
+MOBILE_WIDTH=300    # For mobile displays (~150px display)
+
+# Counter for processed images
+processed=0
+skipped=0
+errors=0
+
+# Find all PNG files larger than 200KB and store in array
+mapfile -t png_files < <(find public -name "*.png" -size +200k -type f | sort)
-mapfile -t png_files < <(find public -name "*.png" -size +200k -type f | sort)
+png_files=()
+while IFS= read -r file; do
+    png_files+=("$file")
+done < <(find public -name "*.png" -size +200k -type f | sort)
-mapfile -t png_files < <(find public -name "*.png" -size +200k -type f | sort)
+png_files=()
+while IFS= read -r file; do
+    png_files+=("$file")
+done < <(find public -name "*.png" -size +200k -type f | sort)
+
+# Process each file
+for original_file in "${png_files[@]}"; do
+    # Get file size in KB for reporting
+    file_size=$(du -k "$original_file" | cut -f1)
+
+    # Extract directory, filename without extension, and extension
+    dir=$(dirname "$original_file")
+    filename=$(basename "$original_file")
+    name="${filename%.*}"
+    ext="${filename##*.}"
+
+    # Skip if this is already a scaled version
+    if [[ "$name" =~ _[0-9]+$ ]]; then
+        echo -e "${YELLOW}⏭️  Skipping already scaled: $filename${NC}"
+        skipped=$((skipped + 1))
+        continue
+    fi
+
+    echo -e "${GREEN}📐 Processing: $original_file (${file_size}KB)${NC}"
+
+    # Get original dimensions
+    dimensions=$(identify -format "%wx%h" "$original_file")
+    echo "   Original size: $dimensions"
+
+    # Generate desktop version (600px width)
+    desktop_file="${dir}/${name}_600.${ext}"
+    if [ -f "$desktop_file" ]; then
+        echo "   ⏭️  Desktop version already exists: $desktop_file"
+    else
+        echo "   🖥️  Creating desktop version (${DESKTOP_WIDTH}px wide)..."
+        convert "$original_file" -resize "${DESKTOP_WIDTH}x" -quality 85 "$desktop_file"
+        desktop_size=$(du -k "$desktop_file" | cut -f1)
+        echo "   ✅ Created: $desktop_file (${desktop_size}KB)"
+    fi
+
+    # Generate mobile version (300px width)
+    mobile_file="${dir}/${name}_300.${ext}"
+    if [ -f "$mobile_file" ]; then
+        echo "   ⏭️  Mobile version already exists: $mobile_file"
+    else
+        echo "   📱 Creating mobile version (${MOBILE_WIDTH}px wide)..."
+        convert "$original_file" -resize "${MOBILE_WIDTH}x" -quality 85 "$mobile_file"
+        mobile_size=$(du -k "$mobile_file" | cut -f1)
+        echo "   ✅ Created: $mobile_file (${mobile_size}KB)"
+    fi
+
+    echo ""
+    processed=$((processed + 1))
+done
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo -e "${GREEN}✨ Complete!${NC}"
+echo "   Processed: $processed images"
+echo "   Skipped: $skipped images"
+if [ $errors -gt 0 ]; then
+    echo -e "   ${RED}Errors: $errors${NC}"
+fi
+echo ""
+echo "📊 Generating size report..."
+
+# Generate a report of file sizes
+echo ""
+echo "Original vs Scaled Sizes:"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+find public -name "*.png" -size +200k -type f | while read -r file; do
+    dir=$(dirname "$file")
+    filename=$(basename "$file")
+    name="${filename%.*}"
+    ext="${filename##*.}"
+
+    # Skip already scaled versions
+    if [[ "$name" =~ _[0-9]+$ ]]; then
+        continue
+    fi
+
+    orig_size=$(du -h "$file" | cut -f1)
+    desktop_file="${dir}/${name}_600.${ext}"
+    mobile_file="${dir}/${name}_300.${ext}"
+
+    if [ -f "$desktop_file" ] && [ -f "$mobile_file" ]; then
+        desktop_size=$(du -h "$desktop_file" | cut -f1)
+        mobile_size=$(du -h "$mobile_file" | cut -f1)
+        echo "📄 $filename:"
+        echo "   Original: $orig_size"
+        echo "   Desktop (600px): $desktop_size"
+        echo "   Mobile (300px): $mobile_size"
+        echo ""
+    fi
+done
+
+echo "✅ All scaled images have been generated!"