Block Supports: Add opt-in semantic CSS class generation for style properties

[sarthaknagoshe2002]

What?

Closes #71693

This PR introduces a opt-in architecture that translates Gutenberg block style attributes (like padding, margin, typography, and borders) into semantic, standardized CSS classes (e.g., has-padding, has-large-font-size) on both the server (PHP) and client (React).

Why?

Currently, Gutenberg hardcodes user styling choices via inline styles (style="padding: 100px;") or scoped style blocks. This creates a nightmare for theme developers trying to enforce responsive design or global brand consistency (e.g., updating a primary brand color across hundreds of old posts).

By translating these stubborn inline styles into predictable CSS classes, we give control back to theme authors, allowing them to target and override editor styles easily via CSS.

How?

• Implemented a opt-in architecture via the wp_enabled_style_properties filter, defaulting to off so it doesn't break backwards compatibility for existing themes.
• Built a PHP engine that evaluates block attributes, safely navigates deeply nested properties, and injects sanitized kebab-case classes into the markup via WP_HTML_Tag_Processor.
• Created a React Component that perfectly mirrors the PHP logic, injecting the exact same classes into the editor canvas to maintain true WYSIWYG parity.
• Registered the __experimentalStyleClassesEnabled key in the WP_REST_Block_Editor_Settings_Controller schema and added it to the BLOCK_EDITOR_SETTINGS JS allowlist to securely pass the active filters from the PHP server to the React client.
• Added dynamic extension hooks, such as wp_enabled_style_properties_{$block_name} and wp_enabled_style_properties_{$slug}, allowing developers to target or exclude specific blocks.
• Engineered 19 PHPUnit tests and 16 Jest tests to guarantee complete cross-environment logic parity.

Testing Instructions

1. Open a post/page in the block editor. Add a Group block and apply various styles (padding, margin, border-radius, background color, font size).
2. Inspect the DOM in the editor and on the frontend. Notice that no semantic classes are generated (verifying the strict default-off behavior).
3. Open your active theme's functions.php and add the global opt-in filter:

   add_filter( 'wp_enabled_style_properties', function() {
       return array( 'padding', 'margin', 'border-radius', 'shadow', 'color-background', 'font-size' );
   } );```

4. Refresh the editor. Inspect the Group block in the editor canvas and verify that semantic classes (e.g., has-padding, has-border-radius, has-custom-background) are now accurately applied to the wrapper.
5. Save the post and check the frontend to verify the exact same class string is generated by the PHP engine.

Screenshots or screencast

Goal

If a developer wants to add custom badges, specific borders, or design adjustments to a block based on user layout choices (like specific padding alignments or mixed border-radii), they can simply write clean class selectors. The video shows this in action across both the editor and the frontend once the opt-in filter is active.

Setup

Theme Opt-In (functions.php):

add_filter( 'wp_enabled_style_properties', function() {
    return array( 'padding', 'margin', 'border-radius', 'color-background' );
} );

Custom Theme Styles (style.css):

.wp-block-group.has-80-padding.has-custom-border-radius {
    position: relative;
    border: 2px solid #ff0000;
}

.wp-block-group.has-80-padding.has-custom-border-radius::after {
    content: "Perfectly Padded!";
    position: absolute;
    top: -15px;
    right: -15px;
    background: #ff0000;
    color: #fff;
    padding: 4px 8px;
    border-radius: inherit;
    font-size: 12px;
    font-weight: bold;
}

.wp-block-group.has-mixed-border-radius.has-custom-top-margin {
    border: 5px dashed red;
    transform: rotate(2deg);
}

Screen.Recording.2026-07-10.at.5.10.58.PM.mov

When the block receives 80px padding and unlinked corner values, the engine injects has-80-padding and has-mixed-border-radius alongside side specific classes, allowing the theme's custom CSS to match those precise state combinations and apply the custom red borders, badges, and rotational effects instantly.

Use of AI Tools

I utilized AI to assist with scaffolding the PHP and JavaScript parsers, and drafting the PHPUnit/Jest test suites. I directed the architecture, reviewed all generated code against Gutenberg coding standards, executed fault-injection tests.

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

• Required label: Any label starting with [Type].
• Labels found: [Package] Editor, [Package] Block editor.

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.

[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: @itsViney.

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: itsViney.

Co-authored-by: sarthaknagoshe2002 <sarthaknagoshe2002@git.wordpress.org>

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