@sumup/design-tokens

@sumup/design-tokens

Visual primitives such as typography, color, and spacing for Circuit UI Web.

Installation

Depending on your preference, run one of the following in your terminal:

# With npm
npm install @sumup/design-tokens

# With yarn v1
yarn add @sumup/design-tokens

Usage

The legacy JavaScript theme for Emotion.js is being replaced by CSS custom properties (aka CSS variables) to improve performance and compatibility with other frameworks. We recommend installing the @sumup/eslint-plugin-circuit-ui ESLint plugin and turning on the prefer-custom-properties and no-invalid-custom-properties rules to help with the migration.

Refer to the theme documentation 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 globally in your application, such as in Next.js' _app.tsx file:

// _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, Create React App, Vite, Parcel, 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:

import { light } from '@sumup/design-tokens';
import { ThemeProvider } from '@emotion/react';
import styled from '@emotion/styled';

const Bold = styled.strong`
  font-weight: ${(p) => p.theme.fontWeight.bold};
`;

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

The package exports a themePropType which can be used to check the theme prop:

import PropTypes from 'prop-types';
import { withTheme } from '@emotion/react';
import { themePropType } from '@sumup/design-tokens';

function ComponentWithInlineStyles({ theme, label }) {
  return <div style={{ color: theme.colors.p500 }}>{label}</div>;
}

ComponentWithInlineStyles.propTypes = {
  theme: themePropType.isRequired,
  label: PropTypes.string,
};

export default function withTheme(ComponentWithInlineStyles);

With TypeScript

The package exports a Theme interface that can be used to augment Emotion.js' types as described in the Emotion.js docs:

import '@emotion/react';
import { Theme as CircuitUITheme } from '@sumup/design-tokens';

declare module '@emotion/react' {
  export interface Theme extends CircuitUITheme {}
}