[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.

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

Summer 2021:

• Build out the theme layer ([CSS-in-JS] Global theme #4643)
  • Convert all the SASS invisibles (variables, functions, etc) to JS
  • Usage documentation
• Enable Emotion in Kibana (Enable CSS-in-JS styling with emotion kibana#98157)
• Initial release of context layer and global theme ([FEATURE] CSS-in-JS via emotion, initial release #4511)
• Add more documentation ([Docs] EuiThemeProvider global theme switching #5072)
• Add global theme context provider in Kibana (Create a theming React context provider integration for applications 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.

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

2022-2023

Beta Give feedback

1. [Meta][CSS-in-JS] Component conversions #5685
   24 of 33
   emotion meta task +3
   

Beyond component conversions:

• [Emotion] Figure out what exports we do and don't want to make public #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

• [EuiLoadingX] Add speed prop (feature request) #4116
• [EuiFlexGrid] Add justifyContent and alignItems like EuiFlexGroup #4878
• Bottom bar too subtle to get properly noticed #4158
• [Discuss] Cross-browser focus states for overflow containers #3385
• [EuiFlexGrid] Allow number of columns based on viewport size #2609
• [EuiFlexGroup] Responsive mode doesn't respect gutterSize #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 #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]

@lightwave I've converted your questions to a discussion to keep this Meta issue centered around tasks. #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 #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.