Creating Custom Themes

You can start using Reshaped 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, Reshaped has a command-line interface for creating new themes.

Adding themes

You need to create a reshaped.config.js file with the theme definitions next to your project's package.json file to add new themes.

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

Theme fragments

In addition to themes, reshaped.config.js allows you to create theme fragments. Theme fragment is a subset of a theme values overrides. By using theme fragments, you can save bundle size as your theme output will contain only the tokens you have changed instead of the whole theme.

This is quite helpful when you're customizing a specific part of the product but don't need to apply this customization to the whole page. For instance, you can create a Twitter theme fragment to implement a TwitterButton component.

Another benefit is that it's easier to combine themes that way. For example, if your product has two themes and you need to render the TwitterButton in both themes, you won't have to create all combinations of themes yourself. Instead, you can create two main themes and a Twitter theme fragment that will inherit the correct token values from the currently used theme.

CLI

Now that we have a config file with theme definitions added, we can use Reshaped 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 reshaped.config.js file and compile them into the src/themes folder. Script will create a folder for each theme and theme fragment with a variables files inside.

Using in the application

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

Our product now uses a custom theme and has a new foregroundNeutral token value available. It still uses other tokens from the default Reshaped theme, which means Button component uses a violet 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 reshaped.config.js is a Javascript file, you can use comments to enable type checking for the config:

  • // @ts-check enables type checking for the config file.
  • @type comment defines the type for the variable used next. This means that the config format will be type checked according to the type definition coming from the Reshaped package.

Tokens format

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

In addition to the tokens in theme defintion, we also generate automatically generate dynamic token 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:

  • base unit contols how condensed your UI is
  • 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 headings but still keep the product styles consistent.
  • If you're using a custom font in this token, don't forget to include your font file into the product

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. For example, in the format code snippet the token uses title1 for s-m screens and display3 for l+ screens.

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