UI: Update CSS cascade layers to use nesting

[aduth]

What?

Closes #78695

Updates the CSS cascade layer defined in @wordpress/ui to use nesting as proposed in #78695.

For review: Strongly recommend reviewing code with whitespace changes hidden, to simplify the diff, since much of the changes are caused by a new level of indentation: https://github.com/WordPress/gutenberg/pull/78959/files?w=1

Why?

• Improves extensibility for consumers: With the previous approach, it's impossible for an application to define its own cascade layer ordering relative to the @wordpress/ui component styles, unless they defined their cascade order before the @wordpress/ui styles are loaded (fragile)
• Reduces the risk for errors, since there's only one public-facing layer to consider (wp-ui), instead of 4.
• Gives us the ability to add or remove cascade layers in the future without as much downstream impact.
• From a code quality perspective, the nesting does a better job of scoping shared layer hierarchy within the @wordpress/ui package scope.

How?

Exactly as proposed in #78695:

So what currently looks like this:

@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;

@layer wp-ui-components {
  /* the styles */
}

Would be nested like this:

@layer wp-ui {
  @layer utilities, components, compositions, overrides;

  @layer components {
    /* the styles */
  }
}

There were a few edge-cases:

• We have some styles that intentionally live outside the CSS cascade layers and need to continue doing so (example)
• Similarly, @keyframes were moved inside the @layer wp-ui, which also does a better job of encapsulating the styles (example of code updated)

Testing Instructions

Verify that there are no regressions in the visual styling of components. Probably easiest to do by checking in Storybook:

1. npm run storybook:dev
2. Go to http://localhost:50240/
3. Explore design system components under "Design System" > "Components"

Use of AI Tools

Markdown edits were hand-written (with the exception of "CSS Layer Hierarchy" subsection revisions). The mechanical process of updating existing code was handled by Cursor + Claude Opus 4.8.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

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: aduth <aduth@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>

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

[github-actions]

Size Change: -29 B (0%)

Total Size: 8.46 MB

📦 View Changed

Filename	Size	Change
build/modules/content-types/index.min.js	158 kB	-34 B (-0.02%)
build/scripts/block-directory/index.min.js	43.7 kB	+4 B (+0.01%)
build/scripts/block-editor/index.min.js	380 kB	-5 B (0%)
build/scripts/block-library/index.min.js	323 kB	+2 B (0%)
build/scripts/components/index.min.js	263 kB	-1 B (0%)
build/scripts/edit-post/index.min.js	52.6 kB	+4 B (+0.01%)
build/scripts/edit-site/index.min.js	296 kB	-1 B (0%)
build/scripts/editor/index.min.js	466 kB	-1 B (0%)
build/scripts/format-library/index.min.js	30.8 kB	+1 B (0%)
build/scripts/media-utils/index.min.js	113 kB	+2 B (0%)

_{compressed-size-action}

[github-actions]

Flaky tests detected in 91419a2.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/27229122905
📝 Reported issues:

• [Flaky Test] shouldn't conflict with server-side autosave #78706 in /test/e2e/specs/editor/various/autosave.spec.js

[ciampo]

LGTM 🚀

This is looking good overall. Should be good to go after rebase / conflict solving

[ciampo]

Could this example ordering be misleading? I assume that, normally, consumers of the package would place their example-app layer after wp-ui?

[aduth]

Maybe? I don't know that I have a strong sense of the use-cases that would be typical here. For example, related to the documented gotchas around bare-element selectors, one possible solution would be to wrap those in one's own app layer and then the wp-ui styles would "win" over those automatically. I don't know how much we want to encourage or support someone overriding wp-ui styles, but even then I'd expect them to work with those layers directly.

[aduth]

I went ahead and reversed these, but we can revisit these as we get a better sense of what this might look like in the real-world. And if we actually wanted to promote the idea from my previous comment about wrapping bare-element selectors, we should probably document that intentionally.

[aduth]

I checked and commented on open pull requests that might be influenced by this change in structure to let them know to rebase and update (notably #78944).