What problem does this address?

I have written a blog post describing the issues this proposal addresses in detail.

This is a proposal to use CSS utility classes for common layout needs and access to site-specific standardized design tokens set in theme.json. Doing so will allow WordPress "core", themes, and plugins to have access to a valuable shared CSS toolkit. The result is a WordPress landscape where WordPress markup and styles are easier to extend, site content is more portable, and themes and plugins are more interoperable.

The overall goals are to:

1. Ensure themes have sufficient ability to customize site designs
2. Improve ability for plugins and theme switching to maintain user decisions
3. Standardize the CSS for how core blocks accomplish frequent layout needs

The need for a clear direction and solution along these lines has come into focus recently:

It is clear that WordPress can provide a significant portion of front-end markup and styling responsibility, but this won't serve the community if the result is a "walled garden".

It’s been over three years since the block editor was released, yet theme authors are still unclear about what they can rely on in the block editor… Even among early and excited adopters of the block editor, I still frequently hear concerns and frustration from people who write custom themes and plugins about the lack of a consistent, and extensible front-end approach for blocks and their styles…

Now is a critical moment to find a path that meets the needs of WordPress core development without sacrificing the needs of 3rd-party themes and plugins.

The background and reasoning behind each decision along with examples are provided, so please read the full proposal if you want to leave a detailed comment.

This proposal brings together multiple different threads of conversations because I think it's important that each change is considered in the context of the others. When they come together, they illustrate a cohesive vision for a vibrant WordPress ecosystem benefiting all users and developers.

With a streamlined and transparent approach to design, core development will have a self-documenting, easy-to-understand set of tools for implementing future designs. When switching themes doesn't mean losing all your content design decisions or having to remove ones that no longer make sense, users gain more freedom with their content and trust WordPress even more. And when plugins can implement site-specific design tokens in their own output, they will work and look better for site owners and site visitors alike. Every site will be more than the sum of its parts.

What is your proposed solution?

This is a four-part solution that builds on existing practices already in WordPress while committing to full block/setting coverage and backwards compatibility:

1. Ensure every HTML element in complex core blocks has a unique class (e.g., wp-block-media-text, wp-block-media-text__content, wp-block-media-text__media, wp-block-media-text__image) and use single-class selectors in core CSS when styling them so they are easy to override
2. Always communicate block state for all visual block options with CSS classes (existing examples: is-vertically-aligned-center, has-background, is-style-{name}, alignwide)
3. Standardize and extend theme.json design tokens. For example, have all themes define background, foreground, primary, secondary, and accent colors and gap-1, gap-2, gap-3, gap-4, and gap-5 for gap values. Use these values as the standard options in block settings for the primary means of customization. I've written a proposed set of standard tokens to get this conversation going.
4. Output a single-purpose CSS utility class for each standard design token (point 3) and relevant block state (point 2), e.g., wp-color-background, wp-gap-4, is-vertically-aligned-center

This proposal is illustrated with code snippets in the blog post and there's a functioning demo showing a partial implementation.

I believe if these four things were done consistently and with a commitment to backwards compatibility, all of the following become easier or newly possible:

• Theme developers would happily write less CSS by setting standardized design tokens in theme.json
• Theme developers could confidently customize themes in places where UI settings are insufficient
• Better theme switching / content portability: Content design choices are not locked-in to a single theme's options or over-optimized to a specific theme's absolute values (e.g. choosing a "Large" gap rather than a 48px gap is easier for users and would look good in any theme without modification)
• Plugin developers would gain access to theme styles for their front-end output
• Core CSS would be more consistent across blocks
• Plugins, themes, and core could rely on a small, shared set of CSS utilities (resulting in less overall code sent to the browser)

Proposed Standard Design Token Names in theme.json

Themes and plugins could define additional tokens beyond these, but all of the following would be expected of new themes. WordPress would likely provide a fallback in cases where themes defined only some or none of the tokens.

• Colors: foreground, background, primary, secondary, accent
• Font sizes: font-size-1, font-size-2, font-size-3, font-size-4 (default), font-size-5, font-size-6, font-size-7
• Font Weights: font-weight-1, font-weight-2, font-weight-3 (default), font-weight-4, font-weight-5
• Font Families: copy, headings, monospace
• Borders: border-1, border-2 (default), border-3
• Gap: gap-1, gap-2, gap-3 (default), gap-4, gap-5
• Margin: margin-1, margin-2, margin-3 (default), margin-4, margin-5
• Padding: padding-1, padding-2, padding-3 (default), padding-4, padding-5
• Media Query Breakpoints: two-columns, three-columns, desktop-menu
• Content Widths: contentSize (exists), wideSize (exists), maxSize

Things not included in the proposal

This proposal doesn't need to interfere with or be at the expense of:

• Inline styles or custom style blocks for one-off block styles (e.g. 7px border vs a small border)
• Themes defining additional values beyond the standardized design token names

Related Issues

This is closely related to a number of existing issues, and tries to present a cohesive vision for a solution. Here's an incomplete list of current relevant issues:

• Tracking: Add a Style Engine to manage rendering block styles #38167 / Improving our saving/rendering of block styles #37495
• General CSS Concepts: Declaring style vs. describing state #38694
• The Block - Theme contract #35470
• Standardizing required theme CSS Variables #33180
• Default Colors, Theme Colors, and Custom Colors #29568
• Add a selection of preset spacing values to supplement/replace custom padding/margin options #35306
• On Global Styles Saving and REST API endpoints #35141
• Explore options to add back semantic classnames to block wrappers  #38719

Credits / Attributions

None of the ideas in this proposal are new (a strength of the proposal). I think they are most compelling when packaged together. This builds on tons of existing thinking and work by other community members. Therefore, I think it's important to credit a many people here as I can.

• People who reviewed the blog post providing valuable feedback: @aurooba, @Luehrsen, @pattyok
• People who provided guidance and resources: @annezazu, @bph
• People whose writing/comments heavily influenced this post: @mtias, @richtabor, @cbirdsong, @luisherranz, @justintadlock, @billerickson