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

tl;dr:

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.

More details about tools and configurations in @preply/ds-workspace.

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 to generate TS code
• this awesome tool to generate the factory functions

Generated files

Following the spec in 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.