Skip to content

Provide style.min.css for production - #61

Merged
MaggieCabrera merged 9 commits into
WordPress:trunkfrom
josephscott:minify-style-css
Nov 9, 2026
Merged

MaggieCabrera merged 9 commits into
WordPress:trunkfrom
josephscott:minify-style-css

Conversation

@josephscott

Copy link
Copy Markdown
Contributor

Using the same pattern as the TT5 theme - https://themes.trac.wordpress.org/browser/twentytwentyfive/1.5/package.json - this change adds a style.min.css and the tooling around it to build it.

The style.css file would still be used any time that SCRIPT_DEBUG is true - which is the case for the wp-env setup used by Ipsum. Production setups would get the benefit of using the smaller style.min.css file.

For sizes, style.min.css comes in at 3,354 bytes. Down from the 9,380 bytes of style.css. Here are a few quick compression numbers:

  • gzip -5 style.min.css : 1,134 bytes
  • brotli -5 style.min.css : 996 bytes
  • zstd -8 style.min.css : 1,142 bytes

The original style.css compressed at the same rates is still larger:

  • gzip -5 style.css : 3,727 bytes
  • brotli -5 style.css : 3,426 bytes
  • zstd -8 style.css : 3,701 bytes

This is an improvement across the board, and doesn't change the ability to run the theme without having to touch a build system.

AI assistance: Yes
Tool(s): Claude
Model(s): Fable 5.1
Used for: Tightly guided, directed, and reviewed. It was all based on the existing pattern for this that was used in the TT5 theme.

@github-actions

Copy link
Copy Markdown

👋 Thanks for your first pull request, @josephscott! We'll take a look soon.

@github-actions github-actions Bot added First-time Contributor Pull request opened by a first-time contributor to the repository documentation Improvements or additions to documentation [Type] Tooling Issues or PRs related to tooling [Area] Theme Functions Issues or PRs that touch functions.php. labels Sep 18, 2026
@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: josephscott <josephscott@git.wordpress.org>
Co-authored-by: MaggieCabrera <onemaggie@git.wordpress.org>
Co-authored-by: mikachan <mikachan@git.wordpress.org>
Co-authored-by: carolinan <poena@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

@carolinan

Copy link
Copy Markdown
Contributor

My preference would be to first explore solutions that does not involve more build tools and disabling an established WordPress feature.
Besides the build tools adding more complexity for some users, this turns editing style.css in the theme editor from
"Hey did you know you don't need to edit this file because we have all of these new features in the Site Editor" to
"You can't edit this file."

Which of the custom CSS is actually non negotiable?
What, if any, performance gains are there by moving the CSS to theme.json?

@MaggieCabrera

Copy link
Copy Markdown
Contributor

My preference would be to first explore solutions that does not involve more build tools and disabling an established WordPress feature. Besides the build tools adding more complexity for some users, this turns editing style.css in the theme editor from "Hey did you know you don't need to edit this file because we have all of these new features in the Site Editor" to "You can't edit this file."

Which of the custom CSS is actually non negotiable? What, if any, performance gains are there by moving the CSS to theme.json?

If we end up having a stylesheet, this makes sense to have, but I agree with you that we should challenge that as much as we can. Let's audit the CSS we have and revisit this after if we decide some of it needs to stay.

Also, the CSS in theme.json is tied to a block. If I am not mistaken, it will only load when such a block is present, which makes it so we don't have the CSS on every single page unless it's really needed.

@josephscott

Copy link
Copy Markdown
Contributor Author

Fair point about using the theme editor to edit the style.css file. I pushed a change that checks to mtime of style.css and style.min.css - if a user has edited the style.css via the theme editor ( or any other mechanism ), then the style.css file will be newer and it will always use that.

This creates a default optimized path for everyone who doesn't edit the style.css file.

Doing this minification step is part of what makes #63 an even better win, where the CSS gets inlined instead of making a separate HTTP request.

@josephscott

Copy link
Copy Markdown
Contributor Author

