@octopusdeploy/design-system-tokens/README.md

The design systems tokens. This package contains the raw tokens in their original format, and compiled to an appropriate format for consumption by the design system components.

# 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](https://www.figma.com/design/aTDMPG8kKA8KflciEtqHht/Design-System-%7C-Foundations?node-id=0-1&p=f&t=7WLLqO0UAPvTF9u9-11)
* 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](https://tokens.studio/starter-plus) initiated in the [Design System | Foundations](https://www.figma.com/design/aTDMPG8kKA8KflciEtqHht/Design-System-%7C-Foundations?m=auto) Figma file.
2. Designer creates a branch with their changes and [pushes them to GitHub](https://docs.tokens.studio/token-storage/remote-push-pull-changes#push-to-sync-provider) 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](https://www.octopus.design/latest/contribute/communicating-changes-u8Ca6udU-u8Ca6udU).

### How the token build process works
The build process depends on two key packages: [Styled Dictionary](https://styledictionary.com/) and [@token-studi/sd-transforms](https://github.com/tokens-studio/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](https://github.com/OctopusDeploy/OctopusDeploy/blob/main/frontend/packages/design-system-tokens/build/tokensSchema.mts) to validate that token metadata is in the expected format.

All the build scripts are located in the [build folder](https://github.com/OctopusDeploy/OctopusDeploy/tree/main/frontend/packages/design-system-tokens/build), and the entry point is [build.mts](https://github.com/OctopusDeploy/OctopusDeploy/blob/main/frontend/packages/design-system-tokens/build/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](https://github.com/OctopusDeploy/OctopusDeploy/blob/main/frontend/packages/design-system-tokens/src/generated/globals.ts): `borderRadius`, `borderWidth`, `fontSize` etc.

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

### Importing 
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](https://tokens.studio/starter-plus)
* [Token Studio sd-transform package](https://github.com/tokens-studio/sd-transforms)
* [Style Dictionary package](https://styledictionary.com/)

## Contributing
The Design System Tokens package is managed by the [Frontend Foundations Team](https://octopushq.atlassian.net/wiki/spaces/RND/pages/2250997828/Frontend+Foundations+Team+FFT). Please [consult us](https://octopusdeploy.slack.com/archives/C02PAUNL6J0) before making changes to this package.

If you want to add or modify a design token, follow the guidelines for [Proposing a Design Token](https://www.octopus.design/latest/contribute/proposing-a-design-token-T3qepMGe-T3qepMGe).