| name | performance-cwv |
| description | Web performance and Core Web Vitals (LCP, INP, CLS) in TryRamadan. Covers critical path, lazy loading, images/fonts, and layout stability. Use when changing above-the-fold content, images, fonts, or heavy components on the main route. |
Performance and Core Web Vitals (TryRamadan)
Use this skill when changing critical path, images, fonts, or layout so LCP, INP, and CLS stay within targets.
1. Goals
- LCP (Largest Contentful Paint): < 2.5s — hero and main content visible quickly.
- INP (Interaction to Next Paint): < 200ms — buttons and inputs feel responsive.
- CLS (Cumulative Layout Shift): < 0.1 — no visible layout jumps.
Doc: docs/PERFORMANCE.md (critical path, checklist, measure).
2. Critical path and lazy loading
- Entry:
main.tsx → App.tsx → index.css. Dashboard sub-pages (Schedule, Meals, Progress, Culture, Quran, Macros) are lazy-loaded; home and Dashboard remain in main bundle.
- Heavy components off critical path: FastingBottomBar, AdhanScheduler, ReminderScheduler not mounted until onboarding complete or on dashboard. Avoid mounting them on every page.
- Timers: Countdown/timer intervals throttled (e.g. 2s) where appropriate to reduce main-thread work (INP).
- Cache-first APIs: Prayer times and location use cache-first; defer initial fetch with requestIdleCallback when possible (see timezone-and-countdown and offline-and-degraded-network skills).
3. Images and fonts
- LCP image: Hero image with explicit
width/height, fetchpriority="high", decoding="async". Preload from HTML when URL is known.
- Below-the-fold:
loading="lazy" and explicit dimensions or aspect-ratio.
- Fonts: No
@import in CSS; use <link rel="preload"> or font-display strategy so font load does not block first paint.
4. Layout stability (CLS)
- Reserve space for dynamic content (timer, cards) with
min-height or explicit dimensions so layout doesn’t shift when data arrives.
- Use skeletons/placeholders with fixed height for loading states.
- Measure:
reportWebVitals() in main.tsx; plug in RUM (e.g. Vercel Analytics) via callback for production.
5. Checklist for changes