[Meta] EUI Visual Refresh integration and QA

[JasonStoltz]

Quick links:
❓ FAQ
📖 JSON token migration table
🎨 Borealis color token overview
🧹 Deprecated token overview

We have added a new EUI theme to Kibana. In preparation to make it live, we are asking all Kibana codeowners to do the following two things.

1. QA your UI with the Borealis theme enabled.
   • QA instructions can be found here.
   • Please mark your team as Done in the QA Status column when complete. ( Not Started, ⏳ In Progress, ✅ Done )
2. Update your code to comply with the new Borealis color system.
   • Instructions can be found here.
   • Please mark your team as Done in the Code Status column when complete. ( Not Started, ⏳ In Progress, ✅ Done )

If you have questions, please do not hesitate to reach out to the EUI team in the #eui Slack channel (Elastic internal). If you would like guidance from the EUI team on your implementation, you may also add the @elastic/eui-team as reviewers on your PR.

Codeowner	QA Status	Code Status	Point of contact	Design QA
@elastic/search-kibana	✅ Done	✅ Done	@sphilipse	@mdefazio
@elastic/kibana-management	✅ Done	✅ Done	@mattkime	@andreadelrio @jovana-andjelkovic
@elastic/ml-ui	✅ Done	✅ Done	@peteharverson	@andreadelrio @joana-cps
@elastic/response-ops	✅ Done	✅ Done	@cnasikas	@andreadelrio @joana-cps
@elastic/kibana-visualizations	✅ Done	✅ Done	@markov00	@andreadelrio @gvnmagni @MichaelMarcialis
@elastic/fleet	✅ Done	✅ Done	@criamico	@andreadelrio @simosilvestri
@elastic/kibana-presentation	✅ Done	⏳ In Progress	@cqliu1	@andreadelrio
@elastic/kibana-security	✅ Done	✅ Done	@SiddharthMantri	@andreadelrio @jovana-andjelkovic
@elastic/appex-sharedux	✅ Done	✅ Done	@tsullivan	@andreadelrio @ek-so
@elastic/kibana-data-discovery	✅ Done	⏳ In Progress	@kertal	@andreadelrio @l-suarez
@elastic/stack-monitoring	✅ Done	✅ Done	@consulthys (with @weronikaolejniczak)	@andreadelrio
@elastic/kibana-core	✅ Done	✅ Done	@TinaHeiligers	@andreadelrio
@elastic/kibana-esql	✅ Done	✅ Done	@stratoula	@andreadelrio @ryankeairns
@elastic/appex-ai-infra	✅ Done / no UI	✅ Done / no UI	@pgayvallet	@andreadelrio
@elastic/logstash	✅ Done	✅ Done	@jsvd, @mashhurs (with @weronikaolejniczak)	@andreadelrio
@elastic/kibana-gis	✅ Done	✅ Done	@jsanz	@andreadelrio @gvnmagni
@elastic/obs-ux-infra_services-team	✅ Done	✅ Done	@MiriamAparicio	@kkurstak @patpscal
@elastic/obs-ux-management-team	✅ Done	✅ Done	@jasonrhodes	@kkurstak @patpscal
@elastic/obs-ux-logs-team	✅ Done	✅ Done	@tonyghiani	@kkurstak @patpscal
@elastic/obs-ai-assistant	✅ Done	✅ Done	@viduni94	@kkurstak @patpscal
@elastic/observability-ui	✅ Done	✅ Done	@smith / @MiriamAparicio	@kkurstak @patpscal
@elastic/obs-knowledge-team	✅ Done	✅ Done	@viduni94	@kkurstak @patpscal
@elastic/security-defend-workflows	Not Started	⏳ In Progress	@dasansol92	@codearos
@elastic/security-threat-hunting-investigations	⏳ In Progress	⏳ In Progress	@PhilippeOberti	@codearos
@elastic/kibana-cloud-security-posture	✅ Done	✅ Done	@opauloh @maxcold	@codearos
@elastic/security-detection-engine	✅ Done	✅ Done	@rylnd	@codearos
@elastic/security-generative-ai	✅ Done	✅ Done	@patrykkopycinski	@codearos
@elastic/security-threat-hunting-explore	⏳ In Progress	⏳ In Progress	@angorayc	@codearos
@elastic/security-detection-rule-management	✅ Done	✅ Done	@nikitaindik	@codearos
@elastic/security-solution	⏳ In Progress	⏳ In Progress		@codearos
@elastic/security-entity-analytics	✅ Done	✅ Done	@CAWilson94	@codearos
@elastic/security-scalability	✅ Done	✅ Done	@ebeahan	@codearos
@elastic/security-service-integrations	✅ Done	✅ Done	@ebeahan	@codearos
@elastic/security-detections-response	Not Started	Not Started	@yctercero @banderror	@codearos

