npm package: @phase2/sic-tokens
Description: Design Token Library: The Standard
Author: Phase2
Latest version: 0.0.10

# 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

```bash
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

```bash
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](https://www.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:

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

## Primary Dependencies & Tooling

- [style-dictionary](https://github.com/amzn/style-dictionary)
- [token-transformer](https://github.com/tokens-studio/figma-plugin/tree/main/token-transformer)

## 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](https://www.conventionalcommits.org/en/v1.0.0/) via [commitlint](https://commitlint.js.org/) and [husky](https://typicode.github.io/husky).

### Conventional Commits

> The [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) 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:

```text
<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](https://www.conventionalcommits.org/en/v1.0.0/#examples) for more usage information.

## @todo

- Finalize token naming structure in all systems.
- Ensure exports coming from Token Studio are as expected and/or desired.