npm package: @preply/ds-tokens
Description: > Source of truth for design tokens (+ code generators).
Latest version: 0.17.0

# `@preply/ds-tokens`

> Source of truth for design tokens (+ code generators).

## Using the Design System in your application or library?

Follow the instructions in [@preply/ds-workspace](../../README.md).

**tl;dr:**

```tsx
import { tokens } from `@preply/ds-core`;
import { useToken } from `@preply/ds-web-core`;

const color = useToken(tokens...);
```

## Development

You probably want to execute `yarn dev` and/or `yarn docs` in the root, as per instructions in [@preply/ds-workspace](../../README.md).

More details about tools and configurations in [@preply/ds-workspace](../../README.md).

## Authoring

- `yarn build` - validates and builds themes
- `yarn dev` - validates and builds every time a data file is modified
- `yarn resolve` - get help with one token
  - `yarn resolve preply-ui action.variant.primary.color invert`

### Data files

Source of truth for tokens, types, themes, is stored in `data/`.

- `tokens.json` defines which tokens should exist in themes using patterns such as `palette.*.*.color`
- `options.json` defines which options go into those `*` placeholders, and which ones should exist as a type in `@preply/ds-core`
- `themes.json` declares which themes exist in the system (and the dependencies between them)
- `schemes.json` declares which color schemes exist in the system

## How it works

### Code generation

We are using:

- [typescript factory API](https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API) to generate TS code
- [this awesome tool](https://ts-ast-viewer.com/) to generate the factory functions

### Generated files

Following the spec in [Token System](https://preply.atlassian.net/wiki/spaces/DS/pages/3114827841/Token+System):

- @preply/ds-tokens
  - dist/metadata.json
- @preply/ds-core
  - src/generated/tokens.ts
- @preply/ds-web-core
  - src/generated/tokens.less
- @preply/ds-web-root
  - src/generated/themes.ts
  - src/generated/themes.module.less
- @preply/ds-theme-\*
  - src/generated/web/constants.ts
  - src/generated/web/theme.module.less

### Troubleshooting

Search for `* FILE` to locate the function responsible for each generated file.

All functions are documented with a sample of the generated code.

### Validation rules (WIP)

The following validations will be implemented progressively, not with the first version of this package.

#### Options

- no repeated patterns
- for each pattern
  - no repeated types
  - no repeated defaults
  - no repeated option ids

#### Schemes

- for each scheme
  - for each scheme.extends
    - value must exist in schemes.items

#### Tokens

- validate id collisions

#### Themes

- for each theme
  - for each theme.extends
    - [ ] value must exist in themes.items
    - for each token in theme
      - [x] token needs to exist
      - [x] data must match the expected format depending on scheme true/false
      - [ ] if value is `{reference}` it must be a valid token name
      - if color scheme
        - for each "base" color scheme
          - [x] value must be provided
  - if theme is a "base" theme (does not extend other themes)
    - for each token in expanded tokens
      - [x] theme must implement token

## Dependencies

This packages is essentially a `Node.js` build-time package that generate codes therefore it depends on:

- typescript - uses its `factory` API to generate TS code.
- chokidar, lodash, etc..

**Note:** This package could theoretically use some of the types from `@preply/ds-core` but we don't want to add that dependency because this tool is responsible for generating some of the type files in there.

### Dev dependencies

Relies on `ts-node` for executing TS in Node.js.