search

WordPress / gutenberg

The Block Editor project for WordPress and beyond. Plugin is available from the official repository.
https://wordpress.org/gutenberg/
Other
10.24k stars 4.09k forks source link

Tracking: Addressing Design Tooling Consistency #43241

Open aaronrobertshaw opened 2 years ago

aaronrobertshaw commented 2 years ago

Overview

This issue will outline and track efforts toward increasing consistency across all our blocks and their design tools.

Goal

  1. To ensure as few gaps in design tools and block supports across blocks as possible.
  2. For any omission of support to be a deliberate and documented choice.

Opportunities to Improve Consistency

General Approach

An initial audit of blocks vs block supports/design tools has already been conducted to assist in identifying gaps in our support. This current state of our design tools will be outlined per block support in sub-issues tracking them.

Phase 1 - Adopting all supports, for all blocks

This involves creating a suite of PRs to opt into any missing supports for all blocks.

As with most things, there will be edge cases adopting various supports that might slow down the process. Given the time remaining before the 6.1 code freeze, we'll need to be fairly pragmatic here to ensure we get the design tools added in time. We can refine the UX and smooth out some edge cases as "bug fixes" after the initial beta is cut.

Low hanging fruit in this phase will be any support that can simply be opted into and works out of the box. Essentially, supports where the resulting styles can be applied to the block's wrapper. Anything that involves skipping serialization of block support styles will likely take longer to ensure compatibility with theme.json and global styles.

An approach to addressing a missing block support might be:

  1. Identify a gap you'd like to fill via the individual block support tracking issues (linked in section below)
  2. Search GitHub for existing PRs that might expedite or inform your efforts.
    • Terminology used in this area is often extremely varied so you might need to get creative with your searches.
  3. Create PR to adopt missing support (updating block.json, edit.js/index.php etc if skipping serialization).
  4. Double check similar or related blocks and make the default controls exposed by the block support match.
  5. Update the block support's tracking issue, linking the PR within the block supports table
  6. Ping for review

Phase 2 - Consistent Default Controls

Once we have all blocks adopting all block supports that are viable for them, we'll need to make which controls are shown by default as consistent as possible.

This might involve updating each block support to define a set of default controls. Once that is available we can remove default control specification from individual block.json files unless there is a glaring need for a given block to override things. In such a case, that should be discussed in its own dedicated issue/PR.

Alternatively, we might wish to display different sets of default controls for related groups of blocks. The difficulty here is that some blocks might span multiple "block groups" leading to some of the inconsistencies we are trying to avoid.

Phase 3 - Stabilization, Follow-ups, and Documentation

By now, the vast majority of gaps should be filled, and we can revisit any blockers that prevented block support adoption, refine edge cases, refactor blocks etc.

Given the widespread adoption of supports, now is also the time to stabilize the block support APIs.

Now might also be the time to pursue new block supports that may replace ad hoc or bespoke controls. For example, several blocks have width, height, or size-related controls.

In addition to the follow-ups, we should have a clearer view of how many exceptions there are to the "all supports, all blocks" goal and their reasons. This will help inform us of how best to document these exceptions to reduce the occurrence of users feeling that something is "missing".

Further Follow-ups

Tracking Issues for Individual Block Supports

jameskoster commented 1 year ago

Might it be worth considering https://github.com/WordPress/gutenberg/issues/43082 as a part of this work?

aaronrobertshaw commented 1 year ago

Thanks for flagging #43082 @jameskoster 👍

It's a little out of the scope I originally intended here. That said, the more widespread adoption of block supports does increase the exposure of the issue outlined in #43082. I agree it can be considered under the banner of "consistency".

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 https://github.com/WordPress/gutenberg/pull/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.

jameskoster commented 1 year ago

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!

aaronrobertshaw commented 1 year ago

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.

jameskoster commented 1 year ago

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

aaronrobertshaw commented 1 year ago

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.

aaronrobertshaw commented 1 year ago

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.

aaronrobertshaw commented 1 year ago

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

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.