Running Kibana with the Borealis theme

In order to run Kibana with Borealis, you'll need to do the following:

1. Set the following in kibana.dev.yml: uiSettings.experimental.themeSwitcherEnabled: true
2. Run Kibana with the following environment variable set: KBN_OPTIMIZER_THEMES="borealislight,borealisdark,v8light,v8dark" yarn start

As of #203840, it is no longer necessary to do the above. Kibana main will run with Borealis by default.

However, there are cases where you may still need to change the theme:

1. Serverless still runs on Amsterdam, so you may want to change the theme to Borealis.
2. 8.x still runs Amsterdam. You may want to change the theme back to Amsterdam to test features in Amsterdam before backporting to 8.x

In either case, you would use the following to change the current theme version:

Set the following in kibana.dev.yml: uiSettings.experimental.themeSwitcherEnabled: true

This will expose a toggle under Stack Management > Advanced Settings > Theme version, which you can use to toggle between Amsterdam and Borealis.

QA Instructions

Please QA your UI throughly with the Borealis theme enabled.

If you find an issue caused by Borealis that would block the release, please be sure to create an issue with the label Borealis: Blocker. Our expectation is that you will fix these issues yourself using the provided guidance, leveraging us as a resource if you can't find a solution. The label will let us track progress toward overall readiness.

When QA has been completed, and all critical bugs have been either fixed or logged with the Borealis: Blocker label, please indicate that by changing marking your team as ✅ Done in the QA Status column.

This Design QA doc(Elastic internal) serves as a helpful reference for designers running QA.

Making code changes

Please follow the following guidelines when making changes for Borealis:

Changes may be made directly in Kibana main. Please label your PR with EUI Visual Refresh -- for our own visibility and tracking.

Please also be sure to test your changes in both Amsterdam and Borealis. This is important for two reasons:

• Borealis will remain behind a feature flag for a period of time. This is particularly important for Serverless, which will continue to use Amsterdam for a period of time.
• 8.x will continue to use Amsterdam. So testing in Amsterdam before backporting changes will also help prevent introducing visual regressions in 8.x.

Regarding backporting -- 8.x will not use Borealis. Only 9.x will use Borealis. 8.x will continue to run Amsterdam. To minimize impact and risk to 8.x, if you are making the changes we outlined below, you may want to consider the backport:skip label.

One issue you may encounter specifically, is that the new tokens we provide are not currently available in 8.x, which will cause backport failures.

Requested Code Changes

We are asking all teams to make the following changes to their Kibana UI code. These are not necessarily blockers for the Borealis rollout. However, skipping ones marked as (Important) may result in bugs.

• (Important) Review usage of "success" colors for positive, semantic intent.(details).
• (Important) Review and update color palette usage. (details)
• (Important) Replace vis colors used outside of visualizations with color tokens . (details)
• (Important) Replace custom colors with semantic tokens (details)
• (Important) Replace color calculation functions with semantic tokens. (details)
• Update tokens to use the new naming scheme. (details)
• Replace euiThemeVars and eui_theme_*.json usage with semantic tokens(details)
  The following

Note:
Throughout this section, tokens are referred to by their root name (e.g. primary). In practice, the primary token exists in Sass as $euiColorPrimary and in Emotion as colors.primary, or could even be passed as prop to an EUI component like color="primary" Keep this in mind for all tokens mentioned below.

💡 Tip:
Many of these changes requires searching for certain text in the code you own. To filter a search in VS Code to just the code you (i.e., a codeowner like security-detection-engine) own, you can try running the following command and then manually pasting it into the "include" box in the VS Code search:

cat .github/CODEOWNERS | grep "security-detection-engine" | cut -d" " -f1 | sed "s@^/@@" | uniq | paste -sd "," - | pbcopy

(Important) Review usage of "success" colors for positive, semantic intent.

