Remove Unused CSS (RUCSS) #9

New Issue

2026-09-13T07:25:08Z

kevin.bataille commented

2026-09-13 07:25:08 +00:00

Problem Statement

Pages contain CSS rules that are not used for that specific page. This wastes bandwidth and slows down rendering.

Solution

Analyze each page to identify used CSS rules, generate a trimmed stylesheet containing only used rules, and serve that instead of the full stylesheet.

User Stories

As a site owner, I want unused CSS removed from pages, so that page weight is reduced
As a site owner, I want the process to be automatic, so that I don't have to manually identify unused CSS
As a site owner, I want to exclude specific CSS files from RUCSS, so that dynamic styles are preserved
As a site owner, I want to see how much CSS was removed, so that I can verify the optimization
As a site owner, I want the used CSS to be cached per page, so that analysis doesn't happen on every load
As a site owner, I want to regenerate used CSS when content changes, so that it stays accurate
As a site owner, I want to manually trigger RUCSS for specific pages, so that I can force regeneration
As a site owner, I want RUCSS to work with external stylesheets, so that CDN resources are handled
As a site owner, I want fallback behavior if analysis fails, so that the site still works
As a site owner, I want to see which selectors were kept, so that I can debug issues

Implementation Decisions

CSS analysis via parser to identify selectors used in HTML
HTML parsing to find matching selectors
Used CSS cached in filesystem per URL
Background processing for analysis
Fallback to original CSS on failure
Exclusion list stored in settings

Testing Decisions

Test unused CSS is removed
Test used CSS is preserved
Test excluded files are not modified
Test used CSS is cached
Test regeneration works
Test fallback on failure
Test with external stylesheets

Out of Scope

Critical CSS generation (separate issue)
CSS minification/combination (separate issue)

Further Notes

RUCSS is computationally expensive. Consider background processing and caching.

## Problem Statement Pages contain CSS rules that are not used for that specific page. This wastes bandwidth and slows down rendering. ## Solution Analyze each page to identify used CSS rules, generate a trimmed stylesheet containing only used rules, and serve that instead of the full stylesheet. ## User Stories 1. As a site owner, I want unused CSS removed from pages, so that page weight is reduced 2. As a site owner, I want the process to be automatic, so that I don't have to manually identify unused CSS 3. As a site owner, I want to exclude specific CSS files from RUCSS, so that dynamic styles are preserved 4. As a site owner, I want to see how much CSS was removed, so that I can verify the optimization 5. As a site owner, I want the used CSS to be cached per page, so that analysis doesn't happen on every load 6. As a site owner, I want to regenerate used CSS when content changes, so that it stays accurate 7. As a site owner, I want to manually trigger RUCSS for specific pages, so that I can force regeneration 8. As a site owner, I want RUCSS to work with external stylesheets, so that CDN resources are handled 9. As a site owner, I want fallback behavior if analysis fails, so that the site still works 10. As a site owner, I want to see which selectors were kept, so that I can debug issues ## Implementation Decisions - CSS analysis via parser to identify selectors used in HTML - HTML parsing to find matching selectors - Used CSS cached in filesystem per URL - Background processing for analysis - Fallback to original CSS on failure - Exclusion list stored in settings ## Testing Decisions - Test unused CSS is removed - Test used CSS is preserved - Test excluded files are not modified - Test used CSS is cached - Test regeneration works - Test fallback on failure - Test with external stylesheets ## Out of Scope - Critical CSS generation (separate issue) - CSS minification/combination (separate issue) ## Further Notes RUCSS is computationally expensive. Consider background processing and caching.

kevin.bataille added the phase-4 label 2026-09-13 07:29:01 +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#9