Design Tokens – Planview Design System
A design token is the smallest piece of a reusable design language. They give a name and value to colors, spacing, sizes, etc.
When talking about a specific color in a design we'll reference error-500
instead of #dd1515
. Using named tokens simplifies communication and enables us to change the specific value over time. This abstraction also helps with the proper flow of values through the system. When all sizes, colors, and spacing use the appropriate design tokens, system-wide changes become simpler while providing a consistent look and feel across products and platforms.
General Usage
Installation
You can install via npm
or yarn
(or compatible package manager):
npm install @planview/design-tokens
yarn add @planview/design-tokens
Versioning
This project uses semantic versioning. This means you should be able to specify the version with a caret to pull in minor and patch versions automatically (For example: "@planview/design-tokens": "^1.0.0"
)
Format Usage
We currently build the tokens into several formats. In addition to the tokens, we also provide helpers in CSS, LESS, and SCSS for text styles.
CSS
Variables use a kebab-case format prefixed with pvds
. For instance --pvds-color-error-500
or --pvds-size-small
. Numerical values are provided in pixels or percentages.
Once you've included @planview/design-tokens/css/variables.css
in your build, the variables can be used as follows:
div {
padding: var(--pvds-spacing-small);
border: solid 1px var(--pvds-color-border-error);
color: var(--pvds-color-text-error);
}
To use the text style classes, include both @planview/design-tokens/css/variables.css
and @planview/design-tokens/css/text-styles.css
in your build, then apply one of the classes to your elements. We do not reset padding/margin on these classes so you will need to handle that in your code if needed.
<h2 class="pvds-text-style-h2">My title</h2>
LESS
Variables use a kebab-case format prefixed with pvds
. For instance @pvds-color-error-500
or @pvds-size-small
. Numerical values are provided in pixels or percentages.
@import (reference) '@planview/design-tokens/less/variables.less';
div {
padding: @pvds-spacing-small;
border: solid 1px @pvds-color-border-error;
color: @pvds-color-text-error;
}
The text styles are provided as mixins. We do not reset padding/margin on these classes so you will need to handle that in your code if needed.
@import (reference) '@planview/design-tokens/less/variables.less';
h2 {
.pvds-text-style-h2();
}
SCSS
Variables use a kebab-case format prefixed with pvds
. For instance $pvds-color-error-500
or $pvds-size-small
. Numerical values are provided in pixels or percentages.
@use '@planview/design-tokens/scss/_variables.scss';
div {
padding: $pvds-spacing-small;
border: solid 1px $pvds-color-border-error;
color: $pvds-color-text-error;
}
The text styles are provided as mixins. We do not reset padding/margin on these classes so you will need to handle that in your code if needed.
@use '@planview/design-tokens/scss/_variables.scss';
@use '@planview/design-tokens/scss/_text-styles.scss';
h2 {
@include pvds-text-style-h2;
}
TypeScript and JavaScript
The tokens are exposed as namespaced exports. Numerical values are provided as integers or strings (in the case of percentages).
There are no equivalent text style helpers in TS or JS as provided by the other formats.
import * as React from 'react'
import { iconSize, size } from '@planview/design-tokens'
const Example = () => {
return (
<svg width={size.medium} height={size.medium}>
<use href="#icon" width={iconSize.small} height={iconSize.small} />
</svg>
)
}
export default Example
For contributors
Building
yarn
yarn build
Publishing new tokens from Figma
When new changes need to be published, first make the changes in Figma using the Figma Tokens plugin. Once the update tokens are pushed (using the steps below), a Pull Request will be opened to this repository with the generated files for review.
Setup
-
Ensure the Figma Tokens plugin is installed
-
Configuration changes are stored with the document, so there shouldn't be a need to change anything in the settings.
-
In GitHub, Create a Personal Access Token that has repo
privileges (and consider adding the token to LastPass so you don't lose it)
-
Enable SSO on the new token for the Planview Design System
organization in Github.
-
In Figma, launch the Figma Tokens plugin and step past any announcements. Click Set up sync.

-
Paste your Personal Access Token in the field and click Save

-
When prompted, pull the latest from GitHub.
-
Ensure "Ignore first part of token name for styles" is checked in the Settings tab of Figma Tokens.
Publishing
-
Make the desired changes in Figma Tokens
Important: If you close Figma Tokens without pushing your changes, you will lose your changes. GitHub is the authoritative source of the tokens.
-
Click the Push to GitHub button in Figma Tokens to send the changes to the repository. The commit message should be a very short summary of changes made. Its best to perform several small changes vs one large set of changes.

-
You do not need to create a pull request. One will be automatically created if needed. You can close the dialog.
Pulling
Figma Tokens will pull from GitHub on launch, but if you need to pull again while the plugin is open you can use the "Pull from GitHub" button.
