[Meta][CSS-in-JS] Switching to `emotion`

[cchaos]

This is a meta ticket to discuss the rollout plan of the CSS in JS solution (Emotion). It is for documenting the expected upgrade process both within EUI and by consuming applications, and being transparent about our timeline.

(Tentative) Timeline & tasks

Spring 2021:

Get the contexts built out and (partially) used in the EUI components and docs, as well as thoroughly tested in downstream applications like Kibana and Cloud. Figure out all the dependencies, hooks and possible state management that go with it.

• [x] EuiContext: Overall context layer that would encompass theming, layering, etc… (#4440)
• [x] EuiThemeContext: Theme specific layer with at least these properties: (#4440)
  • [x] themeName
  • [x] colorMode: ‘light’ | ‘dark’
  • [x] { colors: {primar, secondary, etc} }
• [x] <ColorMode> aka: <DarkMode>{component}</DarkMode> for switching of themes at the component level (#4440)

Summer 2021:

• [x] Build out the theme layer (#4643)
  • [x] Convert all the SASS invisibles (variables, functions, etc) to JS
  • [x] Usage documentation
• [x] Enable Emotion in Kibana (https://github.com/elastic/kibana/pull/98157)
• [x] Initial release of context layer and global theme (#4511)
• [x] Add more documentation (#5072)
• [x] Add global theme context provider in Kibana (elastic/kibana#108972)

Fall 2021:

Start shifting component styles from SASS to JS. This part will probably take a full year and probably means phasing out the old 'legacy' theme, making Amsterdam default.

• [x] Add global reset file via Emotion (#5122)
• [x] Deprecate current theme for Amsterdam (#5222)
• [x] EUI breaking/major release with peerDep on @emotion/react (#5121) from this point forward using only the generated CSS is not supported, EUI must be used through React

### 2022-2023
- [ ] #5685

Beyond component conversions:

• [ ] https://github.com/elastic/eui/issues/7025
• [ ] Convert Kibana's usage of styled-components to Emotion
• [ ] Deprecate using EUI's SCSS mixins/variables
• [ ] Deprecate using EUI's classnames
• [ ] Remove class names (after a lengthy deprecation period)
• [ ] Remove use of ghost and ink in favor of EuiThemeProvider + colorMode (see discussion)
• [ ] Elastic Charts theme as an EuiTheme

[cchaos]

Requests

• #4116
• https://github.com/elastic/eui/issues/4878
• https://github.com/elastic/eui/issues/4158
• https://github.com/elastic/eui/issues/3385
• https://github.com/elastic/eui/issues/2609
• https://github.com/elastic/eui/issues/4140

[cchaos]

Upgrade process

Questions

• [ ] Do we want to allow EUI styling apart from css prop (e.g. in Kibana)
• [ ] EUI does not always apply className to the outermost element, does a css prop on an object prop apply as expected
• [ ] What do we do with the handful of createElement usages, replace with emotion’s createElement equivalent?
• [ ] When css is applied on a custom component which element gets the style? What if there's a fragment at the top level?

EUI

See https://github.com/elastic/eui/issues/5685

Charts theme

Can we create a EuiThemeCharts similar to EuiThemeDefault that can be used primarily as a React hook to pass the theme down to an elastic-charts implementation? And it know the light/dark color mode automatically.

Consuming apps

• TBD (babel, etc)
• Vanilla JS support (Kibana plugins; basic, immutable theme variables)
• SSR support (verify + link to emotion's docs)
• Update Gatsby and Next starters

[lightwave]

Will EUI theme be compatible with the theme specification used in theme-ui and styled system?

[cchaos]

👋 Hi @lightwave, we aren't explicitly building our themes to be compatible, but from the looks at that documentation, it's just a way to store your own theme tokens to then provide it to the UI library of your choice. Our tokens will be specifically designed to how we use them in our components. We're continuing to build out the docs but you can start taking a look at what our JSON theming object looks like here: https://elastic.github.io/eui/#/theming/global-values

[lightwave]

👋 Hi @lightwave, we aren't explicitly building our themes to be compatible, but from the looks at that documentation, it's just a way to store your own theme tokens to then provide it to the UI library of your choice. Our tokens will be specifically designed to how we use them in our components. We're continuing to build out the docs but you can start taking a look at what our JSON theming object looks like here: https://elastic.github.io/eui/#/theming/global-values

You're correct that theme-ui uses its own token, but there are name conflict since both eui and theme-ui uses the underlying emotion theme provider. theme-ui expects the breakpoints attribute to be an array while eui expects the breakpoints in the theme object to be an object. After eui inject its theme object into emotion, it broke the processing in theme-ui where it expects it to be an array.

[cchaos]

@lightwave I've converted your questions to a discussion to keep this Meta issue centered around tasks. https://github.com/elastic/eui/discussions/5351

[jlalmes]

Keen to help out with the implementation and rollout for this. Our use case:

• We need to easily adjust the "primary", "primaryText" colors at runtime using the EuiThemeProvider
• We would like to use individual components from this library for lightweight applications without needing to include the main @elastic/eui/dist/eui_theme_amsterdam_light.css css file in our bundle.

It seems that we're blocked by this PR https://github.com/elastic/eui/pull/4575 which will outline the game plan for moving forward & converting all other components from sass to emotion. What is the current status of this - and how can we help move this PR closer to alpha/beta/production?

[cchaos]

👋 Hey @jlalmes, that's exciting and we'd absolutely love the help during the conversion. You are correct about #4575 being the next step in the process. We like to put a lot of thinking up front in the endeavors so it's less likely that we look back and wish we had done it differently 😄 . We've tentatively given ourselves the typically slow month of December to figure that part out and have a final plan hopefully by the beginning of 2022. We totally understand your pain points and we hope this will solve most of them. Mostly we've been having to juggle prioritizing this work in tandem with other consumer priorities.