The Block - Theme contract

[luisherranz]

I'd like to learn more about the guarantees that a block grants to a theme, in the sense of: what parts of a block can the themes rely on?

For example:

• Can the themes use or rely on the block class name? Is there a guarantee that it won't change over time?
• Can the themes use or rely on the inner class names? Is there a guarantee that they won't change over time?
• Can the themes use or rely on the inner HTML nodes? Is there a guarantee that they won't change over time?

An example of a theme relying on inner block class names can be seen on the the Blockbase theme.

Based on the answers, I have two follow-up questions:

1. If themes cannot rely on any block internals, how will they make the necessary modifications to the blocks? This is related to my where blocks end and themes start question.

2. If themes can rely on block internals, what are the current plans for blocks to evolve over time?

In the second scenario, imagine a theme or a pattern needs to create some sort of layout/style that is not possible using the layout/styling options of core blocks and global styles, and it ends up using custom CSS.

• Is there some kind of isolation technique planned for this use-case beyond using custom class names to avoid "breaking" the block for its normal use cases?
• If using custom class names is the way to go: what will be the way to reuse those custom CSS'ed blocks in other parts of the theme by the final user?
  • Maybe creating documentation for your theme with a list of its custom class names and how to add them?
  • Maybe adding patterns that include the custom class names?

[mtias]

The only proper contract we provide are class names of the form wp-block-{name-of-the-block} for the block wrappers. Practically speaking, internal structure is also an implicit contract in that we try our hardest to not change it in ways that can disturb selectors, but this can happen from time to time, either to improve semantics, address accessibility, or to accommodate new features.

We have not added classes for all blocks (notably headings, paragraphs, lists, render as vanilla html elements when they have no customizations).

So those three questions would be:

• Mostly.
• Somewhat.
• Somewhat.

If themes cannot rely on any block internals, how will they make the necessary modifications to the blocks? This is related to my where blocks end and themes start question.

Block Style Variations would be one way, in that it allows pairing to an explicit class that is hooked into the block wrapper. The block style variations APIs are not fully developed yet and need a lot of further work. See a fairly old overview: #7551.

There's also an expectation to provide per-block custom CSS hooks, following something like this implementation exploration: #25413

[luisherranz]

Thanks a lot for the response Matías, and sorry for my late answer.

Please, let me know if I have understood the current situation correctly:

1. Themes can rely on block class names.

   This makes sense, but it seems like sometimes, as we can see in the Blockbase theme styles, they are not enough to meet the styling requirements of a theme.

2. Themes may choose to rely or not on inner class names and HTML node structure.

   • If they choose to rely on them:

     • There is no guarantee that a future WordPress update won't break their theme.

   • If they choose not to rely on them:

     • The theme will be 100% backward compatible with future WordPress versions.
     • But they are limited to style using only the block wrapper class names.

     For example, this won't be allowed if you want the absolute guarantee that your theme will be backward compatible:

     .wp-block-image figure {
       ...
     }

If this is indeed the situation:

• Is this seen as something that theme developers need to live with?
• Or is this seen as a temporary problem because block styling via theme.json should replace all custom CSS needs from themes?
• Or is this seen as a problem that should be fixed in the future? And if so, are there any ideas to solve it?

[mrwweb]

I just opened #38998 that I hope can provide a path for the "contract" core provides with some standards that would benefit everyone.