(Important): This is marked as important because the "success" color has changed. Things that were meant to appear as teal previously will appear a dark vibrant green. This will likely cause unexpected results.

success and successText have been updated to use a semantic green color, rather than a more subtle teal color.

We would like to reserve the usage of success and successText for semantic use cases, meaning cases that are meant to convey something positive.

We are asking teams to review their usage of the success and successText colors to ensure that they are only using it to convey positive meaning.

Some possibilities to consider:

• There were cases where success was used simply because it was teal, and teal is one of our brand colors. If that is the case, consider switching to accentSecondary, which is a new token that uses a similar teal. However, accentSecondary should be used sparingly, so consider taking it a step further and switching to something like primary.
• For buttons, you're likely bet is to switch to primary, or text (gray). accentSecondary should generally not be used on a button.
• Semantically, components like EuiHealth are never meant to convey anything other than health. Do not switch EuiHealth to use colors like accentSecondary

An example of an affirmative meaning would be this confirmation dialog. This would use the success color:

An example of a non-affirmative meaning would be the background of the "Security" badge. This would use the accentSecondary color, for the teal brand color.

Currently, This doc(Elastic Internal) is the best source for choosing a new token. Scroll down to the "Applying color tokens in product" table. This table can serve as a more comprehensive reference of what colors exist in Borealis: #199715 (comment)

The intent is to use "tokens" that match your intended use case. So rather than selecting an arbitrary color that matches what you had previously, select a "token" that matches how that color is used.

So for instance -- is the color used as a border? You can switch that to something from the borderBase or borderStrong collection -- i.e., euiTheme.colors.borderBase, euiTheme.colors.subdued, etc.

If you give us some more context on the colors you're trying to replace we can help ya pick.

(Important) Review and update color palette usage

(Important): This is marked as important because these colors are now theme aware. Not pulling them from the current them may cause bugs when switching between themes.

All usage of color palette tokens and functions should now be accessed from the EUI theme.

These were not previously part of the theme. This means that they would not change when the theme was changed, they were static. They are now part of the theme and should change when the theme is changed.

This includes any of the color tokens and functions mentioned here: https://eui.elastic.co/#/utilities/color-palettes

A simple test would be to locate your usage of these and use the provided Amsterdam/Borealis toggle to test this whether or not they change.

Vis color tokens (euiColorVis0, euiColorVis1, etc.) are now available through the EUI theme as tokens: euiTheme.colors.vis.*. Please update references to these variables to pull from the theme.

NOTE: _behindText variants of these tokens are no longer included in Borealis. For Borealis you can use the regular vis colors instead now. But for Amsterdam you should use the respective color from euiPaletteColorBlindBehindText() to ensure color parity.

The default visualization colors have been improved in Borealis to ensure the regular vis colors provide enough color contrast, which removes the need for _behindText variants.

theme.eui.euiColorVis0_behindText  -> isAmsterdam ? euiPaletteColorBlindBehindText()[0] : euiTheme.colors.vis.euiColorVis0

If you were using any of our color palette functions:

• either ensure the color palette function is called inside a React component under the EuiProvider context and is hence connected to rerender (called on rerender or connected to a state)
• otherwise if it’s used outside of the EuiProvider context you can use the new EUI_VIS_COLOR_STORE.subscribe() function to listen to changes and update usages manually

const storeId = EUI_VIS_COLOR_STORE.subscribe(
  VIS_COLOR_STORE_EVENTS.UPDATE,
  () => {
    setPalette(euiPaletteColorBlind());
  }
);

(Important) Replace vis colors used outside of visualizations with color tokens

(Important): This is marked as important because the visualization colors have changed. If you were using these colors for things outside of visualizations, you will likely now have unexpected results. For example, these are commonly used to show severity levels, if you had been doing this previously, your UI will no longer appear as expected.

Data visualization colors provided by EUI should be reserved for just that, data visualization. It is important to limit their usage so that we can iterate on these colors in the future without unintentionally affecting other UI.

https://eui.elastic.co/#/utilities/color-palettes

euiColorVis0
euiColorVis1
euiColorVis2
euiColorVis3
euiColorVis4
euiColorVis5
euiColorVis6
euiColorVis7
euiColorVis8
euiColorVis9

For example: A number of places in Kibana use euiColorVis0 to style something with a teal color. Please discontinue doing this and use accentSecondary instead. If you are using vis colors like this, please change to use another color token from EUI.

