wiki context for theming

wiki/consuming.md

@@ -48,25 +48,44 @@ Test utilities are published from the `lib/test` directory.
 import { findTestSubject } from '@elastic/eui/lib/test';
 ```
 
-### Reusing the variables in JavaScript
+### Theming
 
-The Sass variables are also made available for consumption as json files. This enables reuse of values in css-in-js systems like [Emotion](https://emotion.sh/). As the following example shows, it can also make the downstream components theme-aware without much extra effort:
+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). 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. 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 therefor recommend not relying on the JSON dist of these tokens, and convert your applications to utilize EUI's Emotion powered [Theme Proiver](https://elastic.github.io/eui/#/theming/theme-provider) and its related tokens instead. The following are provided as basic examples to show what that conversion might look like if you were using the older, legacy systems.
+
+#### A not-recommended, legacy method to consume theming variables from Sass
 
 ```jsx
-import React from 'react';
-import { css } from '@emotion/react';
 import * as euiVars from '@elastic/eui/dist/eui_theme_light.json';
 
-const styles = css`
-  color: ${euiVars.euiColorPrimary};
-  border: ${euiVars.euiBorderThin};
-`;
+const styles = {
+  color: euiVars.euiColorPrimary,
+  border: euiVars.euiBorderThin
+};
 
 export default () => (
-  <div css={styles} />
+  <div style={styles} />
 )
 ```
 
+#### A recommended method to consume theming variables using Emotion
+
+```jsx
+import { useEuiTheme } from '@elastic/eui';
+import { css } from '@emotion/react';
+
+
+export default () => {
+  const { euiTheme } = useEuiTheme();
+  const styles = css`
+    color: ${euiTheme.colors.primary};
+    border: ${euiTheme.border.thin};
+  `;
+  return (
+  <div css={styles} />
+  );
+};
+```
+
 ### "Module build failed" or "Module parse failed: Unexpected token" error
 
 If you get an error when importing a React component, you might need to configure Webpack's `resolve.mainFields` to `['webpack', 'browser', 'main']` to import the components from `lib` instead of `src`. See the [Webpack docs](https://webpack.js.org/configuration/resolve/#resolve-mainfields) for more info.