@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

Flutter/Dart

Even though npm is not the typical package manager for Flutter/Dart projects, we provide .dart files in this package as a convenience for Planview products using Flutter.

The files (color.dart, size.dart, icon_size.dart and spacing.dart) are located in the flutter/ folder of the package. You can copy the files you need into your Flutter project and import them as needed.

The tokens are exposed as static constants inside classes. PvdsColor, PvdsSize, PvdsIconSize, and PvdsSpacing.

In the example below we have placed the files from the library in a pvds folder inside the theme folder of the Flutter project. We then import the color tokens and use one of the text colors in a custom AppColors class.

import 'package:your-package/theme/pvds/color.dart';

class AppColors {
    static const primaryTextColor = PvdsColor.textPrimary;
}

For contributors

Building

yarn
yarn build