Currently, This doc(Elastic Internal) is the best source for choosing a new token. Scroll down to the "Applying color tokens in product" table. This table can serve as a more comprehensive reference of what colors exist in Borealis: #199715 (comment)

The intent is to use "tokens" that match your intended use case. So rather than selecting an arbitrary color that matches what you had previously, select a "token" that matches how that color is used.

So for instance -- is the color used as a border? You can switch that to something from the borderBase or borderStrong collection -- i.e., euiTheme.colors.borderBase, euiTheme.colors.subdued, etc.

If you give us some more context on the colors you're trying to replace we can help ya pick.

(Important) Replace custom colors with semantic tokens

(Important): This is marked as important because there is a high likelyhood that custom colors will no longer look correct in relation to the new Borealis color palette.

We are asking all teams to remove all hardcoded color values (i.e., any CSS color defined explicitly rather than using an EUI token) when adopting the color changes defined in this document. This could be a hex, rgb, hsl, etc.

To facilitate detecting instances where custom colors are used within the code an eslint rule as been prepared for this, it is currently set to provide warning to developers during development, this same rule can however be leverage to detect occurrences that declare custom colors at a go, by run lint targeting the directory of interest and setting the rule to raise it's report as an error like so;

yarn lint:es <path/to/directory/to/evaluate> --rule '@kbn/css/no_css_color: error'

This would return a familiar output of files that contain code that declares custom colors that needs to be attended to.

It's worth mentioning that instances where some component receives a prop that is then passed as a custom color will not be caught by this lint rule, the onus is on the developer to deter from such patterns.

Note that there are certain cases where it's totally acceptable to have custom color values. SVG source that you paste into a file, for instance.

NOTE: Kibana will soon include a lint rule for this: #200703

Currently, This doc(Elastic Internal) is the best source for choosing a new token. Scroll down to the "Applying color tokens in product" table. This table can serve as a more comprehensive reference of what colors exist in Borealis: #199715 (comment)

The intent is to use "tokens" that match your intended use case. So rather than selecting an arbitrary color that matches what you had previously, select a "token" that matches how that color is used.

So for instance -- is the color used as a border? You can switch that to something from the borderBase or borderStrong collection -- i.e., euiTheme.colors.borderBase, euiTheme.colors.subdued, etc.

If you give us some more context on the colors you're trying to replace we can help ya pick.

---

For some additional context on this change -- The EUI team hopes to iterate on color faster in the future. In order to do so, it is imperative teams strive to use EUI tokens for colors exclusively.

Hardcoded colors create issues when we iterate on the Kibana UI as a whole -- they break the system. By consistently using color tokens from the EUI library, we enable seamless updates and iterations on colors without requiring additional work from Kibana teams. With this approach, we can update a single token in EUI, and the color change will automatically apply across all of Kibana.

The EUI team is fundamentally changing the library by adding a comprehensive suite of Semantic Tokens. A semantic token is defined as such:

Semantic tokens in design systems are a type of design token that provide context and guidance on how to use them. They are named based on their purpose or meaning within the user interface (UI), rather than their appearance.

A practical example of this can be seen by looking at our shade colors. The naming of these tokens is based on their appearance -- dark. light, darkest, etc. We have deprecated many of these tokens in favor of tokens that are based on usage -- "border", "background", etc. This will be a key concept that allows us to iterate and evolve the Kibana UI over time -- cleanly and easily.

This same concept flows through to component customizations as well. In order for the EUI team to modernize UI at an atomic level (buttons, inputs, forms, layout, etc.), we will be asking teams to clean up CSS customizations to these elements as well. We realize that this is a big ask, but it is an important one. Simply put, if you are applying custom styles to our components, we are not able to update them without breaking UI.

(Important) Replace color calculation functions with semantic tokens

(Important): This is marked as important because there is a high likelyhood that these color calculation functions will no longer produce a result that will look correct in relation to the new Borealis color palette.

EUI provides color utility functions. Please discontinue use of these and replace them with an EUI color token. These will be deprecated as they create unpredictable results.

shade()
tint()
shadeOrTint()
tintOrShade()
transparentize()

Currently, This doc(Elastic Internal) is the best source for choosing a new token. Scroll down to the "Applying color tokens in product" table. This table can serve as a more comprehensive reference of what colors exist in Borealis: #199715 (comment)

