What’s a Design Token?
Design Tokens are key and value pairs that represent our design decisions. In practice, they symbolize variables used repeatedly across the interface.
For example, instead of applying a raw color value (such as grey or a corresponding HEX code) to style text, we use color.text.primary. Learn more about our Design Tokens approach and structure.
Contributing a Design Token
We consider adding, modifying, or removing a Design Token a Medium contribution to the design system. Design tokens are the Foundation of the system and require thorough consideration to maintain the Octopus brand and visual cohesiveness.
Additionally, changing or removing existing tokens will have visual consequences across the UI (for example, a change in color contrast might negatively impact accessibility) that must be thoroughly tested before release.
Tokens Studio initial set up
We use Tokens Studio to maintain Design Tokens between design implementation (in Figma) and code implementation (in GitHub).
- Install the Tokens Studio Plugin for Figma: if you need help, follow the steps outlined in Tokens Studio documentation.
- Fill out the plugin Settings page:
- Add a license key: you can find one in Software Licenses / Tokens Studio.
- Click Add a new sync provider: choose GitHub and provide the following details:
|
Name |
This is a nickname that shows up in the plugin settings page later on to identify this specific sync provider configuration. Choose something memorable to you and your project. For example: Octopus Design System Tokens. |
|---|---|
|
Personal Access Token |
Follow these steps to create a Personal Access Token in GitHub unique to you. |
|
Repository |
OctopusDeploy/OctopusDeploy |
|
Branch |
main |
|
Token storage location |
frontend/packages/design-system-tokens/tokens/tokens.json |
Once you’ve set up those details, you can pull and push changes to GitHub. You’re now ready to follow the Design contribution steps below.
Design
Prerequisites: access to Figma, GitHub and Tokens Studio set up.
- Add Design Tokens as Figma Variables to the Foundations Library: follow our naming conventions and create tokens for both Light and Dark modes under the Theme collection and color group.
- Add the same Design Tokens in Tokens Studio: create a token that mimics the Figma Variable (button.icon.primary → color.button.icon.primary).
- Commit and push your changes: Click the push icon to open the push modal. You’ll see the commit form: provide a short description of your change, and make sure you’re pushing to a new branch (for example: ks-add-new-button-tokens). Never commit to main.
- Publish a Pull Request containing the change: Click the ”Create Pull Request” button in Tokens Studio—you’ll be redirected to GitHub. Octopus has a ready-made PR template to guide you in creating a Pull Request and describing changes (or check an example past PR).
- Request a review for your Pull Request: Post it in the #team-frontend-foundations-reviews channel according to the channel guidelines. One of the engineers will follow the steps for Engineers and get the changes released.
Engineering
Prerequisites: access to GitHub and OctopusDeploy/OctopusDeploy application set up.
- Check out the Pull Request branch: find the link in the #team-frontend-foundations-reviews channel.
- Generate the design tokens: run the build script in one of the following ways:
- Commit the generated tokens.
- Address errors (if any): remedy errors in generated tokens and/or failing builds. This might require collaboration with design
- If you modify an existing token, you must manually test the change, including for the application’s Light and Dark modes.
- Merge the Pull Request: When the build is passing and there are no more required changes, merge the Pull Request to release the token changes.