Add Box Shadow Component

[phil-sola]

What problem does this address?

So as of Gutenberg 14.1 and in the upcoming WordPress 6.1 release, there will be support added for themes to register box shadows for specific blocks within the theme.json file.

Similar to padding, margin, typography, etc. I feel like it would be beneficial to actually have a box shadow component either for importing from a package for custom blocks or supported in core blocks which would enable users to create the exact shadow effect they are looking for.

What is your proposed solution?

Adding a box-shadow component within one of the packages which can be imported for custom block development or supported in core blocks which would enable users to create the exact shadow effect they are looking for.

Something like the 'Customize shadows' section on the left in this link: (https://box-shadow.dev/)

Including horizontal, vertical, blur, spread, and colour.

I searched issues for 'box shadow' and 'box-shadow' and couldn't find anything on this, however, I know it might already be something being looked at, apologies if so.

Design

• Shadow panel is empty by default.
• Clicking + opens a menu where you can choose shadows from three categories:
  • Core presets ('Natural', 'Deep', 'Sharp', etc.)
  • User-generated presets from global styles (Shadow: create / edit shadows in the global styles #57100)
  • A custom shadow
• When a preset is added;
  • Clicking the row will re-open the menu so you can switch to a different preset
  • Clicking the – icon will remove the shadow
  • Clicking the unlink icon will detach the shadow properties, essentially switching from the preset to a custom shadow...
• When custom shadow(s) are added;
  • Clicking a row will open a popover where you can edit the associated shadow properties.
  • Clicking + will add a new shadow to the stack
  • Clicking ⋮ will allow you to save the custom shadow as a preset for future use

Tasks

• add box-shadow support for blocks via theme.json #41972
• Shadow: add shadow presets support via theme.json #46813
• Add box shadow support to blocks (using code editor for now). #46896
• Shadow: Add shadow presets and UI tools in global styles #46502
• Shadow: add shadow in block settings (site editor) #57101
• Shadow: enable shadow for more blocks #57103
• Shadow: create / edit shadows in the global styles #57100

[Jabe64]

+1 for this 💯 It should be listed in #33447 too.

[dkjensen]

+1

[jasmussen]

CC: @WordPress/gutenberg-design

[paaljoachim]

Hey Joen. It looks like a good start!

[madhusudhand]

@jasmussen Thanks for the designs. They look great!

I mocked up controls for Angle and Depth instead of X-position and Y-position, as that seems more ergonomic.

I like this idea and I would like to believe, a formula should transform these values to X,Y (apply in CSS) and also reverse transform them without issues.
I will work on this transformation (formula) and provide more detailed feedback.

A preset shadow is applied by clicking the plus, this adds an Item on the right

I would like to imagine shadow presets to behave similar to colors.
There would be Default Shadows (defined in Gutenberg) and Theme Shadows (defined in theme.json)

And a shadow preset could be a combination of multiple shadows that create a unique effect.
e.g.

This is a result of two shadows box-shadow: 5px 5px 0px -2px #DDCFFF, 5px 5px #040DE1.

A theme should be able to define them in theme.json as follows.

{
    "settings": {
        "color": {},
        "shadows": [{
            "name": "Double lines",
            "slug": "double-lines",
            "value": "5px 5px 0px -2px #DDCFFF, 5px 5px #040DE1"
        }, {
            ...
        }]
    }
}

Long story short:

Because a preset can have multiple shadows and they become preset variables (based on the given slug), the UI experience for them should slightly be different.

Following are my thoughts:

• The panel shows presets just like design suggests (but both default and theme shadows)
• When a preset is clicked, it ads a single row (just like custom shadow), but it remains read-only
• It indicated as preset and name comes from the theme.json.
• There should be a new section under global styles, Styles -> Shadows (similar to editing the color palette) where they can be edited.

This way, a preset shadow can be applied to any block and changing it in the global settings would effect all the blocks.

Let me know your thoughts.

[jasmussen]

I like this idea and I would like to believe, a formula should transform these values to X,Y (apply in CSS) and also reverse transform them without issues.

Thank you! If it becomes a headache, don't spend too much time on it, we can start simpler if need be. For example it hits me that it might not be possible to represent all box-shadow configurations with this setup, as the angle+depth components assume that the X and Y values will always be the same. We might need a different angle component, one that's more of a map/grid, for this to work 🤔

I would like to imagine shadow presets to behave similar to colors.
There would be Default Shadows (defined in Gutenberg) and Theme Shadows (defined in theme.json)
A theme should be able to define them in theme.json as follows.

Yes.

When a preset is clicked, it ads a single row (just like custom shadow), but it remains read-only

Thanks for surfacing this shortcoming. I don't think we should make a read-only preset, they should all be editable. But I'll need to think about how to best surface multiple stacked shadows in the panel when applying a preset. Let me return here with some new mockups!

There should be a new section under global styles, Styles -> Shadows (similar to editing the color palette) where they can be edited.

Working on this mockup made me realize a shortcoming of our current global styles. Right now you have Typography, Colors, Layout. Layout includes various values — margin and block spacing for Buttons, and border and border radius for Image. For both Typography and Color, these two blocks (Buttons, Image) have panel counterparts. But there's no counterpart in Global Styles for Dimensions and Border — those are put inside "Layout" instead.

And so I'm not sure we should add a new "Shadows" in Global Styles. I think we should either:

1. Accept that Global Styles has a trio of Typography, Color, and Layout, and put "Shadows" under Layout.
2. Change Global Styles so that it gets a new "Border & Shadows" section, as well as a "Dimensions" section, to match the panels present for each block. This would let the "Layout" section continue to exist for things like Group, which have a Layout panel, but it would also make the Layout section not become a junk drawer for things that don't fit in color or typography.

We should probably start with 1, as 2 has some compounding effects. What do you think?

[jasmussen]

Having tinkered a bit with this now, it's clear that approach I had thought of with regards to layered shadows that I was thinking of, inspired by #39427, is unlikely to work for stacked shadows for us. Quite simply, the fact that a preset can contain all stacks, means the UI to control each layer, would need to be surfaced in the flyout. I think I need to explore an entirely different approach to the presets, which as already noted, felt like the weakest aspect. I'll need more time to think on this.

One question — I really like this shadow generator, which creates 3 shadows by default. Would it be possible to have something like that for the default editor? Then perhaps we could put advanced editing of each individual layer behind an toggle, that would let you edit each layer individually? Essentially any non-standard preset, such as the sharp square shadow in your example, would then become an "advanced" shadow.

[jasmussen]

Based on explorations, I have some new concepts to share, that should hopefully be simpler for the first version.

I would imagine we could start with a preset-first design:

• Structure remains the same: Border & Shadow → Block name, click the plus to add a shadow, the default preset gets added by default.
• Clicking the flyout now lets you pick between default and theme presets first, though, and presets are just text buttons like style variations, relying on the inspector preview.
• A cog can let you edit a shadow using basic existing properties. Doing so collapses any stacked shadows into a single shadow, for simplicity.
• We can even start this first version without any shadow editing controls at all, if that's simpler, just presets.
• It would be useful to figure out whether we create a new section called "Border & Shadow" and move Border + Radius controls there (CC: @WordPress/gutenberg-design). As an alternative, I think we should put "Shadow" under "Layout", where Border and Radius live at the moment. This may be simplest for the first version.

A followup would be to enable shadows in the post editor:

• I would think this necessitates a decision on how Global styles categories (Color, Typography, Layout) map to block panels (Color, Typography, Layout, Border, Dimensions), as noted above. They are close, but not quite the same, and we should avoid creating an entirely new panel just for shadows. So what's a good place to put shadow controls? This mockup suggests renaming the Border panel to "Border & Shadow".

Not for the first effort, but I think there's a fun opportunity tied to the UI for editing drop shadows. It is possible to create beautiful natural-looking shadows by stacking multiple shadows at various depths, and I would love for us to include an algorithm for doing this, which could potentially be controllable like this:

It's not something for the near term, but once you're in the shadow editing control, we might as well provide excellent shadows by default.

What do you think? CC: @madhusudhand @scruffian

[jameskoster]

This seems to work well. We could even double-down further on the presets, and save the user a click by surfacing them in the + menu:

This may work best with a dedicated section, similar to Figma's "Effects" panel. Perhaps that's worth considering if we intend to support filters and other similar features in the future.

[jasmussen]

Nice, I can see further simplification work. Though I abandoned the idea of showing a shadow preset in that small 20x20 area in the ItemGroup, it simply didn't have space enough to be legible at that size, and there's a preview above, after all.

I'm not sure about the unlink, though: what what would the main action of the ItemGroup be?

[paaljoachim]

This looks really good!

[jameskoster]

I'm not sure about the unlink, though

I suppose an alternative would be a remove/delete action. But then you couldn't create a custom shadow from a preset base.

what what would the main action of the ItemGroup be?

Do you mean what happens on click? One option would be to just open the shadow menu:

[richtabor]

I like the idea of presets as well — we use them for font sizes, spacing, colors... may as well for shadows. Any reason why we wouldn't reuse the existing stepped range control pattern? And if the icon is pressed, you see a detailed edit view of that preset — basically like how border controls work.

And second, if we wanted to merge some of these panels, we could package them as tool belt items in an "Effects" panel. Border would fit in well for example.

Also it doesn't have to be integer based (maybe the slugs are, but not the label).

[jasmussen]

I tend to think we should stick to the pattern of ItemGroups opening flyout menus, and since there's a preview in the canvas for the post editor, and in the top right of the inspector for global styles, the simple shadow icon feels like a better starting point to me. But perhaps we can follow the PR and see what feels right as we move closer?

And if the icon is pressed, you see a detailed edit view of that preset — basically like how border controls work.

Not sure I understand. Do you mean something like this?

While we could have presets inside that flyout, the unique challenge with shadows is that in theme.json you can apply a stacked shadow consisting of multiple separate definitions, and have that be a preset. That's why I ended up thinking the preset-first approach was the simplest way to start. Let me know if I missed a beat here!

Another aspect of the preset-first approach, is to enable the more creative uses of drop shadows like this example Madhu shared:

Any reason why we wouldn't reuse the existing stepped range control pattern?

My instinct would be that we need more finegrained control here. That said, I see where you're coming from — each step of the slider could theoretically represent a predefined elevation. It's the same instinct that led me towards this mockup, where I'm picturing each dot on the grid to be an "elevation slot", and then multiple stacked shadows are calculated based on the elevation, light position, and sliders. So you'd still have these predefined steps, but you'd also have directionality in the mix.

[madhusudhand]

Great designs! 🎆

The dropdown of shadow presets is missing the theme presets.
Can you accommodate both default and theme presets with labels may be?

And a question on how it should be invoked.
All the style sections use ToolsPanel that comes with options such as reset styles on click of vertical dots

Do you suggest to have a + button beside it? or a label like Add shadow as one of the option?

[jasmussen]

@madhusudhand I'm not convinced we should go with the immediate dropdown, I still think it's best to use the ItemGroup with the flyout pattern that shows "Default" and "Theme" presets using the same buttons as are present in the Styles panel. We can omit the "Settings" icon for now though.

That would make the shadow control a single control for now, so not yet any stacked shadows. I'm unsure yet how to best surface such stacked shadows, but I'm leaning towards if we ever do that, it should probably be inside the flyout, because presets themselves can come as stacked definitions.

[madhusudhand]

That would make the shadow control a single control for now, so not yet any stacked shadows.

That will be a good start from UI perspective.

For context, a stacked shadow need not be always from a preset.
A theme developer can define stacked shadow for a button only (not a theme preset) in theme.json and it is a custom stacked shadow. In such scenarios, how should we represent that a shadow is applied to the block?

In the first step, because edit controls aren't there, UI should somehow indicate that a custom shadow is applied, because setting it from theme.json is already possible.

Eventually, it should work bi-directional.
Set a custom or preset shadow (single or stacked) from the UI.
Parse a custom or preset shadow from theme.json and show in UI. Let users edit that.

I'm leaning towards if we ever do that, it should probably be inside the flyout, because presets themselves can come as stacked definitions.

I am not sure if it is best to edit the presets (global in nature) from button styles panel.
User might think that shadow they are editing is for the button, but because the presets are global, they can effect all other blocks that are using it.

But in other perspective, a user might want to do minor tweaks to the preset shadow, and apply to the button.
I guess, on edit, it is best if the preset is copied as custom shadow, and apply to the block.

I am thinking for color, I cannot change default or theme palette colors such as Primary from a button styles panel.
I would have to edit them from global styles -> colors only because they effect everything.

[jasmussen]

For context, a stacked shadow need not be always from a preset.
A theme developer can define stacked shadow for a button only (not a theme preset) in theme.json and it is a custom stacked shadow. In such scenarios, how should we represent that a shadow is applied to the block?

I'm assuming this shadow definition would come from theme.json directly? Good question. We probably need an interface for this, but for the near future, would it make sense to add a "Default" button to the "Theme" section, which embodied this?

I am not sure if it is best to edit the presets (global in nature) from button styles panel.
User might think that shadow they are editing is for the button, but because the presets are global, they can effect all other blocks that are using it.

Oh I'm not talking about editing the presets here, that's probably a separate thing and more related to #44417. Let me know if I misunderstood something here.

So that is to say, I can understand we need to be able to both apply a preset to a block, and add an entirely custom shadow to a block, and that we need to be able to do this both locally on a per-block basis, and globally to apply by default across all buttons, for example. Right?

[seothemes]

This is looking really good. Here's a few important things to consider for box shadows that I haven't seen mentioned:

• Hover state
• Theme.json defaults
• Inset value

This a screen recording of how each is handled in the Blockify theme:

box-shadow-hover.mov

Changing just one of the values will enable a box shadow and inherit the remaining values from the theme. This also applies to the Hover state which inherits from the Default state for values that are not set.

We should also consider adding support for Inset values from the beginning too, as that could be difficult to add in the future.

[madhusudhand]

So that is to say, I can understand we need to be able to both apply a preset to a block, and add an entirely custom shadow to a block, and that we need to be able to do this both locally on a per-block basis, and globally to apply by default across all buttons, for example. Right?

Thats correct. It would be the final goal.

[jasmussen]

It remains something we should get to. I would love fresh mockup work, and subsequent dev work, but I will admit it's looking close.

[richtabor]

I think it's fine this slips. It's quite contained as-is and not high exposure.

[ndiego]

@jasmussen @richtabor cool if I remove this from the 6.3 Project Board? We are virtually out of time for enhancements.

[richtabor]

if I remove this from the 6.3 Project Board?

Sure thing.

[jameskoster]

Revisiting this. @SaxonF there are two things I'm not able to picture in your concept here:

1. How do you remove a shadow?
2. If a preset shadow (e.g Natural) has multiple props, how are those presented when you click the settings toggle?

[SaxonF]

If a preset shadow (e.g Natural) has multiple props, how are those presented when you click the settings toggle?

@jameskoster this is a good point . We'd have to do something like Figma which is quite complex for us right now. I'm fine with the "unlink" approach if we can start establishing some guidelines around when to use vs customise.

[jameskoster]

If we can avoid adding a new pattern (unlink) that would probably be optimal, so it's just as case of trying to answer the questions above. Here's a take that attempts to do that:

Preset shadows can be removed via the popover (similar pattern exists in color popover). It would probably be fine to have a - button in the Item as well, which could also work nicely for colors, but not required.

The settings icon is on the shadow panel header. Clicking it detaches the preset and exposes each <props> as a separate Item.

There are two potential issues with this approach:

1. Shadow would need to remain its own dedicated panel (unclear to me how important this is).
2. You couldn't stack preset shadows.

Hopefully this inspires some more ideas.

[SaxonF]

@jameskoster coming back to this, I think your unlink pattern might be the easiest starting point and lets us move forward. We can revisit the whole unlink vs customise pattern as we expand other tools.

@madhusudhand I think we're ok to make progress on this and collaborate while dev is in progress since we would like this for 6.4.

[annezazu]

@jameskoster mind updating the design to the latest for what we have in 6.3? For example, here's what we have now:

This will help devs move a bit faster and ensure we don't take a step back accidentally.

[jameskoster]

@annezazu I updated the OP with the latest designs.

[madhusudhand]

To ease the development, the remaining work is split into separate issues. Following is the current status of the work.

• add box-shadow support for blocks via theme.json #41972
• Shadow: add shadow presets support via theme.json #46813
• Add box shadow support to blocks (using code editor for now). #46896
• Shadow: Add shadow presets and UI tools in global styles #46502
• Shadow: add shadow in block settings (site editor) #57101
• Shadow: enable shadow for more blocks #57103
• Shadow: create / edit shadows in the global styles #57100

[vcanales]

Status update

• Shadow: add shadow in block settings (site editor) #57101 — is ready for review. We are now able to display the Effects/Shadow panel on individual blocks depending on their whether they support the feature or not.
• Shadow: enable shadow for more blocks #57103 — Started adding Block Supports for shadow in the previous PR. The changes to the button block there can be used as a guide to implement shadow supports for other blocks.

Created a PR to test block supports after #57101 is merged: #57982

[colorful-tones]

Hey folks,
I wanted to check in to see what is left for this to be ready for 6.5? It looks to be quite close from what I can tell.

Are we looking for more testing or adding in more block supports?

I’m also wondering if we could remove the Needs Design Feedback label? It seems it is beyond that point. 🤔

Thanks for the excellent progress.

[madhusudhand]

wanted to check in to see what is left for this to be ready for 6.5? It looks to be quite close from what I can tell.

We targeted enabling shadow support for more blocks in addition to button block and in block styles. We are addressing some feedback about the placement of the control here

[annezazu]

Removing this issue from 6.5 after confirming the two PRs are listed within the board #57103 & #57101 as this is more of an overview issue of the work than task based at this point.

[bph]

I have been testing the state of box shadow in 6.5 Beta also with shadow presets from the theme.json and I was wondering how I could remove the core box shadow preset?

In the screenshot the first five are coming from core, the custom presets start with the red one. I'd like to not offer too many choices, and remove either all of core presets or single ones.

Should i create an issue for that or is it already built in?

[carolinan]

@bph There is a pull request for opting in or or out via theme.json #58766

[bph]

Thank you @carolinan

[jameskoster]

I updated the 'Design' section of the OP with some updated mockups based on the ongoing work in #57100.

[madhusudhand]

Shadows can now be created/edited in the editor.
Marking this issue as complete. 🎉