También escribo en Español

The theme.json horizon

A new mechanism called theme.json that allows themes to control various aspects of the block editor, from presets to settings to the appearance of blocks, was introduced in WordPress 5.8. There are some cool things that can be done with it already, but I wanted to briefly explain what I think are the more substantial and interesting aspects it starts to unlock:

Interactivity. Style attributes are a subclass of block attributes. As such, the entire block universe understands their values and the interface gets hydrated with it. This means the same ruleset a theme author uses to build a theme is accessible via a graphic interface for the user to interact with. This is huge for opening up an area that used to be closed to users (or required a bunch of ad hoc work from a theme) while also giving the theme the ability to control boundaries and defaults.

Consolidation. Remove overhead from repetitive declarations on themes, particularly around supporting block features. Themes don’t need to concern themselves with structural styles and can be freed to use CSS for specific visual flair, enhancements, and details.

Compatibility. Given it speaks the language of blocks, it is by default compatible with third party blocks provided those blocks are using the core APIs. This can be transformative for the ecosystem where you don’t need to worry if a WooCommerce block would fit with your site design — it will.

Performance. The framework can generate the right bundles on the front based on what content is used. We are barely scratching the surface here as block themes start to roll out but the improvements can be massive. A theme no longer needs to pay the penalty of loading styles for widgets that may or may not be used on a given page.

Flexibility. It opens the door for mixing and merging different block style recipes. For example, you can bring your definitions for block x and z from one theme and keep y from another. You can do this knowing there will be no selector conflicts! This makes it trivial to transfer brand definitions for a family of sites or say “I want to make the buttons of my site look like this theme” without losing any other customization. Specific customizations could also be retained if desired upon theme switching. We are also barely scratching the surface of what can be possible here.

Visual parity. It goes without saying, but the representation of visual aspects in a shared format also allows the platform to ensure the editor and frontend, no matter their setups, can be in sync. The need for editor-stylesheets (which are historically inaccurate and hard to maintain) should be drastically reduced or disappear entirely.

Patterns. This has not been mentioned much, but with theme.json it’d be fairly trivial to send the theme style specification down the wire to the .org directory as structured directives so that you can preview and browse patterns using the actual context of your theme styles!

Portability. The design structure can also be used in contexts outside a theme — think native apps, RSS feed readers, emails, agencies can control look and feel of ads, etc. There’s essentially a coded recipe for how a site looks and feels that is easy to extract values from and use in different contexts.

Accessibility. Tools that tend to be rudimentary (like color contrast) can now properly understand the context of any value because the nested scope of each block is a traversable aspect ahead of rendering time. It’d be possible to generate a higher contrast flavors of an entire site automatically. Similar with dark mode.

Admin. This is more outlandish, but there’s also the possibility to use certain definitions to customize aspects of the look and feel of wp-admin based on the current site design without having to duplicate work or target things specifically.

Thoughts on Themes

Recently, Vlad Olaru wrote and shared with me a thoughtful piece on the place of themes and the advent of Gutenberg in WordPress. While exchanging impressions via email he encouraged me to share my own more broadly, so here I am, true to the days in which discussion happened across blogs.

Themes, mainly premium ones, have been the integrators of the WordPress world.

This made me smile. I started my WordPress journey with themes years ago. I believe it’s important, while Gutenberg evolves to give better design tools to people, to take the perspective of theme authors for a bit. What does it mean for themes that blocks allow more design tools to be available to users?

The fact themes have been the ones to essentially establish page builders as a paradigm is a testament that their role as “integrators” has pushed the ecosystem forward and lead them to implement — often in idiosyncratic ways — what the WordPress platform wasn’t paying much attention to. Themes have the privilege and responsibility of being the closest to the user and how they experience their site, leading developers, in turn, to try to overcome shortcomings in the customization experience offered by the platform. (The difficulties of making your site look like the demo of a theme are notorious.) However, in solving these issues in a multitude of ways, often incompatible with each other, it contributes to creating a faint locking effect that permeates and hurts the user in the long term. Integration can then become the shackles of inescapable experiences.

Which brings us to the conversation about how the evolution of Gutenberg interacts with themes. There is a difference between standardizing the final interaction point (in our case, the block) and giving all integration decisions to the user (the theme role, in Vlad’s examples). That seems to be the main point of discussion and it’s worth clarifying it: providing consistent integration points through blocks, design tools, etc, shouldn’t mean handling control of the design minutiae to the user, nor removing agency from themes, but instead promoting a common way of expressing site elements that ensures a consistent customization experience.

A lot of the conversations about themes have been cast, perhaps all too eagerly, in doom-colored clouds by focusing on the underlying infrastructure and perceiving the shift at play (giving more tools to users) as one that makes every user responsible for their site design. That shouldn’t be the reality. The role of themes is not really changing. They are still meant to provide template resolvers, design parts, styles, and all its various layout decisions; the only difference is that blocks would be at the center, making things more portable and easier to customize given the editor engine understands them better. Users, in turn, will see a familiar interface for all aspects of their site’s appearance.

Perhaps the only new concept being introduced is patterns. These are design helpers to achieve more difficult layouts or beautiful designs faster, which the theme can also control and provide its own. It can be as simple as a few blocks put together or can encompass a larger area of a page. Since themes are made of blocks, it’d also be feasible to swap parts of it with another. Whether a theme is built through markup, CSS, and PHP templates, or expressed through blocks, patterns, styles, and block templates it’s still the responsibility of the theme to integrate, curate, choose, and prepare the experience in the ways it thinks it can better deliver its possibilities and its safeguards. This is not going away. If anything, it becomes more present.

Patterns aim to bring ready-made block designs to users’ hands.

Actually, the general consensus in Gutenberg is that everyone should “Embrace and enhance users being in control”.

I think this is a mischaracterization lost in the sea of impressions that is the day to day process of developing the main ingredients at play. The question is not about giving all power and responsibility to the user but about absorbing the common so that the specific can be better nurtured. That is, building the design tools that would let users interact with themes and blocks in a coherent manner, and giving themes control over its mechanisms. WordPress should provide a familiar and easy to use platform but it’s also the theme builders (soon also pattern builders), site creators, and so on, the ones that shape the final solutions users will often experience.

The systems that might be implemented (block based themes, a block style system, design tools, etc) are not necessarily to be seen as targeted directly to the end user but to the theme creator as well; and passing through them to the final user. It will remain up to the theme and site creators to decide what should be exposed and in what degree, which might vary from “absolutely nothing” to opening and locking certain aspects of the experience in a controlled and familiar way. The overarching decisions (typography, colors, design balance) should be coming primarily from themes.

If the new editor gets its way, this de-facto packaging standard for distributing whole site solutions to end-users will be gone.

Definitely not! The aim is that it would give better and more supported tools to establish these solutions in ways that are inherently compatible with the platform at large. Standardizing on these design tools should help us integrate and expand a common system but shouldn’t imply taking control away from themes. Quite the contrary, a large part of the work is going into ensuring themes can have overarching control over several visual aspects of blocks.

More to the top, a global system of styling and layout will be (eventually) put at your disposal — again, nice for one part, cognitive-freeze for the other. WordPress is becoming more capable, which is a blessing and a curse.

The styling system is primarily a way to establish a direct relationship between the theme and unaware blocks — that is, blocks that have not been created with a specific theme in mind —, in a way that the platform can recognize as appearance attributes in order to render things accurately while allowing the creation of controls to manipulate them visually on the block interface. But this is something for the theme to ultimately oversee, the same way that having a “theme editor” in the dashboard doesn’t mean it should be exposed to every end-user.

