Required Plugins

Superpowers plugin: MUST be active for all work using this skill. Use throughout the entire build pipeline — design decisions, code generation, debugging, quality checks, and any task where it offers enhanced capabilities. If superpowers provides a better way to accomplish something, prefer it over the default approach.

Frontend Design plugin (webapp-gui-design): MUST be active for all visual output from this skill. Use for design system work, component styling, layout decisions, colour selection, typography, responsive design, and visual QA.

Image Compression

Seamless image compression prior to upload with a hybrid approach:

• Client primary: Squoosh (WASM)
• Client fallback: Canvas API
• Server safety net: Sharp

Defaults: max width $1920$px, max size $512$ KB, quality $75$ (adjust down to hit size).

When to Use

✅ Web apps that upload user images and must reduce bandwidth ✅ Need transparent UX (no user action) ✅ Want modern codecs but must support older browsers

When Not to Use

❌ Server-only batch pipelines (use Sharp directly) ❌ Large-scale media processing with complex transforms (use ImageMagick/FFmpeg)

Core Rules

1. Maintain aspect ratio; never upscale.
2. Target max width $1920$px and max size $512$ KB.
3. Start at quality $75$; reduce in steps to meet size.
4. Prefer JPEG for compatibility; try WebP if size remains too large.
5. Log compression stats (ratio, saved, processing time).

Decision Flow

1. Client attempt (Squoosh)
   • Resize → compress → check size.
   • Decrease quality until size limit met.
   • If still too large, try WebP.
2. Client fallback (Canvas)
   • Resize → toBlob JPEG → reduce quality if needed.
3. Server fallback (Sharp)
   • Always validate size/dimensions server-side.
   • Re-compress if client output exceeds limits.

Implementation Steps (High Level)

1. Client compression service
   • Expose compressImage(file, options).
   • Use Squoosh with dynamic import.
   • Fallback to Canvas on error.
2. Upload hook / handler
   • Validate input is image.
   • Compress transparently.
   • Upload compressed blob.
3. Server middleware
   • Use Sharp to enforce limits.
   • Return 413 if still too large.
   • Attach compression stats to logs.

Required Defaults

• maxWidth: 1920
• maxHeight: 1920
• maxSize: $512 * 1024$
• quality: 75
• minDimensions: 200x200 (server-side)

Anti-Patterns

• ❌ Skipping server validation
• ❌ Uploading original file on failure without logging
• ❌ Enlarging images
• ❌ Using blocking UI (must be transparent to user)

References (Load as Needed)

• Client implementation: references/client.md
• Client usage example: references/client-usage.md
• Server middleware + routes: references/server.md
• Storage adapters (S3/local): references/storage.md
• Security checks: references/security.md
• Monitoring & analytics: references/monitoring.md
• Performance targets: references/performance.md
• Quality examples: references/quality-metrics.md
• Environment variables: references/env.md
• Docker (Sharp): references/docker.md
• Implementation checklist: references/implementation-checklist.md

Output Expectations

• Client compression completes in $100$–$500$ ms typical
• Server compression $50$–$200$ ms typical
• Bandwidth reduction $85$–$97%$

Checklist

• Client: Squoosh primary + Canvas fallback
• Client: size/dimension limits enforced
• Server: Sharp validation + compression
• Logging: compression stats & processing time
• Storage: image saved with metadata
• Tests: JPEG/PNG/WebP, large images, mobile