Background
PurgeCSS has been on and off in this repo:
- cb3b511 added the
astro-purgecss integration.
- 14d7d58 (Oct 2024) removed it "for now because of the
:where() bug" — PurgeCSS mis-handled selectors inside :where()/:is(), stripping rules that were actually used.
- 75ed7fa later updated purgecss to fix a Netlify build error; it has since been removed from dependencies entirely (see
agents/pitfalls.md → PurgeCSS).
The bug may be fixed in current PurgeCSS releases. Worth re-evaluating: the framework ships a lot of generated CSS the docs site never uses (24-col grid selectors, the full spacing-helper matrix — and the responsive helpers issue adds more), so real size savings are on the table.
Investigation plan
-
Check upstream: review PurgeCSS releases/changelog since v6 and the issue tracker for :where()/:is() selector extraction fixes; check astro-purgecss compatibility with Astro 6.
-
Spike on a branch:
- Add latest
astro-purgecss + purgecss, build.
- Selector-inventory diff: extract the selector list from the built CSS with and without purge and diff them — specifically confirm survivors include the
:where(h1, h2, h3):has(+ :is(h2, h3, h4)) pattern (elements.text.css:186) and friends. This is the regression test for the original bug.
- Confirm
@layer blocks and @custom-media-derived media queries pass through intact.
-
Build the safelist (per agents/pitfalls.md, these are known purge victims):
- Grid attribute selectors:
[col="…"], [span…] (global.grid.css).
- JS-toggled state classes:
is-active, is-paused, is-* (hero slideshow, theme toggle, header).
- Helpers used only in MDX content (content may not be scanned depending on config — verify
content globs include src/content/**/*.mdx and built HTML).
aria-current, data-* attribute selectors, theme classes on <html>.- Future: responsive helper suffixes (
/-(sm|md|lg)$/).
-
Measure: report built CSS size (raw + gzip) before/after. If savings are marginal (<~15%), recommend closing as not-worth-the-safelist-maintenance.
-
Verify & land: visual pass over home, docs, components, blog, demos in light + dark themes; if adopted, update agents/pitfalls.md (rewrite the PurgeCSS entry as "enabled, here's the safelist policy") and document the safelist location.
Origin
Split out of the responsive-helpers work (#9): the acceptable size of the helper set depends directly on whether unused CSS gets purged.
Background
PurgeCSS has been on and off in this repo:
astro-purgecssintegration.:where()bug" — PurgeCSS mis-handled selectors inside:where()/:is(), stripping rules that were actually used.agents/pitfalls.md→ PurgeCSS).The bug may be fixed in current PurgeCSS releases. Worth re-evaluating: the framework ships a lot of generated CSS the docs site never uses (24-col grid selectors, the full spacing-helper matrix — and the responsive helpers issue adds more), so real size savings are on the table.
Investigation plan
Check upstream: review PurgeCSS releases/changelog since v6 and the issue tracker for
:where()/:is()selector extraction fixes; checkastro-purgecsscompatibility with Astro 6.Spike on a branch:
astro-purgecss+purgecss, build.:where(h1, h2, h3):has(+ :is(h2, h3, h4))pattern (elements.text.css:186) and friends. This is the regression test for the original bug.@layerblocks and@custom-media-derived media queries pass through intact.Build the safelist (per
agents/pitfalls.md, these are known purge victims):[col="…"],[span…](global.grid.css).is-active,is-paused,is-*(hero slideshow, theme toggle, header).contentglobs includesrc/content/**/*.mdxand built HTML).aria-current,data-*attribute selectors, theme classes on<html>./-(sm|md|lg)$/).Measure: report built CSS size (raw + gzip) before/after. If savings are marginal (<~15%), recommend closing as not-worth-the-safelist-maintenance.
Verify & land: visual pass over home, docs, components, blog, demos in light + dark themes; if adopted, update
agents/pitfalls.md(rewrite the PurgeCSS entry as "enabled, here's the safelist policy") and document the safelist location.Origin
Split out of the responsive-helpers work (#9): the acceptable size of the helper set depends directly on whether unused CSS gets purged.