@MaggieCabrera what are the current thoughts on this? If the theme is going to continue to have a separate style.css, then minifying it would be a performance win. Then inlining it ( #63 ) is another win on top of that.

@josephscott

Copy link
Copy Markdown
Contributor Author

@MaggieCabrera what is the latest on this? If we are going to have a style.css with CSS in it, then I'd really like to see a style.min.css provided with Ipsum as well. And if we get the minified CSS in, we should really do #63 as well.

@MaggieCabrera

MaggieCabrera commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

I rebased this onto trunk and rebuilt style.min.css. The old one still used the color slugs from before #179, so it pointed at colors that don't exist anymore.

Updated sizes, in bytes:

style.css style.min.css Smaller by
Raw 8,149 2,510 69%
gzip -5 3,409 969 72%
brotli -5 3,109 838 73%
zstd -8 3,383 964 72%

I also added a CI check that rebuilds style.min.css and fails if the committed copy doesn't match, so a stale file can't slip through again. And I updated AGENTS.md, which still said there's no build step, plus a line in CONTRIBUTING.md that called style.css the only stylesheet.

@github-actions github-actions Bot added the GitHub Actions Pull requests that update GitHub Actions code label Nov 3, 2026

@mikachan mikachan left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @josephscott, and thanks @MaggieCabrera for rebasing and adding the CI check.

I'm in favour of this. After the audit, it looks like we're only keeping the CSS that can't be included in theme.json, so shipping a minified copy as well makes sense. It's also the same pattern TT5 uses.

I've left one small, non-blocking suggestion.

Comment thread lint-staged.config.mjs Resolved
josephscott and others added 9 commits November 9, 2026 13:33
Using the same pattern as the TT5 theme - https://themes.trac.wordpress.org/browser/twentytwentyfive/1.5/package.json - this change adds a `style.min.css` and the tooling around it to build it.

The `style.css` file would still be used any time that `SCRIPT_DEBUG` is true - which is the case for the `wp-env` setup used by Ipsum.  Production setups would get the benefit of using the smaller `style.min.css` file.

For sizes, `style.min.css` comes in at 3,354 bytes.  Down from the 9,380 bytes of `style.css`.  Here are a few quick compression numbers:

- `gzip -5 style.min.css` : 1,134 bytes
- `brotli -5 style.min.css` : 996 bytes
- `zstd -8 style.min.css` : 1,142 bytes

The original `style.css` compressed at the same rates is still larger:

- `gzip -5 style.css` : 3,727 bytes
- `brotli -5 style.css` : 3,426 bytes
- `zstd -8 style.css` : 3,701 bytes

This is an improvement across the board, and doesn't change the ability to run the theme without having to touch a build system.
The minified stylesheet can't follow the WordPress CSS Coding Standards,
so `npm run lint:css` would fail on it. The pre-commit hook passes staged
files to Stylelint by name, so it also needs --allow-empty-input for a
commit that only rebuilds style.min.css.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
style.css changed on trunk since style.min.css was built, including the
palette rename in WordPress#179, so the old minified file pointed at color slugs
that no longer exist.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
AGENTS.md still said there is no build step, and that style.css loads on
the front end. CONTRIBUTING.md called style.css the only stylesheet,
which stopped being true when assets/css/editor-style.css landed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
style.min.css is committed, so nothing stopped a pull request from
changing style.css without rebuilding it. The CSS job now rebuilds it
and fails if the result differs from the committed copy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributors no longer need to remember npm run build when they change
style.css, and the CI check should rarely fail. Stylelint isn't repeated
in the new task because the *.css task already runs it on style.css.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Trunk changed style.css in WordPress#180 and WordPress#198 after this branch was last
rebuilt, so the CI check failed on the merge with trunk.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@mikachan mikachan left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the changes! I think this is ready to bring in.

@MaggieCabrera
MaggieCabrera merged commit 81bc93a into WordPress:trunk Nov 9, 2026
6 checks passed
MaggieCabrera pushed a commit to josephscott/ipsum that referenced this pull request Nov 9, 2026
**Depends on WordPress#61, which must be merged first.** The added line uses the `$src` variable from WordPress#61, so this does not work on its own.

Adds `path` data to the `ipsum-style` handle so WordPress inlines the theme stylesheet instead of loading it as a render-blocking request. Twenty Twenty-Five does the same - https://themes.trac.wordpress.org/browser/twentytwentyfive/1.5/functions.php#L40

With WordPress#61 merged we get `style.min.css` in production and `style.css` when `SCRIPT_DEBUG` is on.

One less render blocking request, and the minified version is already pretty small.  If we get similar compression results to the stand alone minified version then we are looking at ~1.1KB increase.  A very modest increase for the potential improvement.
MaggieCabrera added a commit to MaggieCabrera/wordpress-develop that referenced this pull request Nov 9, 2026
When `SCRIPT_DEBUG` is off, Ipsum now enqueues `style.min.css`, which is about a third of the size of `style.css`. It falls back to `style.css` when the minified file is missing or older, so edits made in the Theme File Editor keep working. The minified file isn't committed: core's build makes it, as it does for Twenty Twenty-Two and Twenty Twenty-Five.

Synced from WordPress/ipsum#61.

See #66631.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MaggieCabrera pushed a commit to josephscott/ipsum that referenced this pull request Nov 9, 2026
**Depends on WordPress#61, which must be merged first.** The added line uses the `$src` variable from WordPress#61, so this does not work on its own.

Adds `path` data to the `ipsum-style` handle so WordPress inlines the theme stylesheet instead of loading it as a render-blocking request. Twenty Twenty-Five does the same - https://themes.trac.wordpress.org/browser/twentytwentyfive/1.5/functions.php#L40

With WordPress#61 merged we get `style.min.css` in production and `style.css` when `SCRIPT_DEBUG` is on.

One less render blocking request, and the minified version is already pretty small.  If we get similar compression results to the stand alone minified version then we are looking at ~1.1KB increase.  A very modest increase for the potential improvement.
MaggieCabrera added a commit that referenced this pull request Nov 9, 2026
* Inline the theme stylesheet

**Depends on #61, which must be merged first.** The added line uses the `$src` variable from #61, so this does not work on its own.

Adds `path` data to the `ipsum-style` handle so WordPress inlines the theme stylesheet instead of loading it as a render-blocking request. Twenty Twenty-Five does the same - https://themes.trac.wordpress.org/browser/twentytwentyfive/1.5/functions.php#L40

With #61 merged we get `style.min.css` in production and `style.css` when `SCRIPT_DEBUG` is on.

One less render blocking request, and the minified version is already pretty small.  If we get similar compression results to the stand alone minified version then we are looking at ~1.1KB increase.  A very modest increase for the potential improvement.

* Say in the docs that the theme stylesheet is inlined

The front end no longer requests style.css or style.min.css, so there's
no link tag or request for an agent to look for or intercept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: MaggieCabrera <maggie.cabrera@automattic.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: josephscott <josephscott@git.wordpress.org>
Co-authored-by: MaggieCabrera <onemaggie@git.wordpress.org>
wporg-sync pushed a commit to WordPress/wordpress-develop that referenced this pull request Nov 10, 2026
This updates Ipsum from `17a7ada71378a21c36670d67725b3ca632845a9f` to `bc2e5af700e28980f251d97f58cf80c72ee50a13` on its `trunk` branch.

A full list of changes included in this commit can be found on GitHub: WordPress/ipsum@17a7ada...bc2e5af

- theme.json: Give negative outline offset for Button's focus styles (WordPress/ipsum#187)
- Fix view transitions ignoring prefers-reduced-motion (WordPress/ipsum#198)
- Register the pattern utility classes as block styles (WordPress/ipsum#180)
- Fix the PHPStan level 10 errors that core reports (WordPress/ipsum#171)
- Provide style.min.css for production (WordPress/ipsum#61)
- Use the border radius shorthand in the patterns (WordPress/ipsum#206)
- Describe every pattern and offer the format patterns as starter patterns (WordPress/ipsum#181)
- Move what theme.json can express out of the block css strings (WordPress/ipsum#185)
- Clean up editor-only attributes and serialization in the patterns (WordPress/ipsum#204)
- Add DESIGN.md with the theme's design model (WordPress/ipsum#186)
- Inline the theme stylesheet (WordPress/ipsum#63)
- Design guide: Return all theme patterns after the registry has read them (WordPress/ipsum#192)

This commit also includes changes that only exist in core:

- Ipsum is added to the `cssmin:themes` Grunt task, so the build makes the `style.min.css` that the theme now enqueues. The built file is ignored.
- The theme's `node_modules` directory is ignored, and left out of core's build.
- The theme gets its own stylesheet build process, with `build` and `watch` commands that minify `style.css` into `style.min.css`, set up through a new `package.json`, `package-lock.json` and `.nvmrc`. 
- A new `contributing.txt` documents the build process and the `test-and-zip-default-themes` workflow now tests and runs that build for Ipsum.
- Regression tests for the design guide ability are added in core, with a child theme fixture, because Ipsum's repository has no PHPUnit setup.

Follow-up to r60934, r64677, r64678, r64679, r65224.

Props yashjawale, shailu25, onemaggie, westonruter, josephscott, juanfra, mehtadev, mikachan, ravipatel, wildworks, courane01, poena, gziolo.
Fixes #66631.
See #66352.




git-svn-id: https://develop.svn.wordpress.org/trunk@65366 602fd350-edb4-49c9-b593-d223f7449a82
wporg-sync pushed a commit to WordPress/WordPress that referenced this pull request Nov 10, 2026
This updates Ipsum from `17a7ada71378a21c36670d67725b3ca632845a9f` to `bc2e5af700e28980f251d97f58cf80c72ee50a13` on its `trunk` branch.

A full list of changes included in this commit can be found on GitHub: WordPress/ipsum@17a7ada...bc2e5af

- theme.json: Give negative outline offset for Button's focus styles (WordPress/ipsum#187)
- Fix view transitions ignoring prefers-reduced-motion (WordPress/ipsum#198)
- Register the pattern utility classes as block styles (WordPress/ipsum#180)
- Fix the PHPStan level 10 errors that core reports (WordPress/ipsum#171)
- Provide style.min.css for production (WordPress/ipsum#61)
- Use the border radius shorthand in the patterns (WordPress/ipsum#206)
- Describe every pattern and offer the format patterns as starter patterns (WordPress/ipsum#181)
- Move what theme.json can express out of the block css strings (WordPress/ipsum#185)
- Clean up editor-only attributes and serialization in the patterns (WordPress/ipsum#204)
- Add DESIGN.md with the theme's design model (WordPress/ipsum#186)
- Inline the theme stylesheet (WordPress/ipsum#63)
- Design guide: Return all theme patterns after the registry has read them (WordPress/ipsum#192)

This commit also includes changes that only exist in core:

- Ipsum is added to the `cssmin:themes` Grunt task, so the build makes the `style.min.css` that the theme now enqueues. The built file is ignored.
- The theme's `node_modules` directory is ignored, and left out of core's build.
- The theme gets its own stylesheet build process, with `build` and `watch` commands that minify `style.css` into `style.min.css`, set up through a new `package.json`, `package-lock.json` and `.nvmrc`. 
- A new `contributing.txt` documents the build process and the `test-and-zip-default-themes` workflow now tests and runs that build for Ipsum.
- Regression tests for the design guide ability are added in core, with a child theme fixture, because Ipsum's repository has no PHPUnit setup.

Follow-up to r60934, r64677, r64678, r64679, r65224.

Props yashjawale, shailu25, onemaggie, westonruter, josephscott, juanfra, mehtadev, mikachan, ravipatel, wildworks, courane01, poena, gziolo.
Fixes #66631.
See #66352.



Built from https://develop.svn.wordpress.org/trunk@65366


git-svn-id: http://core.svn.wordpress.org/trunk@64505 1a063a9b-81f0-0310-95a4-ce76da25c4cd
arshidkv12 pushed a commit to arshidkv12/wordpress-develop that referenced this pull request Nov 21, 2026
This updates Ipsum from `17a7ada71378a21c36670d67725b3ca632845a9f` to `bc2e5af700e28980f251d97f58cf80c72ee50a13` on its `trunk` branch.

A full list of changes included in this commit can be found on GitHub: WordPress/ipsum@17a7ada...bc2e5af

- theme.json: Give negative outline offset for Button's focus styles (WordPress/ipsum#187)
- Fix view transitions ignoring prefers-reduced-motion (WordPress/ipsum#198)
- Register the pattern utility classes as block styles (WordPress/ipsum#180)
- Fix the PHPStan level 10 errors that core reports (WordPress/ipsum#171)
- Provide style.min.css for production (WordPress/ipsum#61)
- Use the border radius shorthand in the patterns (WordPress/ipsum#206)
- Describe every pattern and offer the format patterns as starter patterns (WordPress/ipsum#181)
- Move what theme.json can express out of the block css strings (WordPress/ipsum#185)
- Clean up editor-only attributes and serialization in the patterns (WordPress/ipsum#204)
- Add DESIGN.md with the theme's design model (WordPress/ipsum#186)
- Inline the theme stylesheet (WordPress/ipsum#63)
- Design guide: Return all theme patterns after the registry has read them (WordPress/ipsum#192)

This commit also includes changes that only exist in core:

- Ipsum is added to the `cssmin:themes` Grunt task, so the build makes the `style.min.css` that the theme now enqueues. The built file is ignored.
- The theme's `node_modules` directory is ignored, and left out of core's build.
- The theme gets its own stylesheet build process, with `build` and `watch` commands that minify `style.css` into `style.min.css`, set up through a new `package.json`, `package-lock.json` and `.nvmrc`. 
- A new `contributing.txt` documents the build process and the `test-and-zip-default-themes` workflow now tests and runs that build for Ipsum.
- Regression tests for the design guide ability are added in core, with a child theme fixture, because Ipsum's repository has no PHPUnit setup.

Follow-up to r60934, r64677, r64678, r64679, r65224.

Props yashjawale, shailu25, onemaggie, westonruter, josephscott, juanfra, mehtadev, mikachan, ravipatel, wildworks, courane01, poena, gziolo.
Fixes #66631.
See #66352.




git-svn-id: https://develop.svn.wordpress.org/trunk@65366 602fd350-edb4-49c9-b593-d223f7449a82
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Area] Theme Functions Issues or PRs that touch functions.php. documentation Improvements or additions to documentation First-time Contributor Pull request opened by a first-time contributor to the repository GitHub Actions Pull requests that update GitHub Actions code [Type] Tooling Issues or PRs related to tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants