npm package: @planview/pv-tokens
Description: Planview design system tokens
Author: Planview
Latest version: 1.4.0

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

```bash
npm install @planview/pv-tokens
yarn add @planview/pv-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/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:

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

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

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

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

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

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

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

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

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

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

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

```

## For contributors

### Building

```bash
yarn
yarn build
```