diff --git a/docs/introduction/2-getting-started.mdx b/docs/introduction/2-getting-started.mdx index d7bd18cf49..7b11360691 100644 --- a/docs/introduction/2-getting-started.mdx +++ b/docs/introduction/2-getting-started.mdx @@ -26,74 +26,40 @@ npm install @sumup/circuit-ui yarn add @sumup/circuit-ui ``` -Circuit UI relies on some mandatory peer dependencies, namely [@sumup/design-tokens](https://www.npmjs.com/package/@sumup/design-tokens), [@sumup/icons](https://www.npmjs.com/package/@sumup/icons), [@sumup/intl](https://www.npmjs.com/package/@sumup/intl), [React](https://reactjs.org/), and [Emotion](https://emotion.sh/). You should install them with the following command: +Circuit UI relies on some mandatory peer dependencies, namely [@sumup/design-tokens](https://www.npmjs.com/package/@sumup/design-tokens), [@sumup/icons](https://www.npmjs.com/package/@sumup/icons), [@sumup/intl](https://www.npmjs.com/package/@sumup/intl), and [React](https://reactjs.org/). You should install them with the following command: ```sh # With npm: -npm install --save @sumup/design-tokens @sumup/icons @sumup/intl react react-dom @emotion/react @emotion/styled +npm install --save @sumup/design-tokens @sumup/icons @sumup/intl react react-dom # With yarn v1 -yarn add @sumup/design-tokens @sumup/icons @sumup/intl react react-dom @emotion/react @emotion/styled +yarn add @sumup/design-tokens @sumup/icons @sumup/intl react react-dom ``` -We also recommend installing and configuring [`@sumup/eslint-plugin-circuit-ui`](Packages/eslint-plugin-circuit-ui/Docs) and [`@sumup/stylelint-plugin-circuit-ui`](Packages/stylelint-plugin-circuit-ui/Docs). The plugins will lint [Circuit UI custom properties](Features/Theme/Docs) and will include codemods for future Circuit UI breaking changes. +We also recommend installing and configuring [`@sumup/eslint-plugin-circuit-ui`](Packages/eslint-plugin-circuit-ui/Docs) and [`@sumup/stylelint-plugin-circuit-ui`](Packages/stylelint-plugin-circuit-ui/Docs). The plugins will lint [Circuit UI custom properties](Features/Theme/Docs) and include codemods for Circuit UI breaking changes. + +### Importing the styles ### Configuring the theme -SumUp's default themes are part of the [@sumup/design-tokens](https://www.npmjs.com/package/@sumup/design-tokens) package. In most cases, they should cover your needs. Refer to the [Theme documentation](Features/Theme/Docs) to learn how to use and customize the theme. +SumUp's default theme is part of the [@sumup/design-tokens](https://www.npmjs.com/package/@sumup/design-tokens) package. Refer to the [Theme documentation](Features/Theme/Docs) to learn how to use and customize the theme. -To make the theme available to Circuit UI, wrap the root of your application in the `ThemeProvider` from Emotion and add the `BaseStyles` component: +To make the theme available to Circuit UI, import the theme styles _before_ the component styles: ```tsx -// _app.tsx for Next.js or App.js for CRA -import { ThemeProvider } from '@emotion/react'; -import { light } from '@sumup/design-tokens'; -import { BaseStyles } from '@sumup/circuit-ui'; - -export default function App() { - return ( - - - {/* Your app */} - - ); -} -``` - -#### Typing the theme - -If you're using TypeScript, you might run into type conflicts when using the `theme` prop: - -``` -Type 'Theme' is not assignable to type 'ThemeArgs'.ts(2322) +// /app/layout.tsx or /pages/_app.tsx for Next.js +import '@sumup/design-tokens/light.css'; +import '@sumup/circuit-ui/styles.css'; ``` -Type the theme by extending the `@emotion/react` module declaration, for example in a new `types/emotion.d.ts` file (make sure the file is included in `typeRoots` in your `tsconfig.json`): - -```ts -// types/emotion.d.ts -import { Theme as CircuitTheme } from '@sumup/design-tokens'; -import {} from '@emotion/react/types/css-prop'; // See https://github.com/emotion-js/emotion/pull/1941 - -declare module '@emotion/react' { - // eslint-disable-next-line @typescript-eslint/no-empty-interface - export interface Theme extends CircuitTheme {} -} -``` - -This will also enable Intellisense for the theme object. - -For more information, refer to [Emotion's TypeScript documentation](https://emotion.sh/docs/typescript#define-a-theme). - ### Configuring the viewport Finally, make sure that the viewport meta tag includes `viewport-fit=cover`, and that your app has the right padding to render inside [CSS safe areas](): ```tsx -// _app.tsx for Next.js or App.js for CRA -import { ThemeProvider } from '@emotion/react'; -import { light } from '@sumup/design-tokens'; -import { BaseStyles } from '@sumup/circuit-ui'; -import Head from 'next/head'; // Add the meta tag directly in index.html with CRA +// /app/layout.tsx or /pages/_app.tsx for Next.js +import '@sumup/design-tokens/light.css'; +import '@sumup/circuit-ui/styles.css'; +import Head from 'next/head'; const Layout = css` padding: env(safe-area-inset-top) env(safe-area-inset-right) env( @@ -103,8 +69,7 @@ const Layout = css` export default function App() { return ( - - + <> {/* Your app */} - + ); } ```