diff --git a/docs/03-metrics-reference.md b/docs/03-metrics-reference.md new file mode 100644 index 0000000..94c5682 --- /dev/null +++ b/docs/03-metrics-reference.md @@ -0,0 +1,326 @@ +# Performance Metrics Reference + +Deep-dive reference for each Core Web Vital metric captured by the seo-intel system. + +## The Five Metrics + +| Metric | Full Name | Unit | Good | Poor | What Matters | +|--------|-----------|------|------|------|--------------| +| **LCP** | Largest Contentful Paint | milliseconds | ≤2,500ms | ≥4,000ms | When main content appears | +| **FCP** | First Contentful Paint | milliseconds | ≤1,800ms | ≥3,000ms | When ANY content appears | +| **CLS** | Cumulative Layout Shift | unitless (0-1) | ≤0.1 | ≥0.25 | How much page jumps | +| **TBT** | Total Blocking Time | milliseconds | ≤200ms | ≥600ms | JS blocking interactions | +| **TTFB** | Time to First Byte | milliseconds | ≤800ms | ≥1,800ms | Server response speed | + +--- + +## 1. LCP — Largest Contentful Paint + +### Definition +The time when the **largest visible element** (image, heading, paragraph block, video) appears on screen. + +### Why It Matters +Users need to see that the page is loading. LCP is the best metric for "when does the user perceive the page is starting to load?" + +### Thresholds +- **≤ 2.5 seconds:** Good — user feels the page is responding +- **2.5 – 4.0 seconds:** Needs improvement +- **≥ 4.0 seconds:** Poor — user thinks the page is slow/broken + +### What Affects LCP +1. **Server response time (TTFB)** — If the server is slow, everything downstream is slow +2. **Large images/videos above the fold** — Unoptimized media delays LCP +3. **Render-blocking JavaScript** — `