npm package: @planview/design-tokens
Description: Planview design system tokens
Author: Planview
Latest version: 0.2.0
Deprecated: No longer maintained. Please use @planview/pv-tokens instead.

# 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):

```bash
npm install @planview/design-tokens
yarn add @planview/design-tokens
```

### Versioning

This project uses [semantic versioning](https://semver.org/). 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:

```css
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.

```html
<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.

```less
@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.

```less
@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.

```scss
@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.

```scss
@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._

```ts
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

```bash
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](https://www.figma.com/community/plugin/843461159747178978/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](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-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**.

    ![Set up sync prompt](./docs/figma-tokens-prompt.png)

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

    ![Edit storage item modal](./docs/figma-tokens-sync-setup.png)

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.

    ![Push to GitHub](./docs/figma-tokens-push.png)

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.

![Pull from GitHub](./docs/figma-tokens-pull.png)