# @coveord/plasma-tokens

Design tokens of the Plasma Design System extracted from Figma.

#### What is a design token?

Simply put, a design token is a stored design decision. It can be understood as a variable that holds the result of a choice (in this case made in Figma). Decisions can be made about multiple different subjects, for example colors, typography, spacing, etc. Therefore, it is important to consider that design tokens come in as many types as there are design subjects.

#### Objective of this package

Distribute design tokens to all Coveo products that rely on the Plasma Design System through code.

## Installation

```bash
npm install @coveord/plasma-tokens
```

For TypeScript users: the package provides its own type declarations.

## Usage

Tokens are provided through multiple outputs. Choose the format that best suits your needs.

### TypeScript

```ts
import * as PlasmaTokens from '@coveord/plasma-tokens';

PlasmaTokens.color.primary.actionBlue[6]; // '#1372ec'
```

### Sass

```scss
@import '~@coveord/plasma-tokens/scss';
// or individual libraries
@import '~@coveord/plasma-tokens/scss/Colors';

.something {
    background-color: $plasma-color-primary-action-blue-6;
}
```

### CSS

First include the css file you want tokens from in your page.

```html
<link href="/node_modules/@coveord/plasma-tokens/css/Colors.css" rel="stylesheet" />
```

Tokens in CSS are exposed as [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).

```css
.something {
    background-color: var(--plasma-color-primary-action-blue-6);
}
```

### Icons

All icons are located under the `icons` folder in `.svg` format.

If you want to use icons in a React application, refer to [`@coveord/plasma-react-icons`](https://github.com/coveo/plasma/tree/master/packages/react-icons).

## Internal usage

### `tokens:fetch`

Fetches tokens information from our tokens libraries in Figma and outputs the result in JSON format into the `data` folder.

In order to fetch data from our Figma libraries on your local machine, you will need to create a `.env` file for yourself that provides the necessary information for the script to run. The file `.env.example` will help you know where to get the proper values such as the access token.

#### `--libraries`, `-l`

Optional option. Use to target one or more specific tokens libraries. If not specified, all libraries will be fetched. See the [list of available libraries](#available-token-libraries).

example:

```bash
tokens:fetch --libraries Lib1 Lib2
```

### `tokens:build`

Translates the fetched tokens into all the available output formats.

### `tokens:lint`

Runs Prettier on the source files generated by the `tokens:build` command.

> This command is automatically run along with the `tokens:build` command.

### `build`

Builds from the sources files that were generated by the `tokens:build` command the code to be distributed on NPM (creates the `dist` folder).

## Available token libraries

| Library Name | Available Formats     | Description                                                                       |
| ------------ | --------------------- | --------------------------------------------------------------------------------- |
| `Icons`      | svg, typescript       | xml markup of the svg elements of all the icons and their variants.               |
| `Colors`     | typescript, scss, css | Values of the different palettes used throughout plasma, also contains gradients. |