[Theme] Support theme level overrides

[mgadewoll]

Summary

Closes https://github.com/elastic/eui-private/issues/281

This PR adds support for theme-specific overrides directly on the theme definition layer.
While we already have ways to override theme tokens (using the modify prop on the EuiProvider) this way is limited to what's available to the provider (e.g. it does not have access to the primitive tokens).

Note

HCM: Currently we add overrides for high contrast mode here.
This use passes overrides via the modify prop to the provider. Anything added there currently is applied to any theme active on the provider, it's a global override.

For theme-specific overrides we instead would want to provide the overrides directly on the definition layer (e.g. here).
A use case we'll need to support this way soon: specific sets of data vis colors in high contrast mode.

The suggested change enables the current theming functionality to support an optional overrides key on the EuiThemeShape and updates the getComputed theming function to include the required overrides (the implementation so far considers HCM (high contrast mode) overrides. The approach follows what's already available for defining LIGHT and DARK variants per color mode. The overrides key is part of the EuiThemeShape (input theme) only, it will not be included on the EuiThemeComputed (output theme).

usage

Note

The code for building and updating themes is old, not that easy to follow and overall rather cumbersome. This PR only adds onto the code for now. In the future (likely once we have fully migrated off Amsterdam and finished Borealis) we might want to consider refactoring those functions in general to improve functionality and maintainability.

Changes

• updates getComputed to support highContrastMode via overrides.HCM on the theme object
• updates inherited color tokens to use computed values (where possible) to ensure tokens are updated accordingly by overrides they inherit from (the alternative would be to have to override each token manually, which a) is still possible but mainly b) seems less favorable in terms of devX)
• removes the @deprecated mark on ink and ghost tokens - while those are not expected in the theme, there is a use case for having true black and white tokens (currently at least for HCM)
• adds HCM override for ink and ghost tokens (resets them to primitive black and white to ensure highest possible contrasts)
• smaller cleanups

QA

• review the testing example for EuiButton with fill={true} here - the custom overrides (code) should apply (and be inherited by the button tokens)(code)

Screen.Recording.2025-04-07.at.17.51.07.mov

• (optional) verify manually locally that overrides work by adding overrides to the theme

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)

[tkajtoch]

The changes look and work good. I want to take a quick look on how the computed works in more detail and what performance implications it has before I approve this. This code is executed early and has direct impact on initial app render

[tkajtoch]

I checked the computed performance and the difference is insignificant.

LGTM

[mgadewoll]

@tkajtoch I rebased with main and additionally added another update (commit) that ensures the following override order (first item = lowest level; each following item overrides the previous):

• theme level
• provider level
• theme HCM override (applies in HCM only)
• provider level HCM override (applies in HCM only)

ℹ️ HCM specific overrides in high_contrast_overrides (file) are currently internal, fixed overrides that can't be manually overridden via the provider.

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 95fe71d
• Documentation website

cc @mgadewoll

[kibanamachine]

Preview staging links for this PR:

• Docs site: https://eui.elastic.co/pr_8558/
• Storybook: https://eui.elastic.co/pr_8558/storybook
• New docs: https://eui.elastic.co/pr_8558/new-docs

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 95fe71d

History

• 💚 Build #3813 succeeded 988ed53
• 💔 Build #3812 failed f0b75e1
• 💚 Build #3806 succeeded 51648a7

cc @mgadewoll