[Visual Refresh] New shadow tokens and utilities

[mgadewoll]

Summary

Implements https://github.com/elastic/eui-private/issues/195

Important

This PR merged into a feature branch.

Note

This PR is continuing the work started in #8880 but implements a different approach for applying floating borders.

Selected implementation approach

The previous PR implemented a different approach to handling shadow tokens, which aligned directly with design specs and included an additional layer for Dark mode shadows for the expected floating border.

This new PR now implements an alternative approach: the floating border is not part of the shadow but instead added next to the box-shadow style as standalone border style.

Both approaches have their own benefits and downsides, there is no perfect solution. The ultimate decision to implement floating borders as standalone border was based on a comparison of possible impact and maintenance.
The deciding factor for the border approach was that it provides flexibility for the cases that need it while the box-shadow approach is more rigid which could lead to blocking issues if they arise.

approach	pro	con
box-shadow only	- tokens match design implementation - no dimension changes between color modes - shadow placement outside of the border-box prevents duplicate borders in compositions "by accident"	- "misuse" of box-shadow as border (consumers will rather apply border on customizations which will result in double borders) - ⚠️ dimension differences in combination with components that use border because box-shadow sits outside the border-box - ⚠️ box-shadow floating border can be cut off if an ancestor has overflow: hidden - ⚠️ the floating border layer is applied to all sides and does not allow for side-specific usages
border	- most "native" border usage - easy to adjust in customizations - supports side-specific borders or removing floating borders entirely	- tokens don't match 1:1 design (removed floating border layer) - ⚠️ dimension changes between LIGHT and DARK mode due to border width difference - ⚠️ borders "add up" in compositions (native/expected behavior; will require floating borders to not always be on all sides)

ℹ️ For the in depth comparison of the approaches with examples see this comment.

Changes

Note

The new tokens have been added as SCSS and JSON exports as well.
⚠️ The new shadow utils have not been added to SCSS, only existing utils have been updated. This is because EUI does not officially supporting SCSS anymore.

• adds new shadow tokens to the theme

{
  colors: {
    base: string;
  };
  xs: { up, down };
  s: { up, down };
  m: { up, down };
  ml { up, down };
  xl: { up, down };
  hover: {
    base: { up, down };
    xl: { up, down };
  };
  flat: { up, down };
};

• updates existing shadow utils to use new shadow tokens

  • euiShadow
  • euiShadowXSmall
  • euiShadowSmall
  • euiShadowMedium
  • euiShadowLarge
  • euiShadowXLarge
  • euiShadowFlat
  • euiSlightShadowHover

• adds new shadow hover util

  • euiShadowHover

• separated shadow SCSS per theme instead of shared through eui-theme-common

• adds documentation for shadow tokens and utils

Why are we making this change?

Design feature: Updating shadows as part of the Visual Refresh project.

Screenshots

direction	LIGHT	DARK
down
up

HCM

direction	LIGHT	DARK
down
up

Impact to users

🟢 The are no updates needed on consumer side.