paaljoachim commented 1 year ago

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

aaronrobertshaw commented 1 year ago

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.

t-hamano commented 1 year ago

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 🙏

Marc-pi commented 1 year ago

@aaronrobertshaw would be great to update the stats. What's planned for 6.3 ?

aaronrobertshaw commented 1 year ago

This is an experimental block, but please add it to each table if needed

@t-hamano, I think it can be added once it's no longer experimental. That said, if anyone feels differently, anyone can update the tracking issues with up-to-date information.

would be great to update the stats. What's planned for 6.3 ?

@Marc-pi I can provide another stat update soon.

Focus generally shifted away from filling design tool gaps toward higher priority issues for 6.2, and wrapping up Gutenberg Phase 2. In addition, we needed to address the crowded sidebar (https://github.com/WordPress/gutenberg/pull/45005) and provide more flexibility in how Global Styles for different design tool features could be applied to blocks (https://github.com/WordPress/gutenberg/pull/46496).

In terms of what's planned for 6.3, we'll continue to chip away here although my understanding is that more focus will be given to laying groundwork for improved workflows, collaboration, and Gutenberg Phase 3 in general.

Anyone is welcome to submit PRs adopting design tools for blocks they feel are missing them. The more contributors that can help here the better, as it will be a slow process otherwise.

aaronrobertshaw commented 1 year ago

Update: 30 March 2023

Current Status

The adoption of specific design tools for individual blocks became a lower priority as the proliferation of tools in the sidebar became a usability issue. For 6.2, the organisation of the Block Inspector has been updated with the introduction of tabs within the sidebar.

The initial rush of design tool adoption was anticipated to slow naturally as easier adoptions were cherry-picked. What we began to find after that was that we were facing an increasing number of blocks that had edge cases we couldn't quite resolve e.g. ensuring that the application of global styles matched the styles provided by individual block supports. It's expected that with Gutenberg 15.5, we'll have access to a stabilized and extended block selectors API. This will provide us with much greater control over the application of global styles and should unblock further design tool adoption.

Over the last couple of WordPress releases, we've also had new layout supports introduced. These caused an unfortunate regression with margins which blocked several blocks from adopting more spacing supports. A fix for this is almost ready to land.

While the adoption of design tools across blocks hasn't progressed rapidly in the last few months, a lot has been done to position the project for another push. Anyone with the bandwidth to submit PRs filling design tool gaps is encouraged to do so.

Phase 1 completion so far:

Block Support Blocks with Full Support No Support Required Postponed # Open PRs % Complete
Typography 64 14 0 0 92.86%
Spacing 51 1 0 9 61.9%
Layout 13 * 0 0 0 56.52%
Color 53 ** 5 0 1 69.04%
Border 15 1 0 2 17.88%

* 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.

t-hamano commented 1 year ago

@aaronrobertshaw

I think it can be added once it's no longer experimental. That said, if anyone feels differently, anyone can update the tracking issues with up-to-date information.

I also added Time To Read block to Tracking Issues for Individual Block Supports since the experimental Table Of Contents block was already present in the listing.

markhowellsmead commented 1 month ago

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.

aaronrobertshaw commented 1 month ago

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.

markhowellsmead commented 1 month ago

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.

markhowellsmead commented 1 month ago

Note from https://github.com/WordPress/gutenberg/issues/63050#issuecomment-2204856481:

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.

aaronrobertshaw commented 1 month ago

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.

Marc-pi commented 1 month ago

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

markhowellsmead commented 1 month ago

@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.

aaronrobertshaw commented 1 month ago

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 (https://github.com/WordPress/gutenberg/issues/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 ```
Hello World :)
```
andrewserong commented 1 month ago

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.

t-hamano commented 3 weeks ago

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

aaronrobertshaw commented 3 weeks ago

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.

simison commented 1 week ago

@aaronrobertshaw related to design tooling:

aaronrobertshaw commented 1 week ago

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 https://github.com/WordPress/gutenberg/issues/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.