@sumup-oss/design-tokens
v8.0.1
Published
Visual primitives such as typography, color, and spacing that are shared across platforms.
Downloads
1,367
Keywords
Readme
@sumup-oss/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-oss/design-tokens
# With yarn v1
yarn add @sumup-oss/design-tokensUsage
The design tokens are exported as CSS custom properties. Choose a font loading strategy and a color scheme, then import the corresponding CSS file globally in your application, such as in Next.js' app/layout.tsx file:
// app/layout.tsx
import '@sumup-oss/design-tokens/fonts.css';
import '@sumup-oss/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.
Refer to the theme documentation for a complete reference of the available tokens.
Fonts
Import the stylesheet that contains the font face declarations globally in your application, such as in a global layout file:
import '@sumup-oss/design-tokens/fonts.css';To speed up the loading of the fonts, add preload links to the global <head> element of your application. Choose which subsets to preload based on the languages your app supports. The available subsets are latin, latin-ext, cyrillic, cyrillic-ext, greek, greek-ext, and vietnamese.
<link
rel="preload"
href="https://static.sumup.com/fonts/Inter/Inter-normal-latin.woff2"
as="font"
type="font/woff2"
crossorigin
/>Do not use Next.js' built-in font optimization as it doesn't support Inter's italic axis.
Color schemes
Single color scheme
For applications that support a single color scheme, import the @sumup-oss/design-tokens/light.css or @sumup-oss/design-tokens/dark.css themes. They contain the complete set of design tokens, in light and dark mode respectively. The tokens are defined globally on the :root element. The themes can be used independently or with a scoped theme.
Scoped color scheme
To apply a different color scheme to a subset of an application, import the @sumup-oss/design-tokens/light-scoped.css or @sumup-oss/design-tokens/dark-scoped.css themes. They contain only color tokens which are scoped to the data-color-scheme="light" and data-color-scheme="dark" selectors respectively. The themes must be used alongside a full theme to ensure that all design tokens are defined.
Multiple color schemes
For applications that support switching between light and dark color schemes, import the @sumup-oss/design-tokens/dynamic.css theme. It contains all tokens defined globally on the :root element, the dark color tokens scoped to the prefers-color-scheme: dark media query, and the scoped themes. By default, the color scheme follows the system settings. Add the data-color-scheme attribute on the document root to set a specific color scheme.
Ensure that users have full control over their preferred color mode: dark, light, or match system. Their choice should be persisted between devices and sessions. There should be no Flash of inAccurate coloR Theme (FART), regardless of whether the app is client-side or server-side rendered.
Legacy JavaScript theme
[!WARNING] The JavaScript theme is being replaced by CSS custom properties (aka CSS variables) to improve performance and compatibility with other frameworks. We recommend installing the
@sumup-oss/eslint-plugin-circuit-uiESLint plugin and turning on theprefer-custom-propertiesandno-invalid-custom-propertiesrules to help with the migration.
The light theme is meant to be used with Emotion.js' ThemeProvider:
import { light } from '@sumup-oss/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-oss/design-tokens';
function ComponentWithInlineStyles({ theme, label }) {
return <div style={{ borderRadius: theme.borderRadius.kilo }}>{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 type { Theme as CircuitUITheme } from '@sumup-oss/design-tokens';
declare module '@emotion/react' {
export interface Theme extends CircuitUITheme {}
}