Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Design-system CSS metrics count engine-generated CSS as source CSS

Open
  • Is something wrong?
#2,967 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
28/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
php, wordpress
Domain
tooling

Research direction

Start in WordPressSitePlan::uniqueSourceCssBytes(), which currently dedupes compiled CSS assets by source_hash and skips only source: engine-support. The fix moves measurement to the input artifact: sum unique author CSS files and unique inline style blocks, then carry the total in the compiled-site envelope as source_css_bytes. Done means a fixture with per-page copies, shared chrome and editor static state reports the input artifact's unique author CSS bytes, and the Modus ratio falls within 5% of the on-disk measurement. The tagging of generated assets needs a design decision first, so check with the maintainers before starting.

Written by the indexing model from the issue text.

Description

Problem

design_system.metrics.unique_source_css_bytes is supposed to measure the author's captured CSS, with each stylesheet counted once. It currently counts engine-generated CSS as source, so generated_to_source_css_ratio understates how much CSS the theme adds by about 16x.

Evidence (Modus Digital, built from #2966 at 0a89e9f4d)

Metric Measured
Theme CSS theme_css_bytes 2,909,287 2,762,159 bytes across 123 .css files on disk
Author source CSS unique_source_css_bytes 2,316,551 about 134 KB: 128,264 bytes in 4 unique captured stylesheets plus 6,250 bytes in 3 unique inline <style> blocks
Ratio generated_to_source_css_ratio 1.26 about 20

Root cause

WordPressSitePlan::uniqueSourceCssBytes() adds up the compiled CSS assets, deduplicated by source_hash, and excludes only source: engine-support. Several engine-generated outputs have no engine-support tag and carry their own hash, so each one counts as source:

  • shared-chrome-*.css (12 files);
  • editor-static-state-*.css and engine-support-after-author-*.css (27 files);
  • per-route inline extractions (blog/*.inline-N.css, 66 files);
  • per-page stylesheet projections (styles-*.page-*.css, up to 773 KB each).

Proposal

Measure source CSS from the input artifact before compilation, rather than from compiled assets:

  • add up the CSS files, deduplicated by content hash;
  • add the inline <style> blocks, deduplicated by content hash;
  • carry the total in the compiled-site envelope (for example source_css_bytes) for the site plan to report.

Engine CSS then becomes theme_css_bytes minus the bytes projected from author CSS. That needs one tag on every generated asset, saying whether it is author-derived or engine-owned.

Acceptance

  • On a fixture with per-page copies, shared chrome and editor static state, unique_source_css_bytes equals the input artifact's unique author CSS bytes.
  • The Modus import reports a ratio within 5% of the on-disk measurement.

AI disclosure: Claude (Opus) in the Pi coding agent, via Roadie, measured the import and drafted this issue at Chris Huber's direction.

Dominant language
PHP
Stars
21
Forks
2
Avg merge
8h 35m
Merged PRs (30d)
659

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Automattic/blocks-engine

All issues in Automattic/blocks-engine

Similar issues

More PHP issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.