npm package: @srsa/ads-design-tokens
Description: Tokens for the Acquiom Design System
Latest version: 0.0.2

# ADS Design Tokens

- [Introduction](#introduction)
- [Token Tiers](#token-tiers)
- [Installation](#installation)
- [Usage](#usage)
- [Releasing](#releasing)


## Introduction

Design tokens represent the repeated decisions which make up the **Acquiom Design System** (ADS). Tokens replace static values with semantic references. They are generated in Figma using [Tokens Studio](https://tokens.studio/) within [ADS/Foundation](https://www.figma.com/file/CkDnYBE4XE5hBjJxSGhphM/ADS-%2F-Foundation). In general, tokens are namespaced using the following convention:

```
$type.category/element.property.variant.state.scale
```

## Token Tiers

### Core

This tier holds all of the hard-coded values for our most foundational design elements including color swatches, font families, and effects. All other tiers hold references to these tokens.

#### Examples

|Token                           |Value            |
|--------------------------------|-----------------|
|`$core.color.Swatch.Neutral.900`|`#1a1a1a`        |
|`$core.font-family.Display`     |`FreightDisp Pro`|

### Semantic

This tier holds universal named references to *Core* tokens for things like primary text colors and heading styles.

#### Examples

|Token                                   |Value                    |
|----------------------------------------|-------------------------|
|`$semantic.color.Connotation.Success`   |`{color.Swatch.Teal.700}`|
|`$semantic.typography.Desktop.Heading.1`|`{"fontFamily": "{font-family.Display}","fontWeight": "{font-weight.Display.Medium}","lineHeight": "{line-height.Heading.XXL}","fontSize": "{font-size.Heading.XXL}"}`       |

### Light

This tier holds semantic references unique to light themes. For every token in this tier, there is a matching *Dark* token.

#### Examples

|Token                                  |Value                       |
|---------------------------------------|----------------------------|
|`$light.color.Light.Background.Surface`|`{color.Swatch.Neutral.0}`  |
|`$light.color.Light.Text.Secondary`    |`{color.Swatch.Neutral.600}`|

### Dark

This tier holds semantic references unique to light themes. For every token, there is a matching *Light* token.

#### Examples

|Token                                |Value                       |
|-------------------------------------|----------------------------|
|`$dark.color.Dark.Background.Surface`|`{color.Swatch.Neutral.900}`|
|`$dark.color.Dark.Text.Secondary`    |`{color.Swatch.Neutral.300}`|

## Installation

This project is published as an NPM package to GitHub packages.

### Installation Process

Using the package name `@srsa/ads-design-tokens`, follow your normal process for installing new NPM packages such as:

- `npm install @srsa/ads-design-tokens`
- `yarn add @srsa/ads-design-tokens`

## Usage

Stylesheets are provided in both **CSS** and **SCSS** variants depending on your use-case. The static files reside in the `output/css` and `output/scss` directories respectively.

For projects using a preprocessor, like Webpack, these files can be included with an import statement omitting the `output` directory such as:

- SCSS: `@import '@srsa/ads-design-tokens/scss/_variables.scss;`
- JavaScript: `import '@srsa/ads-design-tokens/css/_variables.css';`

For projects with tooling unable to use the export paths, like PostCSS, the full path on disk must be used:

- `@import '@srsa/ads-design-tokens/output/css/_variables.css';`

## Releasing

Releases are managed via the GitHub Releases feature and automatically published to GitHub Packages using an action triggered by the release's `published` event. We use release tags to automatically version the project. Make sure your release number takes semantic versioning into account, is in the format `vX.X.X`, and doesn't conflict with a prior version number.

### Release Process

1. Create a new release from the [Releases Page](https://github.com/onehub/ads-design-tokens/releases/new).
2. Choose a new tag for release (such as `v1.2.3`) targetting the `main` branch.
3. Enter the version tag as the title of the release.
4. Add a description of the release. Specific changes beyond those included in the description can be listed under a "What's Changed" heading. The **Generate release notes** button can be used as a starting point and will pre-populate the description with pull request details since the last release.
5. Choose **Set as the latest release**. Releases can be saved as drafts, but new packages won't be built or published unless it is a "latest" or "pre-release". When publishing a pre-release, be sure to append a *beta* or *alpha* designation to your release tag like `v1.2.3-beta.1` to ensure it doesn't conflict with the stable release's version number.
6. Click **Publish release**.

A GitHub action will be triggered that creates and publishes a package with the version number specified.