Theming

We have designed the backpack UI component library to be as easy to theme as possible. Our approach is based on css variables which we generate from a centralised set of reusable design tokens. We are not using any libraries for styling in backpack, so you can easily integrate it with your own approach, read

Design Tokens and CSS

Design tokens allow us to ensure alignment between the Figma backpack component library and the React component library. The approach is based on Amazon's Style Dictionary library, which allows us to maintain a standardised set of design tokens in code which are then used to generate css variables used by our React library, and a JSON file of tokens which can be consumed by a custom figma plugin.

For more detail on the design side of how tokens are structured, read the GUD Token Docs (opens in a new tab).

Tokens system

We have taken cues from Google's Material Design for our tokens system. We use 4 types of tokens:

• Brand tokens. A direct representation of our core brand guidelines in GUD. Brand tokens should never be changed or overridden.
• Reference tokens. These are the first level of design tokens offering a broad selection of design options throughout the system. When themeable, reference tokens are mainly applied through alias tokens.
• System tokens. The system tokens give the Backpack design system its recognizable look and feel.
• Component tokens. Specific tokens for individual components.

CSS variable generation

All of our design tokens generate equivalent css variables. As such a token inside the color token constant such as:

Will be added to the root declaration of our global css file like:

The same goes for all token types. This means all tokens are available to our components and any you build on top. Furthermore, since they are CSS variables, you can override them with themed values at any level of depth in the HTML document tree.

SCSS Modules, global styles and variables

Our components use SCSS modules to encapsulate css styles. The module styles are component specific, and where relevant use component variables which fall back to system variables. This gives you a cascade of specificity to apply styles to. i.e for primary buttons:

You can see that if the component text color variable is not defined (which it won't be by default) the button text color will fall back to the default text color on dark (white).

You can set and override these css variables at any level of specificity in the tree, making it very easy to create globally or locally themed components.