Applying design system foundations to the Block Toolbar

[jameskoster]

In recent weeks, several components and elements of the block editor have been refreshed to align more closely with core design system foundations, particularly regarding corner radius and elevation. The block toolbar remains one of the last significant UI pieces awaiting this transformation. This issue explores updates to the toolbar that would create a more unified experience by bringing it into harmony with the wider design language.

The mockup above demonstrates some small but impactful changes aimed at refining the toolbar’s appearance.

Increased Corner Radius

Currently, toolbar buttons have a 2px ($radius-small) corner radius. By increasing the toolbar’s corner radius to 4px ($radius-medium), we achieve a more cohesive look:

• Radius now aligns with the updated Menu component, commonly accessed from the toolbar.
• Buttons ‘nest’ more neatly inside the toolbar:

Side note: Based on the 8px padding there may be an argument to slightly increase radius-medium for perfect nesting:

We can discuss that here, or separately. Thanks to the recent efforts around formalising these details and the application thereof, such changes are trivial.

Applied Elevation

elevation-medium adds a subtle but effective shadow that visually lifts the toolbar from the content below. This update better aligns the toolbar with other contextual components (such as the Menu), that also leverage this elevation to emphasize actionable items without overwhelming the layout.

Applied to components that offer additional actions to the user. This elevation level helps differentiate actionable elements that appear in context without requiring major focus shifts.
https://wordpress.github.io/gutenberg/?path=/docs/foundations-design-language-elevation--page

Border Tweaks

With this elevation applied, the need for a heavy outline is reduced. Softening the border offers two key advantages:

1. Simplified Menu Styling: By adopting a subtler outline, we eliminate the need for a custom style variation when the toolbar invokes menus, streamlining Menu component integration.
2. Improved Dark Mode Consistency: The updated border style allows the dark toolbar to maintain a polished look that aligns seamlessly with the light mode toolbar.

Additionally the dividers between button groups are shortened to match the footprint of the adjacent buttons, aligning to a convention applied in the Menu component.

---

These adjustments are a step toward a more cohesive and visually refined block editor, enhancing the overall user experience without compromising functionality. They also allow facilitate the simplification of the Menu component by recommending the use of only a single variant.

Let's discuss which changes (if any) have the most merit.

@WordPress/gutenberg-design

[jasmussen]

Changes to shadow, border, and separators, feels less a clear win, and does not seem a logical conclusion to applying foundations from the design system:

• Elevation can be zero, close to the document: since the block toolbar is cropped by the block inspector, after all elevation zero would match its current behavior.
• The border serves to clearly delineate UI from content, which the full dark version does intrinsically as well.
• Being consistent with dark mode is perhaps also mostly theoretical, as dark mode is never a clean inversion, there's always going to be a set of colors that need special treatment to ensure the luminosity is balanced.
• The verticalseparators that no longer go edge to edge makes for a more complex silhouette: instead of separate sections it becomes a single section with additional elements.

The proposed radius changes make sense, as they follow a clear heuristic of inheritance. But applying the other changes, the toolbar loses some distinctiveness without a clear win.

[jameskoster]

There’s definitely room for discussion about whether the toolbar should be an exception to certain system principles. If exceptions are made, it’s important to document them, providing clear reasoning and guidance on when and where specific variants should be used.

That said, I believe it's healthy to periodically examine exceptions, as most design systems advocate minimizing them wherever possible. As a provocation; if we believe block toolbars and their menus warrant a strong outline with zero elevation, why aren’t these traits applied consistently to all menus—or to the dark toolbar found in Write mode?

If we consider the block toolbar a WP branding element then it's a bit easier to reason about, otherwise I'm not sure.

[jasmussen]

There’s definitely room for discussion about whether the toolbar should be an exception to certain system principles.

I don't know that the border is an exception. I'll support that the principles are missing for the block toolbar pattern, though, but we can create those.

if we believe block toolbars and their menus warrant a strong outline with zero elevation, why aren’t these traits applied consistently to all menus—or to the dark toolbar found in Write mode?

As far as the elevation, this is practically in place since block toolbars and their menus are below the top toolbar and the inspector. Menus that invoke from those, on the other hand, are above both top toolbar, inspector, and canvas, and are thus elevated.

I'd think it a value of a design system that it allows some freedom within the boundaries of the guidelines, though the principles of the the dark border are about ensuring contrast between block UI and content, which would also then explain the dark border around the Placeholder component. In true dark mode (as in: user-chosen or set by the operating system), then the Placeholder would likely have a black background too, and should then have a similarly strong light border. I agree there's some work to do on the current iteration of the dark toolbar.