The aim is to provide a better and more integrated engine to power the theme experience, not to expose all its inner workings to all people or make it easy to “ruin a design”. That spectrum should always be in the control of those that provide the final solutions, which could be tightly determined or more open ended, depending on the needs at play.

In the end, WordPress contains multitudes and we ought to design systems that are meaningful to all.

Percy Shelley wrote in A Defence of Poetry that poets were the unacknowledged legislators of the world. To borrow the sentiment, let’s hope themes can be the acknowledged curators of the WordPress world.

WP Block Talk

Tune in for the first WPBlockTalk tomorrow, a free virtual event with speakers from all across the WordPress community. Matt Mullenweg and I will start by presenting on the latest adventures of Gutenberg and hopefully doing some live demos, so there could be dragons 🐉

State of the Word

Last week, Matt gave his annual State of the Word presentation in Nashville, reflecting on another year of WordPress and what lies ahead for the project. I had the chance to join him on stage to present a live demo of Gutenberg. I’m very glad with the reception and the good conversations that happened during the event. Still a lot to do, but I’m proud of what the team has achieved so far.

Gutenberg, or the Ship of Theseus

How can a system fundamentally evolve without drastically changing? WordPress can build incredible sites, yet the usability and clarity that used to be a driving force for its adoption has been fading away. The present reality is that many people struggle using WordPress as a tool for expression—they struggle to compose richer posts with media, to get their site looking the way they want, to imitate how a theme demo looks, or to set up and customize a store. There is a disconnect between what is edited in a given field somewhere in the interface with how it will look on the real site. WordPress has always been about the user experience, and that needs to continue to evolve under newer demands. Gutenberg is an attempt at fundamentally addressing those needs, based on the idea of content blocks. It’s an attempt to improve how users interact with their content in a fundamentally visual way, while at the same time giving developers the tools to create more fulfilling experiences for the people they are helping.

How can such a vision happen without dismantling, rebuilding, fragmenting, or breaking the WordPress ship that for over a decade has been carrying the thoughts, joys, and livelihoods of millions of people and more than a quarter of the web?

The ship, like Theseus’, needs to continue sailing while we upgrade the materials that make it. It needs to adapt to welcome new people, those that find it too rough to climb on board, too slippery a surface, too unwelcoming a sight, while retaining its essence of liberty. This is not an easy challenge—not in the slightest. Indeed, we called it Gutenberg for a reason, for both its challenges and opportunities, for what it can represent in terms of continuity and change. It is an ambitious project and it needs the whole WordPress community to succeed. I’d like to start examining some of the decisions made along the way, and the ones that are still to come.

Optimize for the user. An early overview for the project described some of the requirements it faced from a document and data structure perspective. Namely, how can we introduce the notion of content blocks in a way that is transparent to the existing ecosystem while allowing us to rapidly iterate on what ultimately matters the most—the user experience. This means being able to start using Gutenberg very early on without losing access to your content (opening it in other editors, for instance) and without changing how rendering the document works. The overall principle has been to let the machines do what they are good at. I won’t go into much detail here on the specific technical details because we have written about it in the project documentation and other blog posts. Honoring the user content as HTML is important: it assures their posts remain in a highly accessible way for the future and avoids platform lock-in.

On Guides and Placeholders. It is true that WordPress is capable of creating sophisticated sites and layouts. The issue is you need to know how to do it. And getting there requires a level of commitment and expertise that should be unnecessary. Why do users have to bear the weight of convoluted setups to work around the lack of a solid and intuitive visual experience?

This question is what brought us to the concept of blocks in the first place. The simplified nature of blocks, which optimizes for the direct manipulation of content and a single way to insert it, proposes an evolution of the WordPress model. It also comes with interesting opportunities. For example: how many themes have remarkable presentation in their demo sites but require Herculean efforts to replicate? A core ingredient of blocks is that, by their nature, they have a defined “empty state” that works as a placeholder describing how someone can interact with it. Blocks can guide a user as they craft their content intuitively. They are contextual tutorials that both show and teach how to add content. Here is an example of an image block that has no content:


