Critical CSS Generation #5

New Issue

2026-09-13T07:24:00Z

kevin.bataille commented

2026-09-13 07:24:00 +00:00

Problem Statement

External CSS files block rendering until they load. Critical above-the-fold content is delayed by non-critical styles.

Solution

Generate critical CSS for above-the-fold content, inline it in the head, and defer loading of the full stylesheet.

User Stories

As a site owner, I want to generate critical CSS automatically, so that above-the-fold content renders quickly
As a site owner, I want critical CSS inlined in the head, so that it is available immediately
As a site owner, I want the full stylesheet deferred, so that it loads after first paint
As a site owner, I want per-page critical CSS, so that each page has optimal loading
As a site owner, I want to regenerate critical CSS when content changes, so that it stays accurate
As a site owner, I want to exclude pages from critical CSS generation, so that I have control
As a site owner, I want to see generated critical CSS, so that I can verify it is correct
As a site owner, I want fallback behavior when generation fails, so that the site still works
As a site owner, I want critical CSS generation to work with any theme, so that compatibility is maintained
As a site owner, I want to manually regenerate critical CSS, so that I can force updates

Implementation Decisions

Critical CSS generation via CSS parser analysis
Identify above-the-fold selectors from viewport height
Inline critical CSS in a style tag in the head
Defer full stylesheet via media="print" onload pattern
Cache generated critical CSS per page
Background regeneration via WordPress cron

Testing Decisions

Test critical CSS is generated for pages
Test critical CSS is inlined in head
Test full stylesheet is deferred
Test per-page critical CSS varies by page
Test regeneration on content change
Test fallback when generation fails

Out of Scope

CSS minification/combination (separate issue)
Remove unused CSS (separate issue)

Further Notes

Critical CSS should work independently of other CSS optimization features.

## Problem Statement External CSS files block rendering until they load. Critical above-the-fold content is delayed by non-critical styles. ## Solution Generate critical CSS for above-the-fold content, inline it in the head, and defer loading of the full stylesheet. ## User Stories 1. As a site owner, I want to generate critical CSS automatically, so that above-the-fold content renders quickly 2. As a site owner, I want critical CSS inlined in the head, so that it is available immediately 3. As a site owner, I want the full stylesheet deferred, so that it loads after first paint 4. As a site owner, I want per-page critical CSS, so that each page has optimal loading 5. As a site owner, I want to regenerate critical CSS when content changes, so that it stays accurate 6. As a site owner, I want to exclude pages from critical CSS generation, so that I have control 7. As a site owner, I want to see generated critical CSS, so that I can verify it is correct 8. As a site owner, I want fallback behavior when generation fails, so that the site still works 9. As a site owner, I want critical CSS generation to work with any theme, so that compatibility is maintained 10. As a site owner, I want to manually regenerate critical CSS, so that I can force updates ## Implementation Decisions - Critical CSS generation via CSS parser analysis - Identify above-the-fold selectors from viewport height - Inline critical CSS in a style tag in the head - Defer full stylesheet via media="print" onload pattern - Cache generated critical CSS per page - Background regeneration via WordPress cron ## Testing Decisions - Test critical CSS is generated for pages - Test critical CSS is inlined in head - Test full stylesheet is deferred - Test per-page critical CSS varies by page - Test regeneration on content change - Test fallback when generation fails ## Out of Scope - CSS minification/combination (separate issue) - Remove unused CSS (separate issue) ## Further Notes Critical CSS should work independently of other CSS optimization features.

kevin.bataille added the phase-2 label 2026-09-13 07:28:54 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: kevin.bataille/wp-recache#5