css-render-blocking-diagnosis

CSS Render-Blocking Diagnosis & Resolution

APPLY: EVERY PERFORMANCE QUERY - PRIMARY DIAGNOSTIC RULE

Critical Learning from 98 PageSpeed Achievement

This rule documents the breakthrough that achieved 98-91 PageSpeed scores by solving CSS render-blocking bottlenecks.

Primary Diagnostic Protocol

Step 1: CSS Blocking Symptom Recognition

IMMEDIATE RED FLAGS requiring CSS investigation:

• LCP > 3 seconds with white screen pattern
• Body/content delayed despite JavaScript optimizations
• Performance scores stuck at 80-85 despite component work
• Render delay >70% in LCP performance breakdown
• "Body doesn't show until late" user complaints

Step 2: CSS Loading Sequence Audit

Check these patterns in loading order:

# 1. Confirm body hiding pattern (correct)
grep -r "body.*display.*none" head.html

# 2. Find CSS loading mechanism (potential issue)
grep -r "createElement.*link" scripts.js
grep -r "stylesheet" scripts.js

# 3. Check CSS file sizes (>20KB = likely blocking)
ls -la */styles/styles.css

Step 3: Root Cause Confirmation

Render-blocking CSS anti-pattern:

// ❌ PROBLEM: Large CSS via JavaScript = render blocking
(function loadStyles() {
  const paths = [`${miloLibs}/styles/styles.css`]; // 27KB file
  paths.forEach((path) => {
    const link = document.createElement('link');
    link.setAttribute('rel', 'stylesheet');
    link.setAttribute('href', path); // BLOCKS body visibility
    document.head.appendChild(link);
  });
}());

The Solution Implementation

Phase E: Optimize Block Loading Speed

// ✅ SOLUTION: Focus on LCP element structure creation speed
// Following AEM Three-Phase Loading principles
export default async function init(el) {
  // Phase 1: Create LCP structure synchronously (REQUIRED for performance)
  const lcpContent = createBasicStructure(el);
  el.append(lcpContent);
  
  // Phase 2: CSS loading optimized for AEM transformation phases
  // body { display: none; } stays until data-block-status="loaded"
  
  return lcpContent; // Return immediately for LCP measurement
}