⚠️ There are breaking changes in the eui-theme-common package. (this generally is not an issue as it's a direct dependency on eui it might only be an issue with different versions of eui available)

QA

ℹ️ The changes have also been deployed to Kibana here (login)

• verify the added shadow tokens match design specs (minus the floating border layer in dark mode)
• review updated components and verify dark mode and high contrast mode look as expected (floating border without double border, border only in HCM)
  • EuiPanel / EuiCard (e.g. on interactive hover)
  • EuiHeader
  • EuiCollapsibleNav
  • EuiCollapsibleNavBeta
  • EuiBottomBar
  • EuiFlyout
  • EuiPageTemplate
• review the added documentation for shadow tokens and shadow utils

General checklist

• Browser QA
  • Checked in both light and dark modes
  • Checked in both MacOS and Windows high contrast modes
    • (emulate forced colors if you do not have access to a Windows machine.)
  • Checked in mobile
  • Checked in Chrome, Safari, Edge, and Firefox
  • Checked for accessibility including keyboard-only and screenreader modes
• Docs site QA
  • Added documentation
  • Props have proper autodocs (using @default if default values are missing) and playground toggles
  • Checked Code Sandbox works for any docs examples
• Code quality checklist
  • Added or updated jest and cypress tests
  • Updated visual regression tests
• Release checklist
  • A changelog entry exists and is marked appropriately.
  • If applicable, added the breaking change issue label (and filled out the breaking change checklist)
• Designer checklist
  • If applicable, file an issue to update EUI's Figma library with any corresponding UI changes. (This is an internal repo, if you are external to Elastic, ask a maintainer to submit this request)

[ek-so]

Thanks for your patience and all the huge work @mgadewoll!

A couple of comments / questions:

1. A per this statement — do we leave shadowFlat and euiSlightShadowHover in place? I guess the intent was no to, and we don't have it in design now.
2. I assume, in some places like maps, we have some things that are slightly broken (current QA environment / this PR). Why that might be? It's not a blocker per se, imo, but we will need to fix those (or create a follow up tasks for the teams to do it)

Other than that, everything else looks fine for me.

[ek-so]

Approving not to block, things that were mentioned don't look as a blocker to me.

[mgadewoll]

Thanks for your patience and all the huge work @mgadewoll!

A couple of comments / questions:

1. A per this statement — do we leave shadowFlat and euiSlightShadowHover in place? I guess the intent was no to, and we don't have it in design now.
2. I assume, in some places like maps, we have some things that are slightly broken (current QA environment / this PR). Why that might be? It's not a blocker per se, imo, but we will need to fix those (or create a follow up tasks for the teams to do it)

Other than that, everything else looks fine for me.

@ek-so Thanks for the review!

1. We deprecated those old shadow utils for now. We can migrate implementations first and then remove them fully.

2. Thanks for the catch! Turns out, Kibana is overriding the styles and sets the border to transparent 🫠 It was visible before because we used a pseudo element border for floating borders. I'll fix it on the Kibana testing branch.

[mgadewoll]

ℹ️ Marking this PR as "Draft" again due to an additional concern we haven't considered yet: Potential dimension or position calculations that might be impacted by the floating border difference 🫠

[mgadewoll]

ℹ️ Marking this PR as "Draft" again due to an additional concern we haven't considered yet: Potential dimension or position calculations that might be impacted by the floating border difference 🫠

After looking into the raised scenario on flyouts, it showed that the use case was specific to flyout management. The issue happened due to a border being added in light mode on the parent flyout while the child flyout is being opened which affected the opening animation origin and caused a jump. Adding the border on the child flyout instead prevents the issue.

As this was a very localized issue that can easily be prevented, we're good to proceed with the review of this implementation proposal.

[acstll]

Thank you @mgadewoll for going the extra mile with this one. I think it's working great!

I followed the QA process (except for testing in Kibana directly) and it's all working as expected. I also checked the values match the spec, and that values in JSON and SCSS are correct and aligned (used an LLM for both of these).

Most comments are regarding the docs, and one regarding an API. Everything else looks good…

Thanks again!

[acstll]

Thanks for the updates! 💅

I spotted 2 console.logs, not approving yet in case you didn't leave them there intentionally.

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: e6bd17a
• Documentation website
• Storybook

History

• 💚 Build #1207 succeeded 9bf0ab8
• 💚 Build #1063 succeeded ed1b12d
• 💚 Build #1062 succeeded 46612bd
• 💚 Build #1061 succeeded a1aa020

cc @mgadewoll

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: e6bd17a

History

• 💚 Build #4689 succeeded 9bf0ab8
• 💚 Build #4587 succeeded ed1b12d
• 💚 Build #4586 succeeded 46612bd
• 💚 Build #4585 succeeded a1aa020

cc @mgadewoll

[acstll]

🟢 Thanks again for the updates, amazing work ✨