More topics

Design tokens for developers

Last updated on August 27, 2024

Guidance for developers on how to install and use the B.C. Design System tokens package.

On this page:

Getting started with tokens

Developers can access and use tokens by installing the B.C. Design Tokens package as a dependency. The package is available on npm:

Install the B.C. Design Tokens package

Release notes and changelogs for each version of the package are available on npm.

The package is open source, and published under the Apache 2.0 license. The source code is published on GitHub.

Supported languages

Currently, we publish tokens in three formats:

  • CSS
  • JavaScript (ECMAScript)
  • JavaScript (CommonJS)

TypeScript declarations are included for both JavaScript implementations.

Versioning

The design tokens package uses semantic versioning (major.minor.patch). Because design tokens affect the public-facing design of your interface, we recommend:

  • Installing major version updates manually, as they may contain breaking changes
  • Carefully reviewing release notes to understand what has changed

We may be able to support other formats or languages on request. If you need an alternative implementation for your project, open an issue on GitHub or email designsystem@gov.bc.ca. 

Using tokens in your project

Once you've installed the design tokens package, import your preferred version of the variables file into your project.

To find a specific token, search by element (eg. 'border'), state (eg. 'hover' or 'warning') or a specific style (eg. 'H1').

How tokens are organised

The design tokens library includes almost 200 individual tokens. Tokens are organised by type and intended usage:

  • Surface: colour palettes and effects used to style UI elements
  • Support: colour palettes used for messaging (status, alerts and warnings) 
  • Layout: sizing and spacing measures
  • Typography: values used to implement the typescale
  • Icons: sizing and colour values for icons and indicators

To explore the full list of tokens, view the design tokens glossary.

Prefixed variables

The design tokens package includes 'prefixed' and 'non-prefixed' versions for each supported format.

Prefixed variables include a 'BCDS' namespace value at the start of each variable, to reduce the risk of collision with existing styles or variables.

Non-prefixed variables more closely match code generated by Figma, and may make collaboration and handoff with designers using the B.C. Design Tokens library easier.

There are no other differences between the two formats. Use whichever is best suited for your use-case.