diff --git a/docs/DISCUSSIONS.md b/docs/DISCUSSIONS.md index 07bac34..1c5a867 100644 --- a/docs/DISCUSSIONS.md +++ b/docs/DISCUSSIONS.md @@ -5,6 +5,26 @@ Sorted by descending date (most recent first). --- +# Session: PERF — Lighthouse Score Improvements (CLS, Accessibility, SEO) +**Date:** 2026-05-07 +**Context and Problem to Solve** + +A production Lighthouse audit against `https://ecommerce.devoyager.cloud/` returned Performance 78/100, Accessibility 79/100, SEO 83/100, Best Practices 100/100. The Performance failure was driven entirely by CLS 0.602 — every other metric (FCP 0.4 s, LCP 0.5 s, TBT 0 ms) was already excellent. The CLS originated from the product list skeleton being structurally different from the loaded product grid (different column count, `h-80` fixed heights vs. `aspect-square` cards), causing a large height change when the async data resolved. Accessibility failures were icon-button labelling and insufficient contrast ratios. SEO failures were a missing meta description and `robots.txt` returning the SPA's `index.html` fallback. + +**Summary of Decisions** + +| Decision | Rationale | +|---|---| +| **Replace flat skeleton with card-shaped skeleton** | The original skeleton used `h-80` divs in a mismatched 4-column grid. When 8+ products loaded into a 4-col/3-col/2-col responsive grid with `aspect-square` image containers, the height jump caused CLS 0.602. The new skeleton uses the identical grid classes and card structure (aspect-square image placeholder, text stubs, button stub) so the height change on load is negligible. | +| **`` + WebP with PNG fallback** | Product images were served as PNG (up to 433 KB). Converting to WebP and wrapping in `` reduced transfer sizes by 92–95% (433 KB → 31 KB for the largest) without changing the `imageUrl` field in MongoDB. The `webpUrl()` helper in each component derives the `.webp` path from the `.png` URL; browsers without WebP support fall back to the PNG ``. | +| **`width`/`height` on `` tags** | Explicit intrinsic dimensions allow the browser to reserve space before the image response arrives, preventing any residual CLS from image-specific load timing. | +| **`h1` → `h2` in product-list** | The product-list component is embedded inside `home.html` which already has an `h1`. A second `h1` broke heading hierarchy on the home page. Changing to `h2` fixes the hierarchy on both the home page and the standalone `/products` route. | +| **`h3` → `h2` for "Description" in product-details** | The product name was `h1`; "Description" was `h3` with no intervening `h2`, triggering Lighthouse's heading-skip audit. | +| **`text-slate-400` → `text-slate-600` for footer and description label** | `text-slate-400` on white background has contrast ratio 2.63, below the WCAG AA minimum of 4.5:1. `text-slate-600` achieves ~5.9:1. | +| **`robots.txt` in `public/`** | Nginx was serving `index.html` for `/robots.txt` requests because no such file existed and the SPA fallback catches all unknown paths. A real `robots.txt` in `public/` is copied to the build output root and served directly. | + +--- + # Session: PERF — Cold Start Fix and Lighthouse Protocol **Date:** 2026-05-07 **Context and Problem to Solve** diff --git a/frontend/public/product-images/iphone-15.webp b/frontend/public/product-images/iphone-15.webp new file mode 100644 index 0000000..2a63b02 Binary files /dev/null and b/frontend/public/product-images/iphone-15.webp differ diff --git a/frontend/public/product-images/macbook-pro-14-m3.webp b/frontend/public/product-images/macbook-pro-14-m3.webp new file mode 100644 index 0000000..07aed4f Binary files /dev/null and b/frontend/public/product-images/macbook-pro-14-m3.webp differ diff --git a/frontend/public/product-images/samsung-galaxy-s24-ultra.webp b/frontend/public/product-images/samsung-galaxy-s24-ultra.webp new file mode 100644 index 0000000..0099980 Binary files /dev/null and b/frontend/public/product-images/samsung-galaxy-s24-ultra.webp differ diff --git a/frontend/public/robots.txt b/frontend/public/robots.txt new file mode 100644 index 0000000..c2a49f4 --- /dev/null +++ b/frontend/public/robots.txt @@ -0,0 +1,2 @@ +User-agent: * +Allow: / diff --git a/frontend/src/app/app.html b/frontend/src/app/app.html index 3225cf2..1725fb1 100644 --- a/frontend/src/app/app.html +++ b/frontend/src/app/app.html @@ -138,7 +138,7 @@