ADS Design Tokens

• Introduction
• Token Tiers
• Installation
• Usage
• 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 within ADS/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.
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.