@phase2/sic-tokens NPM

Design Token Library

This is a source of truth for design tokens for The Standard.

Developer Workflow

Basic workflow for token management and updating.

Installation

git clone git@github.com:phase2/sic-tokens.git
cd sic-tokens
yarn install

Updating Tokens

Update appropriate tokens in the tokens/SET directory.
- Initially, only the tokens/default set is included.
- Tokens are split into multiple files. The files are numbered simply to demonstrate the cascade order we define.
  - 01-global.json
  - 02-alias.json
  - 03-component.json
Ensure npm scripts are correct for any sets being processed and published.
- The scripts are intentionally hard coded to process the tokens/default directory only. If more theme sets are added, the NPM scripts in package.json will need to be adjusted accordingly.

Building Token Definitions

yarn build

Scripts

yarn build:token-transformer:default - Runs the token-transformer library against the tokens/default directory with the following flags, creating an output file at dist/tokens.default.json.
- --expandTypography=true
- --expandShadow=true
- --expandComposition=true
yarn build:style-dictionary - Runs the style-dictionary library against any outputs defined in config.json.

Releases

By default, the system is set up for a manual release process. An account on npmjs.com authorized to publish to the @phase2 namespace.

Commit or pull changes
- feat(release): Release version X.X.X.
npm login
Update version number in package.json
yarn package

Integration

The following describes how to integrate the token library into your application.

`.npmrc`

Applications consuming the Design Token Library may need an .npmrc file with the following information:

@phase2:registry=https://registry.npmjs.org

Primary Dependencies & Tooling

Samples

The following samples are included in the primary repository to demonstrate basic usage of the tooling.

Simple

The samples/simple directory contains the most basic implementation to demonstrate the usage of the design token library. To test out the system, the following steps should work:

Workflow

Ensure you have a proper token setup as described in the Access Token section above.
cd samples/simple
npm install - Ensure everything installs with zero errors.
npx serve . - Creates a localhost server to demonstrate working implementation of tokens from @phase2/sic-tokens package.

Files of note

The following files show various portions of the implementation.

samples/simple/index.html - Basic markup and inclusion of various CSS files.
samples/simple/node_modules/@phase2/sic-tokens/dist/tokens.default.css - The generated tokens file from the @phase2/sic-tokens package.
samples/simple/styles.css - Basic CSS using standard CSS as well as integrating variables from tokens.default.css.

Caveats

What this samples/simple demo does NOT show is the process that must be included to properly rsync the tokens.default.css file from node_modules to a location more suited for the application implementing the package. This could be done via a postinstall / postupdate script or multiple other means.

Semantic Versioning

This feature is currently not tied into an automated release process.

In order that the design token library can maintain semantic versioning, and provide stable releases to various applications, this system is set to use Conventional Commits via commitlint and husky.

Conventional Commits

The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

The commit message should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit messages are in the form: type(tag): message.

Types include

fix: Fix - (this correlates with PATCH release in Semantic Versioning)
feat: Feature - (this correlates with MINOR release in Semantic Versioning)
BREAKING CHANGE: A commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (this correlates with a MAJOR release in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.
chore or something else: Ignored

When code is merged, tooling will create a new package version with the major.feature.fix semantic versioning.

For example, if you add a few commit messages:

feat(colors): Updated the colors for the base set.
feat: Updated configuration for a thing to be better.
fix: Fixed the first thing I did.

If you had a version 1.2.3, this would create a new version 1.3.0 since there is a new feature. It only increments once even though there are multiple commits.

See the examples for more usage information.