[richtabor]

Also of note, the toolbar should not have blurry edges here; there are a few tricks to avoid this. And medium shadow feels a bit heavy on light backgrounds.

The verticalseparators that no longer go edge to edge makes for a more complex silhouette: instead of separate sections it becomes a single section with additional elements.

Agree.

[jameskoster]

The verticalseparators that no longer go edge to edge makes for a more complex silhouette: instead of separate sections it becomes a single section with additional elements.

Do y'all think Menu should be consistent about this detail?

[jasmussen]

Do y'all think Menu should be consistent about this detail?

To be fair, that's been the case for the classic menus:

I'd think menus should be consistent with each other. I'd also lean towards edge to edge there, since the same argument for silhouette applies, though it is less pronounced because of the lighter gray. But this is not a strong opinion.

[jameskoster]

The menu details are worth considering, as it can be argued that there's a lot of semantic overlap between toolbars and menus. They're often connected in the UI (I think almost 100% of block toolbars include a menu), so it may be worth creating more cohesion between them. This can be an opportunity for the software to guide the system a bit.

Trying a few things...

• Full-bleed dividers in both toolbars and menus for consistent silhouette
• Increased gap between menus and submenus to match the gap between block toolbar and its menus
• Increase menu padding to match toolbar
• Decreased elevation on Toolbar
• 40px → 32px menu item height, for consistency with toolbar buttons (this could be a big win on long menus):

[jasmussen]

I think it's slightly misleading to show the block toolbar and menus without actual content to surround it, because it's that content—including the role of the placeholder—that originally informed the G2 design (#18667). That's an important aspect to stress test with these explorations.

The latter shows the block toolbar being underneath the top toolbar, which is one of the main argument for me as to why this is at elevation zero.

[jameskoster]

The latter shows the block toolbar being underneath the top toolbar, which is one of the main argument for me as to why this is at elevation zero.

Since this isn't documented it's a little ambiguous. The arrangement could be interpreted a couple of ways;

1. The canvas slides underneath the top bar as you scroll, like you describe
2. The canvas scrolls independently, never underlapping the top bar—they occupy the same elevation level

It's important to consider because it affects the elevation. If it's the former like you suggest, doesn't that indicate that the top bar should be painted as a level above the canvas in terms of elevation? In other words the block toolbar would be level 1, and the top bar would be level 2. This can help remove the ambiguity by creating clearer separation between the page and the edit UI.

[jasmussen]

Yes, the logical consequence of adding elevation to the block toolbar would be adding a higher elevation to the other elements that are above it. But that is a design choice: shadows are not intrinsically necessary to indicate elevation, it's just one way to do it. Other ways are distance, scale, scrims, blur, parallax, and borders. Older Google guidelines provide a decent overview of what their goal with elevation, which is to ensure contrast between different layers, those layers existing separately to aid orchestration such as animation and point of origin.

[jameskoster]

Shadows were used only because that's the established treatment we find amongst the existing components (menus, modals, etc). Totally agree there are other approaches we might consider—I quite like how Apple uses blur as a background filter, with varying opacities. The nice thing about formalising the application is that it makes it trivial to quickly try these different options.

[fcoveram]

Interesting conversations here.

I like the subtle shadow of elevation-medium. I don’t envision risks in blending the Block Toolbar with the canvas level in both light and dark backgrounds. In addition to building depth, motion also plays a role in how elements show up. The level where Block Toolbar is placed is also built by how other UI parts behave.

Regarding the silhouette, edge-to-edge works better for recognizing groups and relationships. The grey divider is a low-contrast decision that needs other visual traits to complement it.

In a similar spacing topic, the submenu feels detached when there is a gap with its ancestor. The overlap layout conveys better the meaning of dependency.

The menu item height is a great exploration and I do see benefits, but I think this approach belongs to a density level that users set when landing on the admin page for the first time. The current 40px as default works well, especially in big displays. Leaving that to user preferences could be the best path for this spacing treatment.

Regarding the top bar elevation, I think that occupying the same level as the canvas. By itself, surrounded by the browser’s UI, and in the browser context where other sites are on the screens, it looks like any site on the web where the header allows to navigate internal pages and the content below lives as a page. In this case, the top bar and side panels frame the canvas like rules placed on the sides of a sheet of paper to extend its characteristics.