@planview/pv-tokens

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/pv-tokens
yarn add @planview/pv-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/pv-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/pv-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/pv-tokens/css/variables.css and @planview/pv-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>

To add support for Dark mode, include @planview/pv-tokens/css/theme-dark.css in your build, and then add data-react-pvds-theme="dark" to the html element when you want dark mode to work.

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/pv-tokens/less/variables.less';

div {
    padding: @pvds-spacing-small;
    border: solid 1px @pvds-color-border-error;
    color: @pvds-color-text-error;
}

To use LESS variables that read from CSS variables (to support theming at run time), you'll need to include additional files:

@import (reference) '@planview/pv-tokens/less/variables.less';
@import (reference) '@planview/pv-tokens/less/theme.less';

div {
    padding: @pvds-spacing-small;
    border: solid 1px @pvds-color-border-error;
    color: @pvds-color-text-error;
}

You will also need to include @planview/pv-tokens/css/variables.css and @planview/pv-tokens/css/theme-dark.css as part of your production build to fully support Dark mode.

If you need static colors that don't change when the theme changes, either add .pvds-static to the containing DOM element or import @planview/pv-tokens/less/static.less and all the color variables are available prefixed as @pvds-static- (for instance, @pvds-static-color-primary-500).

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/pv-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/pv-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;
}

To use SCSS variables that read from CSS variables (to support theming at run time), you'll need to include additional files:

@import (reference) '@planview/pv-tokens/scss/_variables.scss';
@import (reference) '@planview/pv-tokens/scss/_theme.scss';

div {
    padding: @pvds-spacing-small;
    border: solid 1px @pvds-color-border-error;
    color: @pvds-color-text-error;
}

You will also need to include @planview/pv-tokens/css/variables.css and @planview/pv-tokens/css/theme-dark.css as part of your production build to fully support Dark mode.

If you need static colors that don't change when the theme changes, either add .pvds-static to the containing DOM element or import @planview/pv-tokens/scss/_static.scss and all the color variables are available prefixed as $pvds-static- (for instance, $pvds-static-color-primary-500).

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/pv-tokens/scss/_variables.scss';
@use '@planview/pv-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/pv-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