Tracking: Addressing Design Tooling Consistency

Important

The adoptions below are being opened as PRs by an automated process. Please don't open separate PRs for them.

That process works through this issue and keeps it up to date. Leaving the adoptions to it is the quickest and cleanest way to get these features to users.

Where help makes the biggest difference is reviewing and testing the generated PRs. Each one follows the decisions from the audit below and includes testing instructions and screenshots.

Overview

This issue tracks design tool and block support consistency across the block library. The goal is unchanged from 2022: as few gaps as possible, and every remaining gap a deliberate choice with a recorded reason.

The four per-support tracking issues that sat under this one are now closed. What they listed is either shipped or carried forward here.

Where things stand

I have audited the current block library: all 116 blocks against every design tool, including the supports the original issues never covered, such as background, shadow, block gap, sticky position and duotone.

Every block and tool combination now has a decision. The support is already there, a pull request will add it, or it is deliberately left alone with a reason.

Support	Gaps left	Pull request open	Not started	Of those, migrations
Dimensions	69	6	63	10
Border	12	9	3	0
Spacing	12	9	3	0
Typography	5	0	5	2
Shadow	5	0	5	0
Colour	4	2	2	0
Background image and gradient	3	1	2	0
Sticky position and duotone	0	0	0	0
Total	110	27	83	12

Remaining work

One pull request per block per support, with all features of that support in the one pull request. The lists below are the full remaining set, grouped by support. A block with an open pull request already covering that support carries the number on its line.

Two exceptions to the one support rule:

Border and spacing may be combined where padding and border both affect box sizing.
Migrations are always on their own, because each needs a deprecation and a content migration.

Most of these are small: a block.json change, sometimes selectors or skipped serialization where the styles have to land on an inner element.

Note

These lists are generated from the audit and from block.json on trunk, so an item disappears once its support lands. Please do not edit them in place, the next refresh will overwrite your change. An item marked in progress or with a pull request number is already being handled.

Border, 12 gaps, 9 with a pull request open

Colour, 4 gaps, 2 with a pull request open

