Global Styles: Add support for loading CSS from external files in theme.json

[im3dabasia]

What?

Closes: #69484

This PR adds a new feature to theme.json that allows theme authors to load CSS for blocks from external files instead of embedding it directly in the theme.json file. This is done through a new file: prefix syntax in the css property.

Why?

This enhancement allows theme authors to organize their CSS in dedicated files, and use it in the theme.json

How?

The implementation adds support for a special file: prefix in the css property value in theme.json. When detected, the code:

1. Extracts the relative file path
2. Resolves it to an absolute path within the theme directory
3. Uses WordPress's built-in wp_enqueue_block_style() function to properly enqueue the file
4. Applies the same approach for both block-level CSS and block style variations

This keeps the implementation simple while leveraging existing WordPress functions for style enqueueing, ensuring compatibility with the WordPress CSS loading system.

Testing Instructions

1. Create a new theme or use an existing theme with a theme.json file I used test/emptytheme
2. Activate the emptytheme in Appearance > Themes > Empty Theme
3. Add the following to your theme's theme.json file:

"styles": {
  "blocks": {
    "core/navigation": {
      "css": "file:./assets/css/navigation.css"
    },
    "core/paragraph": {
      "css": "file:./assets/css/paragraph.css"
    }
  }
}

4. Create the CSS files /assets/css/navigation.css and /assets/css/paragraph.css

• /assets/css/navigation.css

.wp-block-navigation {
  border: 5px solid #d41ad1;
  background-color: #a7d5ee;
}

• /assets/css/paragraph.css

.wp-block-paragraph {
  background-color: rgb(183, 21, 118);
}

5. Create a page with navigation and paragraph blocks
6. View the page and verify the CSS is applied correctly

Screenshots or screencast

A comprehensive video of how I tested this feature locally:

Screen.Recording.2025-03-14.at.4.29.29.PM.mov

[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.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @EldarAgalarov.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

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

Unlinked contributors: EldarAgalarov.

Co-authored-by: im3dabasia <[email protected]>

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

[github-actions]

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

• Type-related labels to choose from: [Type] Automated Testing, [Type] Breaking Change, [Type] Bug, [Type] Build Tooling, [Type] Code Quality, [Type] Copy, [Type] Developer Documentation, [Type] Enhancement, [Type] Experimental, [Type] Feature, [Type] New API, [Type] Task, [Type] Technical Prototype, [Type] Performance, [Type] Project Management, [Type] Regression, [Type] Security, [Type] WP Core Ticket, Backport from WordPress Core, Gutenberg Plugin.
• Labels found: .

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.