From 3902751fdb90e6aadbe22bb9f01eac02cd799851 Mon Sep 17 00:00:00 2001 From: Cee Chen Date: Wed, 18 Sep 2024 15:23:33 -0700 Subject: [PATCH 1/9] Update getting started docs to remove references to `.css` files and migration + remove `colorMode` docs in anticipation of automatic system color mode logic, and link to EuiProvider props instead --- .../guidelines/getting_started/_app_setup.tsx | 71 +++++++------------ .../docs/01_guidelines/getting_started.mdx | 16 +---- wiki/consuming-eui/README.md | 5 +- 3 files changed, 31 insertions(+), 61 deletions(-) diff --git a/packages/eui/src-docs/src/views/guidelines/getting_started/_app_setup.tsx b/packages/eui/src-docs/src/views/guidelines/getting_started/_app_setup.tsx index cce01cad10e..9ad5022204e 100644 --- a/packages/eui/src-docs/src/views/guidelines/getting_started/_app_setup.tsx +++ b/packages/eui/src-docs/src/views/guidelines/getting_started/_app_setup.tsx @@ -1,71 +1,52 @@ -import React, { FunctionComponent } from 'react'; +import React from 'react'; import { Link } from 'react-router-dom'; import { EuiCodeBlock, - useEuiTheme, EuiCode, EuiSpacer, EuiText, - EuiCallOut, + EuiLink, } from '../../../../../src'; -type AppSetup = {}; - -export const AppSetup: FunctionComponent = ({}) => { - const { colorMode } = useEuiTheme(); +export const AppSetup = () => { + return ( + <> + +

+ EUI uses CSS-in-JS (specifically{' '} + + Emotion + + ) for its styles and theming. As such, we require an{' '} + {''} wrapper around your application + in order for various theme-related UI & UX (such as dark/light mode + switching) to work as expected. +

+ - const appSetup = ( - - {`import React from 'react'; -import '@elastic/eui/dist/eui_theme_${colorMode.toLowerCase()}.css'; + + + {`import React from 'react'; import { EuiProvider, EuiText } from '@elastic/eui'; const MyApp = () => ( - +

Hello World!

 ); export default MyApp;`} - - ); - - return ( - <> - -

- While EUI is in the process of converting from a Sass based theme to - CSS-in-JS via Emotion. We require that both the{' '} - - EuiProvider - {' '} - and the compiled CSS (or raw Sass) files be imported - during this transition. -

- - - - - -

- EUI provides a general context provider to handle global aspects like - light and dark theme. You can import these default themes through - their respective compiled CSS files. Use the{' '} - .min.css file extension for the minified version. -

- - - - {appSetup} +

- For the dark theme, you can swap the words light{' '} - for dark.
For more configuration options of the provider, see the{' '} - EuiProvider documentation. + + EuiProvider documentation + + .

diff --git a/packages/website/docs/01_guidelines/getting_started.mdx b/packages/website/docs/01_guidelines/getting_started.mdx index 75caebef0d6..e40b4f48a3c 100644 --- a/packages/website/docs/01_guidelines/getting_started.mdx +++ b/packages/website/docs/01_guidelines/getting_started.mdx @@ -44,24 +44,15 @@ You can read more about other ways to consume EUI in our wiki. ## Setting up your application -:::warning -While EUI is in the process of converting from a Sass based theme to CSS-in-JS via Emotion. We require that both -the [EuiProvider](https://eui.elastic.co/#/utilities/provider) **and** the compiled CSS (or raw Sass) files be imported -during this transition. -::: - - -EUI provides a general context provider to handle global aspects like light and dark theme. You can import these -default themes through their respective compiled CSS files. Use the `.min.css` file extension for the minified version. +EUI uses CSS-in-JS (specifically [Emotion](https://emotion.sh)) for its styles and theming. As such, we require an `` wrapper around your application in order for various theme-related UI & UX (such as dark/light mode switching) to work as expected. ```jsx import React from 'react'; -import '@elastic/eui/dist/eui_theme_light.css'; import { EuiProvider, EuiText } from '@elastic/eui'; const MyApp = () => ( - +

Hello World!

 ); @@ -69,9 +60,8 @@ const MyApp = () => ( export default MyApp; ``` -For the dark theme, you can swap the words `light` for `dark`. For more configuration options of the provider, see the -[EuiProvider documentation](https://eui.elastic.co/#/utilities/provider). +[**EuiProvider** documentation](https://eui.elastic.co/#/utilities/provider). ## Styling your application diff --git a/wiki/consuming-eui/README.md b/wiki/consuming-eui/README.md index 9e0e275a97d..6bc0430d971 100644 --- a/wiki/consuming-eui/README.md +++ b/wiki/consuming-eui/README.md @@ -51,16 +51,15 @@ import { findByTestSubject, render, screen } from '@elastic/eui/lib/test/rtl'; / ### Theming -As of April 2022 EUI is in the process of [migrating to Emotion JS for the CSS and theming layer](https://github.com/elastic/eui/issues/3912). While EUI is in the process of this conversion, we require that both the EuiProvider and the compiled CSS (or raw Sass) files be imported during this transition. +EUI uses CSS-in-JS (specifically [Emotion](https://emotion.sh)) for its styles and theming. As such, we require an `` wrapper around your application in order for various theme-related UI & UX (such as dark/light mode switching) to work as expected. ```jsx import React from 'react'; -import '@elastic/eui/dist/eui_theme_light.css'; import { EuiProvider, EuiText } from '@elastic/eui'; const MyApp = () => ( - +

Hello World!

 ); From de60361bc7f775707b546271c84ad317d9d5fb35 Mon Sep 17 00:00:00 2001 From: Cee Chen Date: Wed, 18 Sep 2024 15:56:14 -0700 Subject: [PATCH 2/9] [Getting started] Update consuming theme tokens docs --- .../guidelines/getting_started/_tokens.tsx | 101 ------------------ .../getting_started/getting_started.js | 34 ++++-- .../src-docs/src/views/theme/consuming.tsx | 4 +- .../docs/01_guidelines/getting_started.mdx | 82 ++++++-------- wiki/consuming-eui/README.md | 21 +--- 5 files changed, 60 insertions(+), 182 deletions(-) delete mode 100644 packages/eui/src-docs/src/views/guidelines/getting_started/_tokens.tsx diff --git a/packages/eui/src-docs/src/views/guidelines/getting_started/_tokens.tsx b/packages/eui/src-docs/src/views/guidelines/getting_started/_tokens.tsx deleted file mode 100644 index 1731c112295..00000000000 --- a/packages/eui/src-docs/src/views/guidelines/getting_started/_tokens.tsx +++ /dev/null @@ -1,101 +0,0 @@ -import React, { FunctionComponent, useContext } from 'react'; -import { Link } from 'react-router-dom'; - -import { - EuiCodeBlock, - EuiSplitPanel, - EuiFlexGroup, - EuiFlexItem, - EuiText, - EuiHorizontalRule, - EuiCode, -} from '../../../../../src'; - -import { GuideSectionExampleCode } from '../../../components/guide_section/guide_section_parts/guide_section_code'; -import { LanguageSelector, ThemeContext } from '../../../components/with_theme'; -const consumingSource = require('!!raw-loader!../../theme/consuming'); - -const ImportOutsideExample = () => { - const themeContext = useContext(ThemeContext); - let files; - switch (themeContext.theme) { - case 'dark': - files = `@import '@elastic/eui/src/themes/amsterdam/colors_dark'; -@import '@elastic/eui/src/themes/amsterdam/globals';`; - break; - default: - files = `@import '@elastic/eui/src/themes/amsterdam/colors_light'; -@import '@elastic/eui/src/themes/amsterdam/globals';`; - break; - } - - return ( - - {`// index.scss -${files} - -@import 'your/custom/styles';`} - - ); -}; - -export const Tokens: FunctionComponent = () => { - const themeContext = useContext(ThemeContext); - const currentLanguage = themeContext.themeLanguage; - const showSass = currentLanguage.includes('sass'); - - return ( - - - - - -

- - Keep an eye out for this language selector that will allow you - to view the syntax for either the Sass or CSS-in-JS (Emotion) - theming mechanisms. - -

- - - - - - - - - {showSass ? ( - <> - - -

This will require style, css, postcss, and sass loaders.

- - - - - - - ) : ( - <> - - -

- As long as you have wrapped your application with{' '} - - EuiProvider - - , you have access to the JS theme tokens via{' '} - useEuiTheme() and Emotion's{' '} - css prop. -

- - - - - - - )} - - ); -}; diff --git a/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js b/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js index 88c48d5e53f..1c51cf5e126 100644 --- a/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js +++ b/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js @@ -1,12 +1,19 @@ import React from 'react'; import { Link } from 'react-router-dom'; -import { EuiCodeBlock, EuiCode, EuiText, EuiSpacer } from '../../../../../src'; +import { + EuiCodeBlock, + EuiCode, + EuiText, + EuiSpacer, + EuiPanel, +} from '../../../../../src'; import { AppSetup } from './_app_setup'; -import { Tokens } from './_tokens'; import { Customizing } from './_customizing'; import { ThemeNotice } from '../../../views/theme/_components/_theme_notice.tsx'; +import { GuideSectionExampleCode } from '../../../components/guide_section/guide_section_parts/guide_section_code'; +const consumingSource = require('!!raw-loader!../../theme/consuming'); import { euiProviderComponentDefaultsSnippet } from '../../provider/provider_component_defaults'; export const GettingStarted = { @@ -72,18 +79,23 @@ export const GettingStarted = { <>

- To build your custom components using EUI theme variables, - functions, and mixins, you will need to consume them through one - of the Sass,{' '} - Emotion, or{' '} - - JSON import - {' '} - methods. + You can build custom components using EUI's theme tokens, consumed + via useEuiTheme(). The below example uses + Emotion's css prop, but any CSS-in-JS library + should be able to interpolate the JS variables. +

+

+ For more ways to consume EUI's theme, see the{' '} + + EuiThemeProvider documentation + + .

- + + + diff --git a/packages/eui/src-docs/src/views/theme/consuming.tsx b/packages/eui/src-docs/src/views/theme/consuming.tsx index 44bb1cd7971..82e3e440ab3 100644 --- a/packages/eui/src-docs/src/views/theme/consuming.tsx +++ b/packages/eui/src-docs/src/views/theme/consuming.tsx @@ -22,8 +22,8 @@ export default () => { `} > The padding of this box is created using calc(){' '} - because EUI's theme sizes are string pixel values that are - calculated off the theme's base + because EUI's theme sizes are string pixel values that are calculated + off the theme's base

); diff --git a/packages/website/docs/01_guidelines/getting_started.mdx b/packages/website/docs/01_guidelines/getting_started.mdx index e40b4f48a3c..231f8c2fa76 100644 --- a/packages/website/docs/01_guidelines/getting_started.mdx +++ b/packages/website/docs/01_guidelines/getting_started.mdx @@ -65,56 +65,42 @@ For more configuration options of the provider, see the ## Styling your application -To build your custom components using EUI theme variables, functions, and mixins, you will need to consume them -through one of the [Sass](https://eui.elastic.co/#/theming/sass), -[Emotion](https://eui.elastic.co/#/theming/theme-provider), -or [JSON import](https://github.com/elastic/eui/blob/main/wiki/consuming-eui/README.md#a-not-recommended-legacy-method-to-consume-theming-variables-from-sass) methods. +You can build custom components using EUI's theme tokens, consumed via `useEuiTheme()`. The below example uses Emotion's `css` prop, but any CSS-in-JS library should be able to interpolate the JS variables. - - - ```scss title="This will require style, css, postcss, and sass loaders." - // index.scss - @import '@elastic/eui/src/themes/amsterdam/colors_light'; - @import '@elastic/eui/src/themes/amsterdam/globals'; - - @import 'your/custom/styles'; - ``` - - - ```jsx title="As long as you have wrapped your application with EuiProvider, you have access to the JS theme tokens via useEuiTheme() and Emotion's css prop." - import React from 'react'; - import { EuiIcon, EuiCode, EuiText, useEuiTheme } from '@elastic/eui'; - import { css } from '@emotion/react'; +For more ways to consume EUI's theme, see the [**EuiThemeProvider** documentation](https://eui.elastic.co/#/theming/theme-provider#consuming-with-the-react-hook). - export default () => { - const { euiTheme } = useEuiTheme(); - return ( - -

- {' '} - This primary color will adjust based on the light or dark theme value -

- -

- The padding of this box is created using calc(){' '} - because EUI's theme sizes are string pixel values that are - calculated off the theme's base -

- - ); - }; - ``` - - +```jsx +import React from 'react'; +import { EuiIcon, EuiCode, EuiText, useEuiTheme } from '@elastic/eui'; +import { css } from '@emotion/react'; + +export default () => { + const { euiTheme } = useEuiTheme(); + return ( + +

+ {' '} + This primary color will adjust based on the light or dark theme value +

+ +

+ The padding of this box is created using calc(){' '} + because EUI's theme sizes are string pixel values that are + calculated off the theme's base +

+ + ); +}; +``` ### Customizing the style tokens diff --git a/wiki/consuming-eui/README.md b/wiki/consuming-eui/README.md index 6bc0430d971..a9322741e24 100644 --- a/wiki/consuming-eui/README.md +++ b/wiki/consuming-eui/README.md @@ -67,7 +67,7 @@ const MyApp = () => ( export default MyApp; ``` -#### The recommended method to consume theming variables using Emotion +#### Consuming theme tokens Using EUI's theme layer with Emotion is [documented in our docs](https://elastic.github.io/eui/#/theming/theme-provider) and should cover the majority of your theming needs. @@ -87,25 +87,6 @@ export default () => { ); }; ``` -#### A not-recommended, legacy method to consume theming variables from Sass - -Until the conversion is complete, the components you consume may still contain soon-to-be-removed Sass styling. EUI's distribution also provides both a light and dark JSON token file that exposes these Sass variables (through an automatic process derived from the Sass) to make tokens from the individual Sass components available to consume if you need them. As components continue to convert to Emotion, these Sass-to-JS tokens in these files will degrade, eventually disappearing altogether. We therefore recommend not relying on the JSON dist of these tokens, and instead using the above recommended Emotion approach. - -The following is provided as an example of the soon-to-be-deprecated Sass theme variables, to aid consumers in converting legacy usage. - -```jsx -import * as euiVars from '@elastic/eui/dist/eui_theme_light.json'; - -const styles = { - color: euiVars.euiColorPrimary, - border: euiVars.euiBorderThin - padding: euiVars.euiPanelPaddingModifiers.paddingSmall -}; - -export default () => ( -
-) -``` ### "Module build failed" or "Module parse failed: Unexpected token" error From 61b779162f0231d716c173882ae699e28fb0ea40 Mon Sep 17 00:00:00 2001 From: Cee Chen Date: Wed, 18 Sep 2024 18:10:30 -0700 Subject: [PATCH 3/9] [Getting started] Update style token customization docs + move bottom bullet point to a location where it'll actually be read, and wrap it in a warning callout --- .../getting_started/getting_started.js | 42 ++++---- .../docs/01_guidelines/getting_started.mdx | 102 +++++++----------- 2 files changed, 61 insertions(+), 83 deletions(-) diff --git a/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js b/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js index 1c51cf5e126..38ee0673506 100644 --- a/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js +++ b/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js @@ -7,13 +7,13 @@ import { EuiText, EuiSpacer, EuiPanel, + EuiCallOut, } from '../../../../../src'; import { AppSetup } from './_app_setup'; -import { Customizing } from './_customizing'; -import { ThemeNotice } from '../../../views/theme/_components/_theme_notice.tsx'; import { GuideSectionExampleCode } from '../../../components/guide_section/guide_section_parts/guide_section_code'; const consumingSource = require('!!raw-loader!../../theme/consuming'); +const overrideSimpleSource = require('!!raw-loader!../../theme/override_simple'); import { euiProviderComponentDefaultsSnippet } from '../../provider/provider_component_defaults'; export const GettingStarted = { @@ -102,29 +102,35 @@ export const GettingStarted = {

Customizing the style tokens

EUI can be slightly customized to fit your branding needs by - altering the base tokens like color and typography. Simply declare - your token overrides before importing the whole EUI theme. This - will re-compile all of the EUI components with your colors. + altering the base tokens like color and typography. You can pass a + full or partial list of override tokens to the{' '} + EuiProvider's modify prop.

+ + By nature, EUI is very rigid. You shouldn't need much to make + drastic changes to color. Most themes are less then a dozen + variable overwrites in total. + +

- For a full list of global tokens visit{' '} - Customizing theme. + For a full list of global tokens, visit{' '} + Customizing themes. + For more examples of the modify prop, see the{' '} + + EuiThemeProvider docs + + .

- - - + + + -

Do not use in conjunction with the compiled CSS.

-

If you provide both, it will duplicate the imported styles.

-

Touch the least amount of variables possible.

-

- By nature EUI is very rigid. You shouldn't need much to make - drastic changes to color. Most themes are less then a dozen - variable overwrites in total. -

Do not overwrite individual component variables or{' '} .eui class names. diff --git a/packages/website/docs/01_guidelines/getting_started.mdx b/packages/website/docs/01_guidelines/getting_started.mdx index 231f8c2fa76..5b75c9f77f7 100644 --- a/packages/website/docs/01_guidelines/getting_started.mdx +++ b/packages/website/docs/01_guidelines/getting_started.mdx @@ -104,79 +104,51 @@ export default () => { ### Customizing the style tokens -EUI can be slightly customized to fit your branding needs by altering the base tokens like color and typography. -Simply declare your token overrides before importing the whole EUI theme. This will re-compile -all of the EUI components with your colors. +EUI can be slightly customized to fit your branding needs by altering the base tokens like color and typography. You can pass a full or partial list of override tokens to the **EuiProvider**'s `modify` prop. -For a full list of global tokens visit Customizing theme. - -:::warning Partial component support -EUI is transitioning to a CSS-in-JS solution for theming and requires consuming/customizing global variables -in **both the Sass and CSS-in-JS** methods. To track this effort, -subscribe to the [Meta ticket](https://github.com/elastic/eui/issues/3912). +:::warning Touch the least amount of variables possible +By nature, EUI is very rigid. You shouldn't need much to make drastic changes to color. Most themes are less then a dozen variable overwrites in total. ::: - - - ```scss title="This will require style, css, postcss, and sass loaders and a full re-compile of all EUI component styles." - $euiColorPrimary: #7B61FF; - - // The following rebuilds the entire EUI component styles - @import '@elastic/eui/src/themes/amsterdam/theme_light'; +For a full list of global tokens visit [Customizing themes](https://eui.elastic.co/#/theming/customizing-themes). For more examples of the modify prop, see the [**EuiThemeProvider** docs](https://eui.elastic.co/#/theming/theme-provider#simple-instance-overrides). - @import 'your/custom/styles'; - ``` - - - ```jsx title="You can pass along a full or partial list of global overrides to the EuiProvider which will update the EUI components that are currently using the Emotion method of theming." - import React, { FunctionComponent, ReactNode } from 'react'; - import { EuiCode, EuiText, EuiThemeProvider, useEuiTheme } from '@elastic/eui'; - - const Box: FunctionComponent<{ children: ReactNode }> = ({ children }) => { - const { euiTheme } = useEuiTheme(); - - return ( - -

{children}

- - ); - }; - - export default () => { - const overrides = { - colors: { - LIGHT: { lightShade: '#d3e6df' }, - DARK: { lightShade: '#394c4b' }, - }, - }; - - return ( -
- - - The background of this box is using the locally overridden value of{' '} - euiTheme.colors.lightShade - - -
- ); - }; - ``` - - +```jsx +import React, { FunctionComponent, ReactNode } from 'react'; +import { EuiCode, EuiText, EuiThemeProvider, useEuiTheme } from '@elastic/eui'; -#### Do not use in conjunction with the compiled CSS. +const Box: FunctionComponent<{ children: ReactNode }> = ({ children }) => { + const { euiTheme } = useEuiTheme(); -If you provide both, it will duplicate the imported styles. + return ( + +

{children}

+ + ); +}; -#### Touch the least amount of variables possible. +export default () => { + const overrides = { + colors: { + LIGHT: { lightShade: '#d3e6df' }, + DARK: { lightShade: '#394c4b' }, + }, + }; -By nature EUI is very rigid. You shouldn't need much to make drastic changes to color. Most themes are less then a dozen variable overwrites in total. + return ( + + + The background of this box is using the locally overridden value of{' '} + euiTheme.colors.lightShade + + + ); +}; +``` #### Do not overwrite individual component variables or .eui class names. From dec612629f2f0d474d39ff1b1736ceee35b52450 Mon Sep 17 00:00:00 2001 From: Cee Chen Date: Wed, 18 Sep 2024 18:26:24 -0700 Subject: [PATCH 4/9] [Getting started] Move and rewrite classes example - should be under styling section, where it's actually useful - add link to cache config, since that affects CSS specificity - modify example to be usable in codesandbox --- .../getting_started/getting_started.js | 103 +++++++++++------- .../docs/01_guidelines/getting_started.mdx | 49 +++++---- 2 files changed, 90 insertions(+), 62 deletions(-) diff --git a/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js b/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js index 38ee0673506..f30b0bb294a 100644 --- a/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js +++ b/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js @@ -8,6 +8,7 @@ import { EuiSpacer, EuiPanel, EuiCallOut, + EuiLink, } from '../../../../../src'; import { AppSetup } from './_app_setup'; @@ -98,6 +99,67 @@ export const GettingStarted = { + +

Customizing with classes

+

+ For consumers using vanilla or preprocessed CSS, all components + allow you to pass a custom className prop, + which will be appended onto the component. +

+ + Avoid overwriting .eui class names + + } + > + EUI's class names are not a guaranteed API and are prone to + change, which will risk breaking your theme. Target your custom + classNames instead. + + +

+ While EUI's styles are generally low in{' '} + + specificity + {' '} + due to our usage of CSS-in-JS, you may need to ensure that your + CSS is defined after ours in your {''}.{' '} + See{' '} + + EuiProvider's cache customization + {' '} + for more style injection options. +

+ + + + ( + <> + + Hello world! + +);`, + }} + /> + + +

Customizing the style tokens

@@ -129,19 +191,6 @@ export const GettingStarted = { - - -

- Do not overwrite individual component variables or{' '} - .eui class names. -

-

- Although this may be possible, components are much more prone to - change and you'll risk breaking your theme. All EUI - components accept custom a className which you - can use to append your custom styles. -

- ), }, @@ -259,34 +308,6 @@ import { findByTestSubject, render, screen } from '@elastic/eui/lib/test/rtl'; / ), }, - { - title: 'Customizing with classes', - wrapText: false, - text: ( - <> - -

- We do not recommend customizing EUI components by applying styles - directly to EUI classes, eg. .euiButton. All - components allow you to pass a custom className{' '} - prop directly to the component which will then append this to the - class list. Utilizing the cascade feature of CSS, you can then - customize by overriding styles so long as your styles are imported{' '} - after the EUI import. -

- - - - {''} - - -

Renders as:

- - {'