@conveyorhq/design-tokens

Design tokens are platform-agnostic style values used to ensure consistent experiences across Conveyor products.

This project is using Style Dictionary to transform the design tokens into various formats for each platform.

Installation and usage

There are a variety of formats included and this section details how you can use each one. But first, you will install the package into your project:

yarn add @conveyorhq/design-tokens

JavaScript / TypeScript / ES module

The package exports an ES module by default.

import { tokens } from "@conveyorhq/design-tokens";

If you’re using Visual Studio Code, then the TypeScript intellisense will give you the available variable names after you type tokens. from the included d.ts file.

JavaScript / CommonJS module

If your project requires a CommonJS module, you can import the package as follows:

const tokens = require("@conveyorhq/design-tokens/dist/tokens.cjs");

You may also import single variables like so:

const { color } = require("@conveyorhq/design-tokens/dist/tokens.cjs");

CSS

The design tokens are also available as CSS custom properties. To use the generated CSS file, there are a couple of options.

If your project uses Webpack and is configured with style-loader, then you can just import the file.

import "@conveyorhq/design-tokens/dist/tokens.css";

The other option is to load the CSS in the head of an HTML document.

<link rel="stylesheet" href="https://unpkg.com/@conveyorhq/design-tokens@latest/dist/tokens.css">

In the future, we may want to host tokens.css on our own CDN if there’s a reason to do so.

Tailwind CSS configuration

If your project uses Tailwind CSS, you can install the provided tailwind.config.js into your project’s own config.

const { config } = require("@conveyorhq/design-tokens/dist/tailwind.config");

module.exports = {
  ...config,
  content: ["./path/to/ui/**/*.{jsx,tsx}"],
};

You will need to provide your own content paths. You can also override any configuration as needed, which might look something like this:

module.exports = {
  content: ["./path/to/ui/**/*.{jsx,tsx}"],
  theme: {
    ...config.theme,
    colors: {
      // Project’s custom color palette
    },
  },
  plugins: [
    // Project’s custom Tailwind plugins
  ],
};

You can also build a completely custom Tailwind config by importing the design tokens as a CommonJS module.

// tailwind.config.js
const { color } = require("@conveyorhq/design-tokens/dist/tokens.cjs");

const colors = {
  ...color,
  current: "currentColor",
};

module.exports = {
  config: {
    content: ["./path/to/ui/**/*.{jsx,tsx}"],
    theme: {
      colors,
      // Additional theme variables
    },
  },
};

Upgrading from @conveyorhq/arrow-ds/tokens

Design tokens work the same as they did when they were included with arrow-ds, but some of the token variable names have changed.

Old name (arrow-ds)	New name (design-tokens)
colors	color
lineHeight	leading
screens	screenWidth
boxShadow	shadow
letterSpacing	tracking
fontFamily	type

Contributing

Start by installing all dependencies by running yarn install.

This project requires minimal code compilation which is done automatically every time you make a commit and before publishing to npm (which is also done automatically). However, if you would like to preview the output before committing, you can run yarn run output to build and compile to the dist directory.

Formats

Formats define the file output for each platform. This project is using both pre-defined formats and custom formats. Custom formats provide more control over the file output and can be found in the formats directory.

The current formats include:

• CommonJS
• CSS custom properties
• ES module
• Tailwind config
• Typescript definition file

For more about formats, please see the documentation.

Tokens

The tokens directory is where the actual design token variables exist. These files will get compiled for the platforms defined in the style-dictionary.config.js file.

The token files are expected to be written in a specific format where each attribute is a key-value pair.

You may add your own custom key-value pairs, for example, width tokens include a tailwindId property.

Config

The config file is where the path to the token files is defined and includes instructions on how to format and transform the tokens for each platform’s output file.

The config file is where you would update existing or add new formats and platforms.

Scripts

The following package scripts are available in the project.

• build Builds the output files
• clean Deletes the output files to prepare for a build
• compile Runs Babel on tokens.esm.js; must be ran after build
• output Combines clean, build and compile scripts
• prettier Runs prettier to check code formatting
• prettier:fix Runs prettier --write to try to fix any code formatting violations
• lint Runs eslint to check for problems in code
• lint:fix Runs eslint --fix to try to fix any problems in code
• check: Combines both prettier and lint scripts
• fix: Combines both prettier:fix and lint:fix scripts
• test-publish: An alias for yalc publish

When you run git push, husky runs a pre-commit hook which runs check and output.

Testing a release locally

To test a release locally, you must install yalc globally by running yarn global add yalc.

Then, run yarn run test-publish in this project and in the consuming project, run:

yalc add @conveyorhq/design-tokens
yarn install

Publishing to npm

This project uses semantic-release to automatically build, tag and publish new releases using semantic versioning.

Writing commit messages

To adhere to semantic versioning and ensure the correct version number is created, semantic-release reads the content of each commit message to determine the type of changes made and which version number to increment (major, minor, patch).

Each commit message format must follow the Conventional Commits specification and should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

From the Conventional Commits summary:

The commit contains the following structural elements, to communicate intent to the consumers of your library:

1. fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning).
2. feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning).
3. BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type. types other than fix: and feat: are allowed, for example build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, and others. Additional types are not mandated by the Conventional Commits specification, and have no implicit effect in Semantic Versioning (unless they include a BREAKING CHANGE).