WARNING

Use tokens from the @semcore/theme package instead of @semcore/core, as they will be removed from the core package starting from version 17.

Description

Design tokens are variables that store visual design choices (colors, fonts, spaces, opacity, box-shadows, etc.). The most important thing is that tokens ensure the same style names and values are used in design files and code.

Intergalactic Design System has:

• set of base tokens that define a base palette;
• set of semantic tokens which are applied across all components and even the chart library.

These sets form the default theme of the design system.

TIP

For the complete JSON with all the token sets, refer to the GitHub repository.

Stylelint plugin

The stylelint plugin helps developers to avoid mistakes in the design token names. It's part of intergalactic npm package but also might be installed as a separate package.

// .stylelintrc.json
{
  "extends": ["stylelint-config-standard"],
  "plugins": ["@semcore/stylelint-plugin"],
  "rules": {
    "intergalactic/design-tokens": true
  }
}

Available options

• include - adds custom design tokens to the list of allowed tokens.
• exclude - removes design tokens from the list of allowed tokens.
• tokensSource - path to the file with design tokens. Default is node_modules/@semcore/core/lib/theme/themes/default.mjs.
• tokensPrefix - design tokens (default is --intergalactic-). Only CSS variables with this prefix are considered as design tokens.

Base tokens

Base tokens include:

• our product palette;
• font size, line height, font weight, and letter spacing values;
• the base spacing and sizing scale;
• sizing;
• spacing;
• the base border radius scale;
• breakpoints.

The palette was built with Huetone tool (learn more about the tool in the Twitter thread).

Shades of the same color have a value ranging from 50 to 800, depending on its tone. Each shade has recommendations for use based on Huetone's contrast ratio calculation.

Semantic tokens

It's a list of tokens for components and charts for the default Intergalactic theme.

Semantic tokens include:

• colors;
• box shadows;
• border radius;
• form control heights;
• opacity;
• z-index;
• animation durations.

To learn more about the tokens names, see Token naming structure section.

Themes

If you need to build a product that differs in style and tone of voice from our default theme, you can create a custom theme.

Theme is a set of tokens represented in CSS variables that has different from the default sets values. Values can be changed for base, semantic, or both sets. You can redefine them globally or only for a specific subtree of React app. Refer to the Usage in development.

Creating new theme

Step one. Design new theme

Creating a theme usually starts with design. In fact, this is the most time-consuming part.

We recommend you using the native Figma variables (tokens) functionality. Refer to the following tutorials, for the detailed process for creating a new theme. Semrush designers and developers can use the following tutorials:

• Tutorial for Figma tokens
• Tutorial for Tokens Studio

In case if you need more functionality that Figma doesn't have at the moment, use Tokens Studio plugin for Figma. It's one of the most powerful tools for managing tokens, linking styles between the code and Figma files.

For non-Semrush employees we have a tutorial for Tokens Studio.

TIP

In cases where different styles are needed for just one component or a part of the design system:

• Designer can create a new theme as described earlier, and apply it only to the necessary component
• Developer can use ThemeProvider

Step two. Connect new theme to components in code

For this step, you need to export your token sets with the new values and process them into CSS styles in the way that suits you best. We recommend referring to the following links:

• Usage in development;
• Example for custom component;
• CSS Injection guide.