Design System Tokens

Design System Tokens is a package that contains:

* design token values with associated themes, corresponding to Design System Foundations file in Figma
* an automated build process for generating tokens in appropriate formats

How it works

1. Designer adds or modifies a design token in Tokens Studio Plugin initiated in the Design System | Foundations Figma file.
2. Designer creates a branch with their changes and pushes them to GitHub using Tokens Studio. The branch name should start with tokens/, new commit in a branch with such naming convention triggers Github Action to generate the Design Tokens automatically in appropriate formats.
3. Designer requests a review on the Pull Request from Frontend Foundations.
4. Engineer reviews the Pull Request, makes necessary code change if needed, and merges the changes to main.
5. Designer communicates changes accordingly to Communication Guidelines.

$3

The build process depends on two key packages: Styled Dictionary and @token-studi/sd-transforms. We highly recommend reading the Styled Dictionary's documentation to understand the structure of the build process. We also use Zod with defined schema to validate that token metadata is in the expected format.

All the build scripts are located in the build folder, and the entry point is build.mts.

Usage

Design tokens are grouped as following, all the dimension tokens are 16px (1rem) based.
- themeTokens: contains all the colour tokens and shadow tokens.
- text: shorthand tokens that can be applied to font style.
- space: dimension tokens to be used for spacing, such as gap, padding.
- other tokens in globals: borderRadius, borderWidth, fontSize etc.

> Note: direct usage of colorScales is highly not recommended, you should use themeTokens.color instead when seeking for colour tokens.

$3

Design tokens can be imported from @octopusdeploy/design-system-tokens package.

Example:
``typescript
import { themeTokens, space, text, borderRadius } from "@octopusdeploy/design-system-tokens";
``

Dependencies

The workflow of managing and design tokens in this package depends on the following external tools and services:

* Tokens Studio Figma Plugin
* Token Studio sd-transform package
* Style Dictionary package

Contributing

The Design System Tokens package is managed by the Frontend Foundations Team. Please consult us before making changes to this package.

If you want to add or modify a design token, follow the guidelines for Proposing a Design Token.