On Templates. Imagine defining a whole page template as a set of default blocks, ready to be filled once the user creates a page; or a custom post type that specifies only certain blocks as available and has them already present in the page instead of a blank canvas. Imagine a simple site meant for publishing pictures where the default block can be just an image block, streamlining the process of creating content in the context of its purpose. On mobile this could reduce the time spent setting things up. This flexibility replaces one of the main needs for post formats, a long quest to allow more diversity of expression. That is, a UI that is contextual to the type of content being created. It also scales further into more advanced post types. A “book” block can include several distinct fields within the context of exactly how it will be presented. A business running an ecommerce plugin can set up pages with products and related blocks—while the users just have to fill in the fields. Finally, themes could now guide their users to the satisfaction of achieving the desired look, without ever leaving the composing interface.

A Powerful Design Tool. This is an important idea to clarify. Contrary to a worried perception that designs will be susceptible to breaking if the user can edit things, Gutenberg aims to give developers a way to define and protect structural markup and their design while giving users the ability to directly edit the information intuitively. Rather than making it easy to mess up a design by mistake or lack of knowledge, Gutenberg protects the design and guides the user. What used to require a mixture of widgets, opaque shortcodes, different meta-boxes, and an instruction sheet to follow—all without a direct visual indication of how things would end up looking—can now be done within a block that looks like the final result. The designer is able to create sophisticated layouts that users can interact with easily and directly without the fear of breaking things.

This puts more tools in the hands of developers and designers without alienating users. The benefit of direct manipulation is that there is no cognitive barrier to overcome—what you see is what you edit. Blocks can define what is editable and in which ways. Their markup cannot be ruined because the block is explicit about how the information will be presented. What used to require a complex set of abstractions can now become a simple structural block that is easy to edit, yet hard to break.

Themes can also provide styles for individual blocks, which can, in aggregation, fundamentally alter the visual appearance of the whole site. You can imagine themes becoming more about the presentation of blocks, while the functional parts can be extracted into blocks (which can potentially work across multiple theme variations). Themes can also provide templates for multiple kind of pages—colophon, products, portfolios, etc., by mixing blocks, setting them up as placeholders, and customizing their appearance.


Discovering Blocks. One of the goals of the block editor is to consolidate the different ways content can be created under the same interface pattern. This not only surfaces a lot of “hidden” features of WordPress but also opens new opportunities for the entire plugin ecosystem. Once the way a user creates content goes through a predictable interface flow, WordPress can surface optional plugins in the right context. If a user searches in the block inserter for something they want to add to their site, and a block doesn’t currently exist, we can immediately search for relevant plugins that might offer such blocks:


On the Layers of the Onion. In order to shift the content creation paradigm without breaking expectations, there are several layers of architecture working in tandem. There is a lot going on before Gutenberg finally outputs a block to the post. First, we get the raw content of the post; we then identify blocks through a grammar parser; we allocate additional attributes for a block based on different heuristics; we build a tree of block objects; we attempt to validate that the shape the block wants to output matches what we have; we finally pass the block type to a visual component which renders the edit context the block has specified when it was registered. All of this happens fast. Yet the different stages and isolated steps grants us a lot of possibilities. If you have already tested the Gutenberg plugin you might have seen a dialog like the following:


This occurs during the “validate what the block can save matches what we have” step. Gutenberg starts with a very strict baseline to allow us to iterate and build the layers we need for an optimal experience. This means if the markup for a paragraph block is lacking p tags, we can identify that as an error. There are three ways we currently offer to resolve it: let the block force what it expects overwriting extraneous markup; convert a block to “classic mode” which switches the block type to be handled by the classic WordPress editor (within Gutenberg); and transforming the block into an HTML block where you can write whatever markup is desired. This is a powerful mechanism and there’s a lot we can do with it. In future releases we’d want to display a before & after comparison for blocks where we detect changes above a certain threshold. Furthermore, these operations are isolated to the block, which gives a lot of granularity to further refine the experience with additional context.

