This file extends common/performance.md with web-specific performance content.

Web Performance Rules

Core Web Vitals Targets

Bundle Budget

Loading Strategy

1. Inline critical above-the-fold CSS where justified
2. Preload the hero image and primary font only
3. Defer non-critical CSS or JS
4. Dynamically import heavy libraries

const gsapModule = await import('gsap');
const { ScrollTrigger } = await import('gsap/ScrollTrigger');

Image Optimization

• Explicit width and height
• loading="eager" plus fetchpriority="high" for hero media only
• loading="lazy" for below-the-fold assets
• Prefer AVIF or WebP with fallbacks
• Never ship source images far beyond rendered size

Font Loading

• Max two font families unless there is a clear exception
• font-display: swap
• Subset where possible
• Preload only the truly critical weight/style

Animation Performance

• Animate compositor-friendly properties only
• Use will-change narrowly and remove it when done
• Prefer CSS for simple transitions
• Use requestAnimationFrame or established animation libraries for JS motion
• Avoid scroll handler churn; use IntersectionObserver or well-behaved libraries

Performance Checklist

• All images have explicit dimensions
• No accidental render-blocking resources
• No layout shifts from dynamic content
• Motion stays on compositor-friendly properties
• Third-party scripts load async/defer and only when needed