The intent is to use "tokens" that match your intended use case. So rather than selecting an arbitrary color that matches what you had previously, select a "token" that matches how that color is used.

So for instance -- is the color used as a border? You can switch that to something from the borderBase or borderStrong collection -- i.e., euiTheme.colors.borderBase, euiTheme.colors.subdued, etc.

If you give us some more context on the colors you're trying to replace we can help ya pick.

Update tokens to use the new naming scheme

Many of our old tokens have been renamed, and we're asking folks to simply update their usage to use the new names.

Realistically, we could probably do one big find/replace PR, but if you're able to handle these while you're making other changes, that would be great. Otherwise, we'll probably do a follow up to catch everything in bulk afterwards.

# previous color token -> new color token
primaryText -> textPrimary
accentText -> textAccent
between this and textSuccess.
warningText -> textWarning
dangerText -> textDanger
text -> textParagraph
title -> textHeading
subduedText -> textSubdued
disabledText -> textDisabled
successText -> textSuccess

Replace euiThemeVars and eui_theme_*.json usage with semantic tokens

JSON tokens exported by EUI are being deprecated for usages in React components, and we need to start replacing them with semantic tokens from the EUI theme. We would appreciate it if teams could spend some time migrating away from these.

Please discontinue use of these and replace them with a token from our theme context.

ℹ If you're using the JSON tokens in a static non-react context (e.g. server-side), it is expected to keep using the JSON tokens and no update is needed.

JSON tokens are anything from:

@elastic/eui/dist/eui_theme_amsterdam_light.json
@elastic/eui/dist/eui_theme_amsterdam_dark.json
@elastic/eui/dist/eui_theme_borealis_light.json
@elastic/eui/dist/eui_theme_borealis_dark.json
import { euiThemeVars } from '@kbn/ui-theme'

For example:
https://github.com/elastic/kibana/blob/main/packages/kbn-visualization-ui-components/components/dimension_buttons/palette_indicator.tsx#L32

Before:

import { EuiIcon, EuiCode, EuiText, useEuiTheme } from '@elastic/eui';
...
height: ${euiThemeVars.euiSizeXS} / 2;

After:

import { useEuiTheme } from '@elastic/eui'
....
const { euiTheme } = useEuiTheme();
...
height: ${euiTheme.size.xs} / 2;

[!IMPORTANT]
See the tables in this comment when mapping from old tokens to new. (e.g. from euiSizeXS to size.xs)

A note for folks using the styled syntax

If you are replacing usage of euiThemeVars within the styled syntax from @emotion/styled, it may look something like this:

Before:

const LogStreamContainer = styled.div`
  display: flex;
  background-color: ${euiThemeVars.euiColorEmptyShade};
`;

After:

const LogStreamContainer = styled.div`
  display: flex;
  background-color: ${props => props.theme.euiTheme.colors.emptyShade};
`;

If you see type errors related to props.theme, you may have to set up an emotion.d.ts

Here's some guidance related to that, plucked from our Emotion FAQ:

Please note, that if you encounter type errors with the theme parameter inside of the css function, you'll need to make your Plugin is set up to use Kibana's emotion.d.ts file.

To do this, add in the aforementioned emotion.d.ts with it's path relative to location of the typings directory as the value of the include property for the tsconfig.json file that exists within your plugin.
file for your Kibana plugin for the parameter in css functions to be properly typed as EUI's theme. See the osquery plugin for an example of their tsconfig setup.

[!IMPORTANT]
Please use this table as point of reference when migrating import { euiThemeVars } from '@kbn/ui-theme' to the useEuiTheme() theme hook.

If a token might be missing or unfitting for your use case, please reach out to the EUI team in the #eui slack channel.
We'll update this list as needed.

[JasonStoltz]

@elastic/kibana-core
@elastic/kibana-esql
@elastic/appex-ai-infra
@elastic/logstash
@elastic/security-defend-workflows
@elastic/security-threat-hunting-investigations
@elastic/security-detection-engine
@elastic/security-generative-ai
@elastic/security-threat-hunting-explore
@elastic/security-detection-rule-management
@elastic/security-solution

Hi folks 👋 . Could you all please add a contact/owner from your team to the table above? It's helpful for coordinate and serves as an acknowledgement of this work from your team.

Let me know if you have any questions.