Update the design token README

packages/design-tokens/README.md

@@ -2,7 +2,7 @@
 
 # @sumup/design-tokens
 
-Visual primitives such as typography, color, and spacing that are shared across platforms.
+Visual primitives such as typography, color, and spacing for [Circuit UI Web](https://github.com/sumup-oss/circuit-ui/tree/main/packages/circuit-ui).
 
 [![Stars](https://img.shields.io/github/stars/sumup-oss/circuit-ui?style=social)](https://github.com/sumup-oss/circuit-ui/) [![Version](https://img.shields.io/npm/v/@sumup/design-tokens)](https://www.npmjs.com/package/@sumup/design-tokens) [![Coverage](https://img.shields.io/codecov/c/github/sumup-oss/circuit-ui)](https://codecov.io/gh/sumup-oss/circuit-ui) [![License](https://img.shields.io/badge/license--lightgrey.svg)](https://github.com/sumup-oss/circuit-ui/tree/main/packages/design-tokens/LICENSE) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.1%20adopted-ff69b4.svg)](https://github.com/sumup-oss/circuit-ui/tree/main/CODE_OF_CONDUCT.md)
 
@@ -22,9 +22,30 @@ yarn add @sumup/design-tokens
 
 ## Usage
 
-The package currently exports a single `light` theme that is meant to be used with SumUp's React component library, [Circuit UI](https://github.com/sumup-oss/circuit-ui/tree/main/packages/circuit-ui). Pass the theme to Emotion's [`ThemeProvider`](https://emotion.sh/docs/theming):
+The [legacy JavaScript theme](#legacy-javascript-theme) for Emotion.js is being replaced by [CSS custom properties](#css-custom-properties) (aka CSS variables) to improve performance and compatibility with other frameworks. We recommend installing the [`@sumup/eslint-plugin-circuit-ui`](https://circuit.sumup.com/?path=/docs/packages-eslint-plugin-circuit-ui--docs) ESLint plugin and turning on the `prefer-custom-properties` and `no-invalid-custom-properties` rules to help with the migration.
 
-```jsx
+Refer to the [theme documentation](https://circuit.sumup.com/?path=/docs/features-theme--docs) for a full reference of the available tokens.
+
+### CSS custom properties
+
+The `@sumup/design-tokens/light.css` CSS file contains all CSS custom properties that are used by Circuit UI. Import it in a globally used file like Next.js' `_app.tsx` file:
+
+```tsx
+// _app.tsx
+import '@sumup/design-tokens/light.css';
+
+function App({ Component, pageProps }) {
+  return <Component {...pageProps} />;
+}
+```
+
+The application code must be processed by a bundler that can handle CSS files. [Next.js](https://nextjs.org/docs/pages/building-your-application/styling), [Create React App](https://create-react-app.dev/docs/adding-a-stylesheet), [Vite](https://vitejs.dev/guide/features.html#css-modules), [Parcel](https://parceljs.org/languages/css/#css-modules), and others support importing CSS files out of the box.
+
+### Legacy JavaScript theme
+
+The `light` theme is meant to be used with Emotion.js' [`ThemeProvider`](https://emotion.sh/docs/theming):
+
+```tsx
 import { light } from '@sumup/design-tokens';
 import { ThemeProvider } from '@emotion/react';
 import styled from '@emotion/styled';
@@ -33,20 +54,22 @@ const Bold = styled.strong`
   font-weight: ${(p) => p.theme.fontWeight.bold};
 `;
 
-const App = () => (
-  <ThemeProvider theme={light}>
-    <Bold>This styled component has access to the theme.</Bold>
-  </ThemeProvider>
-);
+function App() {
+  return (
+    <ThemeProvider theme={light}>
+      <Bold>This styled component has access to the theme.</Bold>
+    </ThemeProvider>
+  );
+}
 ```
 
 The theme is a plain JavaScript object, so you can use it in other ways, too.
 
-### With prop types
+#### With prop types
 
 The package exports a `themePropType` which can be used to check the `theme` prop:
 
-```js
+```tsx
 import PropTypes from 'prop-types';
 import { withTheme } from '@emotion/react';
 import { themePropType } from '@sumup/design-tokens';
@@ -63,13 +86,15 @@ ComponentWithInlineStyles.propTypes = {
 export default function withTheme(ComponentWithInlineStyles);
 ```
 
-### With TypeScript
+#### With TypeScript
 
-The package exports a `Theme` interface which can be used to type Emotion's `styled` function. Create a custom `styled` instance as described in the [Emotion docs](https://emotion.sh/docs/typescript):
+The package exports a `Theme` interface that can be used to augment Emotion.js' types as described in the [Emotion.js docs](https://emotion.sh/docs/typescript#define-a-theme):
 
-```tsx
-import styled, { CreateStyled } from '@emotion/styled';
-import { Theme } from '@sumup/design-tokens';
+```ts
+import '@emotion/react';
+import { Theme as CircuitUITheme } from '@sumup/design-tokens';
 
-export default styled as CreateStyled<Theme>;
+declare module '@emotion/react' {
+  export interface Theme extends CircuitUITheme {}
+}
 ```