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';
// Depending on your compiler you may need to use @import instead

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';
// Depending on your compiler you may need to use @import instead

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

1. Ensure the Figma Tokens plugin is installed

2. Configuration changes are stored with the document, so there shouldn't be a need to change anything in the settings.

3. In GitHub, Create a Personal Access Token that has repo privileges (and consider adding the token to LastPass so you don't lose it)

4. Enable SSO on the new token for the Planview Design System organization in Github.

5. In Figma, launch the Figma Tokens plugin and step past any announcements. Click Set up sync.

   

6. Paste your Personal Access Token in the field and click Save

   

7. When prompted, pull the latest from GitHub.

8. Ensure "Ignore first part of token name for styles" is checked in the Settings tab of Figma Tokens.

Publishing

1. 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.

2. 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.

   

3. 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.