Since WordPress 5.9 ushered in the era of blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. themes, there have been questions and concerns about the relationship between theme and CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. styles in the context of GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/. Much of the feedback centers around the notion of how themes can, or should be able to, override CSSCSS Cascading Style Sheets. generated by Core.

This post provides an update about what is happening and, rather imprecisely, when things will happen.

A summary of the challenge

Gutenberg comes with a mix of bundled CSS: global, preset CSS vars, individual block styles or style attributes and block supports.  

As a result of these different layers, theme authors are running into battles of specificity where they wish to override Core styles. Given the frequency of pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party releases, CSS rules are seen as moving targets.

Part of the challenge is to combine the need for greater transparency and predictability with the customization and control of theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML.. Thrown into the mix is how the Block Editor approaches and honors styles added by users.

Folks working closely with Gutenberg are thinking about how to address these concerns both in the short and long term. Everyone’s feedback and contributions have been immensely helpful so far. 

As you can imagine, the ambitions are lofty, the parts are many and moving. There remains a lot of work and discussion to undertake, and the answers aren’t all there.

Theme.json and theme CSS

Block themes have introduced a new paradigm into theme development, with Core attempting to absorb many of the common CSS customization burdens that classic themes have had to carry.

This arrangement is apparent at the basic level of pattern and site composition: blocks.

One of the functions of blocks is to express site elements in a consistent manner, and promote consistent customization experience regardless of the theme. This means that site owners can switch between themes and be confident that their theme.json and global style preferences will migrate with little or no friction. 

Overriding CSS, whether layout, preset, or block styles, presents an obstacle to integration and interoperability: visual parity between the frontend and editor becomes more difficult to maintain, upgrades to block internals may conflictconflict A conflict occurs when a patch changes code that was modified after the patch was created. These patches are considered stale, and will require a refresh of the changes before it can be applied, or the conflicts will need to be resolved. with overrides. Custom CSS is, furthermore, less portable across other block themes.

By encouraging theme authors to use theme.json APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. where possible, the hierarchy of “base > theme > user” defined styles can be resolved correctly.

The general response to calls for greater control over themes is to extend the theme.json API. If there is a feature in demand, and it’s not currently available in the API, contributors band together to build it in. For example, to control the ways in which editors can interact with their designs, theme authors can define which style UIUI User interface components are accessible in the editor right down to the block level through the block support API.

When working on styles in Gutenberg, these guiding principles have remained predominant.

The reality however, is that theme authors will do what they can to achieve specific objectives, that is, “to get stuff done” and realize their (or others’) designs. There have been reports of overly-specific generated layout styles, and CSS rules using !important frustrating theme CSS overrides.

Alternative ways of thinking about how styles are expressed have been proposed, and the ensuing discussion has been supremely valuable.

While more communication and documentation around the what, why and how of styles is part of the puzzle, making the theory and intentions behind blocks and block themes compatible with the practical reality is an ongoing preoccupation of many who are working on Gutenberg.

Current initiatives

Folks on the Core team, including me, are monitoring discussions, and are actively working on shorter-term code changes, and longer-term mitigation strategies to make working with CSS more predictable.

At the same time, the goal is to preserve the primacy of theme.json, and look for opportunities to extend its API and reduce the need for manual overriding of block or layout CSS. When considering proposals such as extending theme.json to define settings and styles for block “sections”, the goal becomes even more pertinent.

Shorter term changes relate to bugs or enhancementenhancement Enhancements are simple improvements to WordPress, such as the addition of a hook, a new feature, or an improvement to an existing feature. features. These potentially include removing !important from preset style rules, and addressing block-specific style issues such as Global Styles: Setting font size for Paragraph impacts Quote Block.

Longer term, there are new discussions around outputting semantic classnames for generated styles and the notion of, for better or worse, holding block or layout classnames to the standards of a public API. The motivation here is for greater consistency in what Core exposes. @isabel_brison expresses eloquently that, regardless of whether something can or should be done via theme.json “sometimes there isn’t a better way to accomplish the goal, and the best we can do in that case is provide a good safety net of consistent and meaningful classnames”.

A vehicle that could unify the management and generation of style and classnames is the nascent Style Engine. The stated goal is to have a “consistent API for rendering styling for blocks, across both client-side and server-side applications”. The barest of bones are in the Gutenberg plugin right now, and there are more iterations on the way. 

Finally, and intertwined with all these efforts, are the plans around increasing layout options. Implicit in this project is a refactor of how we generate and apply layout styles across blocks. Many of the concerns in relation to style and classname generation – predictable and consistent classname hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same., and customization via theme.json – are guiding this work.

Iterations of the longer term projects will be priorities in upcoming versions of WordPress.

Improving documentation

Official documentation on block editor styles is out there. 

There is, nevertheless, huge scope to improve documentation around the role of in-built block CSS and theme.json styles, for example, answering specific questions on best ways to control layouts or individual blocks and providing how-to guides.

It’s a critical one to get right as we all move forward on this issue, and one that I hope will form part of the projects mentioned above.

How to get involved

While there’s no single solution, or maybe even a right solution, now is a great time to get involved while everyone is still experimenting and planning, and there exists the chance for us to strike a balance between the common styles produced by Core and highly specific requirements of theme authors. 

Compromise will arise from wide input and consultation, so I encourage folks to share their thoughts on the features they’d like to see in theme.json and block themes in general. You can join the discussions surrounding semantic classnames, layout options or the Style Engine, or create a new GithubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ issue or discussion if you have an idea about a new approach.

If you have knowledge to share that would help other contributors, there’s always scope to expand and improve the documentation. 

Thanks for reading this post, and for everyone’s input so far. I look forward to diving into the problem-solving pool with you all.

---

Thanks to @annezazu, @isabel_brison, @andrewserong, @glendaviesnz and @apeatling for their help with this post.

#block-themes, #core-css, #gutenberg