Home Link core/home-link: add text, background
Playlist track core/playlist-track: add text, background (open: #81998)
Social Icon core/social-link: add text, background
Table core/table: add link (open: #72229)

Typography, 5 gaps, 0 with a pull request open

Playlist track core/playlist-track: add font size, line height, font family, font style, font weight, letter spacing, text transform, text decoration
Pullquote core/pullquote: add fit text
Quote core/quote: add fit text

Needs a migration first. These blocks already do the job with a bespoke attribute, so each needs a deprecation and a content migration.

Quote core/quote: add text align
Social Icons core/social-links: add font size

Spacing, 12 gaps, 9 with a pull request open

Dimensions, 69 gaps, 6 with a pull request open

Needs a migration first. These blocks already do the job with a bespoke attribute, so each needs a deprecation and a content migration.

Background image and gradient, 3 gaps, 1 with a pull request open

Post Navigation Link core/post-navigation-link: add background image, background size, gradient (open: #83940)
Social Icon core/social-link: add gradient
Submenu core/navigation-submenu: add background image, background size, gradient (in progress)

Shadow, 5 gaps, 0 with a pull request open

Navigation core/navigation: add shadow
Navigation Link core/navigation-link: add shadow
Playlist track core/playlist-track: add shadow
Site Logo core/site-logo: add shadow
Social Icon core/social-link: add shadow

Sticky position and duotone, 0 gaps, 0 with a pull request open

Platform fixes these adoptions needed

Three gaps turned up while working through the list. Each is a small fix of its own, and each unblocks adoptions that cannot be done correctly without it.

The editor ignored background skip serialization, so a block that applies its background to an inner element was painted on the wrapper in the editor and on the inner element on the front end. Fixed in #83943, which also adds useBackgroundProps and getBackgroundClassesAndStyles to @wordpress/block-editor, the helpers every other support already has. Icon, Table, Button, Tab List, Search and Post Navigation Link background all depend on it.
Fit text sized every copy of a block in a loop from one rule, so in a Query Loop the longest title clipped while the shortest stayed small. Fixed in #83985. This is what Post Title fit text was waiting on.
A per-instance state rule was scoped to the wrong element when a block's root selector names its parent, so a responsive or pseudo-state value set on a single block did nothing. List Item is the case, with .wp-block-list > li. Fixed in #83986, in PHP and in the editor.

Decisions worth knowing before reviewing

Three rules came out of the audit. They explain choices that will otherwise look inconsistent across the pull requests.

Gradients use background.gradient. No block adopts color.gradients from here on. packages/block-editor/src/hooks/background.jsx treats color.gradient as the legacy path and background.gradient as the current one. Blocks already shipping color.gradients add background.gradient alongside it rather than switching, so existing content keeps working.

Element colours need a descendant to target. elements.heading resolves to h1, h2, h3, h4, h5, h6 scoped under the block selector, see packages/blocks/src/api/constants.ts:299. A block whose own wrapper is the heading cannot use it. Accordion Heading is the clearest case: it renders the heading as its own wrapper and its toggle button does not carry the element button classes, so it takes neither elements.heading nor elements.button. The other three Accordion blocks take both.

Bespoke attributes get their own pull request. Several blocks already do a support's job with a custom attribute. Social Icons size turns out to be a font size rather than a dimension. Spacer height and width map onto the dimension supports, which have their own presets through settings.dimensions.dimensionSizes. These are listed separately under each support above.

Exceptions

The larger half of the audit is the decisions not to adopt. That was the second goal in the original version of this issue and the part that never got written down. Spacer renders an empty sizing box, so typography and shadow do not apply to it. Separator has no content to style. Embed does not take border, shadow or aspect ratio for now: a fixed size third party embed does not fill the block, so a border or shadow is drawn around empty space. Each of these is recorded per block with its reason.

I would like to land the full set as a reference page under docs/, so block authors can see why a support is absent rather than reporting it as a bug. That is a follow-up.

As long as we allow themes or plugins to enqueue stylesheets, I don't think there is a quick win there. The low-hanging fruit in relation to closing that gap will be exposing the merged global styles in the block editor as per #34178. Once that is in place we'd need to go through all the block supports and their controls to leverage that global styles data to set better defaults. Additionally, we'd probably need some updated designs for several controls that allow for selection of, or reflect that, a value is being inherited.

Long story, short. I think that is large enough in scope to require its own dedicated tracking issue. For now though, I've added it to this issue's description as a future follow-up.

Additionally, we'd probably need some updated designs for several controls that allow for selection of, or reflect that, a value is being inherited.

This is what I am afraid of. Hopefully there is a heuristic we can come up with (e.g. simply hiding controls when the value is inherited from css) and apply it across all tools.

Long story, short. I think that is large enough in scope to require its own dedicated tracking issue. For now though, I've added it to this issue's description as a future follow-up.

Fair enough, this sounds good, thanks!

Hopefully there is a heuristic we can come up with (e.g. simply hiding controls when the value is inherited from css) and apply it across all tools.

If a control is not displayed by default, it will only be shown for a block if a user has toggled it on or customized its value previously. Is your concern primarily with default controls (the ones shown without the user having to toggle them on via the ellipsis menu)?

I believe the previous driver for having these default controls was that they should be the controls that users tweak often. Exactly which controls are displayed by default was something we aimed to refine over time.

Is your concern primarily with default controls (the ones shown without the user having to toggle them on via the ellipsis menu)?

Yes that's it. It's really awkward to see empty controls when a value is clearly set (albeit via css). My hypothesis is that in these cases seeing no control would be less confusing, and makes adding the control feel more like what it is – a local override.

I believe the previous driver for having these default controls was that they should be the controls that users tweak often. Exactly which controls are displayed by default was something we aimed to refine over time.

Indeed, and this is a good argument against simply hiding the controls when they inherit values from css.

But if the alternative requires us to come up with designs for every single control so that they clearly indicate what is already a fairly confusing concept, then I think it's worth considering. We ran in a lot of circles trying to handle this just in the new padding control alone.

At least we can find comfort in the fact that this issue should (hopefully) fade away over time as theme.json is becomes more widely adopted, and #34178 is closed like you mentioned.

Sorry to derail this issue, we can continue the conversation in #43082 :D

Update: 5 September 2022

Current Status

Work towards completing Phase 1, as outlined in this PR, is still ongoing. We have several contributors from the wider WordPress community assisting in these efforts, which is greatly appreciated 🙇

If there are particular block supports you wish to ensure land in time for 6.1, please feel free to jump in and create or review relevant PRs. If you submit a PR, it would be great if you could also update the relevant block support tracking issue or comment on them (see links at bottom of this issue's description). We'd like to keep these as up-to-date as possible, so anyone can quickly identify gaps and contribute without overlapping the efforts of others.

Rough guide to current Phase 1 completion:

Block Support	Blocks with Full Support	% Complete	# Open PRs (as of this writing)
Typography	46/84	54.76%	9
Spacing	34/84	40.47%	5
Layout	12/23 *	52.17%	1
Color	41/84 **	48.81%	5
Border	8/84	9.52%	3

* Not all blocks will be candidates for adopting layout support. As such, the available blocks number reflects eligibility.
** What makes sense for color support can differ more from block to block. This figure is a very rough approximation.

The figures above don't yet acknowledge any blocks we determine should not in fact opt into a particular block support. As a result, these numbers will tend to be conservative.

What's planned for WordPress 6.1

The current plan is to achieve as much as possible towards completing Phase 1.

Given the large number of blocks and the potential for tricky edge cases, we won't be able to complete phase 1 across all block supports. As such, we'll be approaching them in general order of priority:

Typography > Spacing > Layout > Color > Border

Beyond 6.1

WordPress 6.1 will only be the start of our efforts to achieve consistency across our design tools. The immediate goal post 6.1 will be to complete Phase 1 for all block supports. From there, we should be well positioned to complete phases 2 & 3 for WordPress 6.2.

Update: 16 September 2022

This update is a little late as I was AFK for a few days recently but here goes 🙂

Current Status

In the lead up to the 6.1 feature freeze, we focused primarily on Typography and Spacing supports.

The majority of blocks requiring typography design tools received them. There were of course several exceptions such as captioned blocks e.g. Image, Embed, Video etc. While these blocks could have benefited from typography supports, the potential in the near future for them to be refactored to use an inner standalone Caption block made it worth holding off here to avoid any backwards compatibility issues.

Phase 1 is continuing however the pace here might slow in the short term as we shift focus to help iron out kinks for the 6.1 beta.

Phase 1 completion so far:

Block Support	Blocks with Full Support	No Support Required	Postponed	# Open PRs	% Complete
Typography	59	9	4	4	85.71%
Spacing	42	0	0	4	54.76%
Layout	12 *	0	0	0	52.17%
Color	50 **	5	0	6	65.47%
Border	12	0	0	2	14.28%

* Not all blocks will be candidates for adopting layout support. As such, the available blocks number reflects eligibility.
** What makes sense for color support can differ more from block to block. This figure is a very rough approximation.

Quick comment to drop a link to a PR aiming to extend and stabilize our block.json selectors API.

Block.json: Refactor and stabilize selectors API #46496

It will offer the ability to specify CSS selectors for individual styles (e.g. font size), not just features (e.g. typography). In turn, that extra flexibility might help smooth out edge cases and make adoption of block supports easier.

It would be great with an update in regards to the upcoming WordPress 6.2. Beta 1 is 7th of February.
Thanks!

@paaljoachim

Hi @paaljoachim 👋

There hasn't been much progress on further block support adoptions for this release.

Most of the low-hanging fruit (especially for typography supports) has been picked. Those remaining have some trickier edge cases requiring greater control over CSS selectors to ensure we don't create a disjoint between individual blocks and theme.json/global styles (more on this in a moment).

We also ran into some issues with margins being broken by the new layout supports, which became a blocker to adopting spacing supports. With any luck that will be resolved later this week. You can follow progress there on #47399.

With the rapid adoption of block supports adding more and more controls to our sidebar, we've needed to switch focus a little this release to refining the sidebar. A big part of that was the sidebar tabs experiment #45005.

Back to the CSS selectors mentioned earlier, I've been working on stabilizing and extending the block.json selectors API. This will provide blocks with greater control over the selectors used for each block support feature (e.g. color, typography) and subfeature (e.g. background color, font size).

The combination of these efforts should help reduce the friction in adopting missing block supports. Hopefully, allowing for this issue to regain some of its lost momentum.

A new "Post Time To Read" block has been merged with #43403. This is an experimental block, but please add it to each table if needed 🙏

@t-hamano

As @t-hamano mentioned in #63050, this might be the better place to track all of the requirements and missing features. I have compiled a task list in that issue: does it make sense to bring that here? I imagine that a revised list would make sense once 6.6 drops and I would imagine that having one issue per requirement would lead to them all receiving very little attention in the wider context.

does it make sense to bring that here?

I think so.

The linked issues here per block support also capture when deliberate decisions have been made to omit a support from a block when it doesn't make sense.

@bph

Adding the list of outstanding missing supports (which @bph originally compiled).

Edit: see the existing summaries linked at the top of this issue under Tracking Issues for Individual Block Supports.

Note from #63050 (comment):

Can you expand on your comment, how some features “don’t apply”?

It can sometimes be difficult to predict how and why a support might be hard to implement for a particular block. I.e. the block might have a particular markup structure or server-rendering that means it isn't very straightforward. So, it can be useful to contain the discussion to an issue that's related to that particular block support.

I don't feel that the difficulty of implementation is a valid reason to exclude support of a particular feature.

@markhowellsmead

Thanks for consolidating #63050 into this and adding that list @markhowellsmead 👍

I don't know how useful it is in that long form though. In addition to pushing the rest of this issue's conversation way down the page for a while, it won't act as a source of truth or task list over the dedicated feature issues linked in the description.

For me, it is also a bit misleading as it suggests some supports should be adopted, or are missing, when they were deliberately omitted previously.

Perhaps it could be collapsed under a <details> block if we wish to keep it, what do you think?

Each of the individual feature issues linked in the description will need a quick pass to make sure they are up to date. I suspect they'll only need a few minor tweaks but I don't really have the bandwidth at the moment to do that pass myself.

I don't feel that the difficulty of implementation is a valid reason to exclude support of a particular feature.

My interpretation of that comment was it was highlighting not that support couldn't be adopted but that discussion around it should be contained to an issue that's related to that particular block support.

Hello,
don’t forget the highly needed radius on column (so border is partially implemented on child columns, it’s ok on the parent column). In case we need to build pricing grids, we have to encapsulate a group just to get the radius option.
Related

@aaronrobertshaw

@aaronrobertshaw I agree that it is a very long list, but it also highlights the disparity between the many blocks; some of which have been incomplete for a very long time. Hiding it in a Details block (is that even possible in Github?) is brushing the many problems under the carpet.

I'd opened #63050 in order to try and have a central overview, but it was agreed that this issue (#43241) is the correct place to continue the discussion. I don't want to drag this in the direction of issue administration, but it's more than possible that the summaries are best retained within the issues linked under the original Tracking Issues for Individual Block Supports heading at the top of this issue, rather than having a single check-list here. To that end, I've removed the check-list from my previous comment.

@markhowellsmead

highlights the disparity between the many blocks; some of which have been incomplete for a very long time

@markhowellsmead that's exactly the reason all these design tooling issues were created in the first place 🙂

Hiding it in a Details block (is that even possible in Github?) is brushing the many problems under the carpet.

The details block was a compromise to keep a historical record of where things are at right now.

Contrary to "sweeping problems under the carpet", the dedicated feature issues are more discoverable than a list in a single comment on this issue. So I think we are on the same team here in that we'd both like to see progress made. The dedicated issues per block support are our best bet to do that.

it was agreed that this issue (#43241) is the correct place to continue the discussion

To this point, yes, #43241 was referred to explicitly but I think it was more meant as the collective set of design tooling issues. This is just the primary entry point to those.

To that end, I've removed the check-list from my previous comment.

Thank you 🙇

Having a single checklist or source of truth per block support should help limit confusion and hopefully make it easier for anyone to contribute if they have a particular block and support they'd like to see adopted 🤞

P.S. Yes, you can use a simple HTML details block in GitHub comments.

Click for snippet

<details>
<summary>Hello</summary>

World :)
</details>

My interpretation of that comment was it was highlighting not that support couldn't be adopted but that discussion around it should be contained to an issue that's related to that particular block support.

Yes, that was my intention — there are heaps of great features that folks would love to implement but some will require more discussion than others. My main hesitation with big tasks lists is that they can sometimes obfuscate how challenging and involved each task might be, and that there'll be discussions to be had along the way.

To be clear, though, I'm very excited seeing all the enthusiasm for improving block supports consistency and feature support here! With many eyes, hopefully it'll be easier for us to tackle in the long term.

Should the following block support also be managed in a separate tracking issue?

background
- backgroundImage
- backgroundSize
shadow

Should the following block support also be managed in a separate tracking issue?

Eventually yes.

My preference would be to address the issues we have now, moving them to a point we can call them complete, before splitting effort further.

Background supports are still in flux, in particular the merging of color gradient and background image support. So that one needs some more time.

Shadow support is only new as well. There is nothing stopping it being adopted for critical use cases but I think its a little premature to try and get it adopted widely over the other pre-existing supports.

@aaronrobertshaw

@aaronrobertshaw related to design tooling:

Embed blocks: adding captions via toolbar #64385

@simison

Thanks for flagging that one and creating a separate issue @simison 👍

Given it's only a handful of blocks that need an update around caption handling, it might be best to track that via #64385. I've added the [Feature] Design Tools and [Type] Enhancement labels to the issue so it should come up in related searches and work efforts.

I have updated this issue's description with the current state of this work.

The per-support tracking issues under this one have been closed. Their tables had fallen behind, there were 26 new blocks added since this effort began. Multiple new block supports have also been implemented yet not included in these efforts. Decisions recorded in those sub-issues still stand unless this issue description says otherwise.

This issue's description now lists the full remaining set as of today. About 330 updates grouped by support with any open pull request linked on the line it affects.

Those lists are generated from the audit and from block.json files on trunk. So an item disappears once its support lands. Please do not edit them in place, the next refresh will overwrite the change. Comment here to claim something and reference this issue from the PR.

I've closed #83019 as something we won't adopt for now. There are a few embed types that won't render in standard aspect ratios that would fill the block so applying borders and shadows to the embed block itself isn't clean. Further we can't reliably apply the styles to or target inner markup within iframes of an unknown or potentially changeable structure.

So for now, we have more valuable additions that we should focus on before revisiting this.

Navigation Menu

Repository navigation

Tracking: Addressing Design Tooling Consistency #43241

Overview

Where things stand

Remaining work

Platform fixes these adoptions needed

Decisions worth knowing before reviewing

Exceptions

Related

Update: 5 September 2022

Current Status

Rough guide to current Phase 1 completion:

What's planned for WordPress 6.1

Beyond 6.1

Update: 16 September 2022

Current Status

Phase 1 completion so far:

4 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Tracking: Addressing Design Tooling Consistency #43241

Description

Overview

Where things stand

Remaining work

Platform fixes these adoptions needed

Decisions worth knowing before reviewing

Exceptions

Related

Activity

jameskoster commented on Aug 25, 2022

aaronrobertshaw commented on Aug 26, 2022

jameskoster commented on Aug 26, 2022

aaronrobertshaw commented on Aug 26, 2022

jameskoster commented on Aug 26, 2022

aaronrobertshaw commented on Sep 5, 2022

Update: 5 September 2022

Current Status

Rough guide to current Phase 1 completion:

What's planned for WordPress 6.1

Beyond 6.1

aaronrobertshaw commented on Sep 16, 2022

Update: 16 September 2022

Current Status

Phase 1 completion so far:

aaronrobertshaw commented on Dec 15, 2022

paaljoachim commented on Jan 23, 2023

aaronrobertshaw commented on Jan 25, 2023

t-hamano commented on Feb 27, 2023

4 remaining items

markhowellsmead commented on Jul 2, 2024

aaronrobertshaw commented on Jul 2, 2024

markhowellsmead commented on Jul 3, 2024

markhowellsmead commented on Jul 3, 2024

aaronrobertshaw commented on Jul 3, 2024

Marc-pi commented on Jul 3, 2024

markhowellsmead commented on Jul 3, 2024

aaronrobertshaw commented on Jul 3, 2024

andrewserong commented on Jul 3, 2024

t-hamano commented on Jul 28, 2024

aaronrobertshaw commented on Jul 29, 2024

simison commented on Aug 9, 2024

aaronrobertshaw commented on Aug 9, 2024

aaronrobertshaw commented on Sep 8, 2026

aaronrobertshaw commented on Sep 17, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions