Creating Custom Themes

You can start using Arcade with the theme we provide but at some point you might want to apply custom values to the design tokens and align them with your brand. To solve that, Arcade has a command-line interface for creating new themes.

Adding themes

To add new themes, you need to create an arcade.config.js file with the theme definitions.

In this example, we have defined a theme that will only change foregroundNeutral token value. All other values will inherited from the default Arcade theme.

Theme fragments

In addition to themes, arcade.config.js allows to create theme fragments. Theme fragment is a subset of a theme values overrides. By using fragments, you can build a theme that contains only a small subset of variables instead of creating a file with all supported variables. For instance, you can create a Twitter theme fragment to then create a TwitterButton component.

Keeping other values coming from the main theme in runtime makes it easier to combine themes together. If you have two themes used in your product, you don't have to build a Twitter theme for each of them separately. Instead you could build a theme fragment that will work with both of them.

CLI

Now that we have a config file with theme definitions added, we can use Arcade CLI to generate these themes. Let's add an NPM script to call the CLI to your package.json:

Running yarn build:themes or npm run build:themes now will take your added theme definitions from arcade.config.js file and compile them into the src/themes folder. For each theme and theme fragment script will create a folder with their name and a css file with the variables inside.

Using in the application

With the themes built, you can now import them in your code. We can start by picking the productTheme we've just built and pass it to the Arcade provider:

Our product now uses a custom theme and has a new foregroundNeutral token value available. It still uses other tokens from the default Arcade theme, which means Button component uses purple color for its background.

Let's create a TwitterButton component with a different button background color with a twitter theme fragment. We can use a ThemeProvider utility to define a theme just for the components rendered inside it.

This concept is called Scoped theming, and you can learn more about it in a separate section.

Typescript support

Even though arcade.config.js is a Javascript file, you can use comments to enable type checking for the config:

  • // @ts-check will enable type checking for the config file.
  • @type comment will define the type for the variable defined after it. This means that the format of the config will be type checked according to the type definition coming from the Arcade package.

Tokens format

Theme is represented with an object that has token types as keys. Each token type contains an object of token objects with their values.

Most of the tokens you define in the theme object and some of them will be generated automatically based on other values. You can find more about the result css output for tokens in the Design Tokens section.

Color

Format:

Available token names:

  • All onBackground color tokens are generated automatically.
  • hexDark value is optional in case you're not using dark mode or if the values are same in both modes
  • black and white tokens should preserve their values in both light and dark mode

Unit

Format:

Available token names:

  • x1 - x10 unit tokens will be auto generated based on your base token px value.

Font family

Format:

Available token names:

Two font family types let you differentiate between regular text and larger headings but still keeping the product styles consistent.

Font weight

Format:

Available token names:

Font

Format:

Available token names:

  • fontWeightToken refers to the font weight token names
  • fontFamilyToken refers to the font family token names
  • responsive is an optional field to make the typography responsive based on the viewport size
  • responsive values refer to the font token names and are mobile first. In our format example it means that token is using title1 for s-m and display3 for l+.

Shadow

Format:

Available token names:

  • Uses an array of values to apply multiple shadows to the same element
  • colorToken is referring to a color token name