Handling Multiple Sources. In addition to being able to validate blocks, we can also transform generic content into Gutenberg blocks. We are exploring these behaviours through the ability to paste arbitrary content into the editor. (Gutenberg optimizes pasting for several sources, like Google Docs, Microsoft Office, Apple Pages, older WordPress posts, and general web content). It also supports pasting plain text markdown and converting it to blocks. Since blocks are isolated, it is possible to mix different content types without risking the integrity of other blocks.


Markdown can often be great for writing, but it’s not necessarily the best environment for working with rich media and embeds. With the granularity afforded by blocks you could intermix markdown blocks with any other block, adapting to whatever is the most convenient way to express a specific kind of content. Whenever a block cannot be interpreted, we can also handle it as a plain HTML block. In future releases, you’d be able to edit individual blocks as HTML without having to switch the entire editor mode. Individual HTML blocks can also be previewed in place and immediately.

On Granularity. With the abstraction blocks provide, we can also build several tools that take advantage of the fact the full document is broken down into smaller units with semantic value. An example could be the document outline functionality that leverages the presence of heading blocks and allows the user to navigate through the document easily. It can also warn if it detects incorrect heading levels in the outline. Other plugins, like Yoast, could more surgically tailor their tools on a much smaller surface by focusing on single blocks at a time instead of having to deal with the entire document. This same granularity is allowing us to develop a collaborative editing framework where we can lock content being edited by a peer on per block basis, instead of having to lock down the whole post.

A Powerful Developer Tool. Gutenberg not only comes with several user-facing blocks, but the tools we use to create them and power their functionality are also available as components for others to build their own blocks. Our hope is that creating new blocks can be as easy as combining some of our tools, defining new markup and its presentation. This sharing of tools also ensures the user experience is more consistent. We might even look at building a “block composer” (block editor, if you will!) in the future where you can create custom blocks and package them for release. By reusing these pieces, the developer benefits from all the work that went behind them, including things like built in accessibility. These components can also take cues from themes— like the color palette component does—allowing the theme to overwrite the default colors.


Looking Beyond the Post. Gutenberg is initially focused on the post editor but the overarching plan is that it becomes the basis for general editing and customization in WordPress. There are features already in progress that expand beyond the content of the post. “Global Blocks” will allow a user to reuse a specific block (with its content) through multiple posts or pages. This absorbs some of the simpler needs that custom post types historically covered: a “testimonial” can become a simple Quote block that is now globally saved and accessible across all posts through the block inserter. Blocks are also able to save attributes in meta fields, if needed, granting continuity to existing features. Overall, the concept of the block is not about where it stores data, but how the user interacts with it. Blocks will also support nesting, opening further possibilities for customization.

Once Gutenberg is capable of handling all the pieces that visually compose a site—with themes providing styles for all the blocks—we end up with an editor that looks exactly like the front-end. (And at that point, we might just call it front-end editing.) Yet we’d had arrived at it through gradually improving the pieces of our familiar ship, in a way that didn’t cause it to collapse or alienated the people aboard. We want to accomplish this in a way that would allow us to refine and correct as we iterate and experience the reality of what is being built and how it is being used.

Gutenberg is about converting the need for discrete data from one of indirect manipulation into a direct and richer visual experience. It doesn’t seek to remove existing functionality—shortcodes still work the same way—but introduce new ways of interacting with the content. It is an attempt at improving how users can connect with their site in a visual way, not at removing the flexibility and power that has made WordPress thrive. There might be a time when the old ways become obsolete and disappear, absorbed by the richer and clearer interface of blocks, but we are doing as much as possible to make this a process. The old doesn’t have to disappear suddenly, it can be gradually shaped into the new.

Thank you to Mark Armstrong for his feedback and suggestions.