System tokens

Validates and builds design token artifacts that can be consumed by various platforms (palettes and themes).

Brand palette usage

CLI

The easiest way to build a palette is with the CLI command:

1. Install:

   npm install --save-dev @telus-uds/system-tokens

2. Add a npm run script to your package.json (this assumes the palette is located at ./palette.json, if not you can set a path with the PALETTE_PATH env variable):

   {
     // ...
     scripts: {
       "build": "system-tokens-build-palette"
     }
   }

3. Build the palette:

   npm run build

Environment variables

The following variables are used:

| variable | description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | PALETTE_PATH | Path to palette JSON file to build, defaults to palette.json | | AWS_ACCESS_KEY_ID | AWS access, see the docs | | AWS_SECRET_ACCESS_KEY | AWS access, see the docs | | AWS_SESSION_TOKEN | AWS access (optional), see the docs | | AWS_REGION | AWS region, see the docs | | AWS_ASSET_BUCKET | AWS S3 bucket name to upload assets too | | AWS_ASSET_PREFIX | AWS S3 object path prefix, such as path/into/bucket/for/cdn, defaults to an empty string. | | CDN_ASSET_PREFIX | URL to the public facing assets, for example https://my.cdn.com/path/to/assets/. This is prepended to uploaded assets, defaults to an empty string. | | CI | If not set, asset uploading will be skipped |

Variables can be set by the environment or read from .env

Theme usage

Quick start

1. Install as a dev dependency into your UDS theme:

   npm install --dev @telus-uds/system-tokens

2. Add a build script to the UDS theme package.json

   {
     // ...
     "scripts": {
       "build": "UDS_PALETTE=@telus-uds/palette-your-palette system-tokens-build-theme"
     }
   }

   ℹ️ You will probably want to set some env vars also in the build script, see below for details

Configuration

All configuration is done through environment variables.

• UDS_THEME_PATH is the input theme filename to build. Defaults to ./theme.json.
• UDS_THEME_SCHEMA is the theme schema package defining the components and appearances to validate and build the theme for. Defaults to @telus-uds/system-theme-tokens, the schema package for the @telus-uds/components-base.
• UDS_PALETTE is the palette package for resolving theme tokens. Sensible examples are @telus-uds/palette-allium, @telus-uds/palette-koodo, or @telus-uds/palette-public-mobile.

Env vars can be set in the command line or via a .env file.

The theme is always outputted to ./build/theme.js.

Tokens

Icons

Icons are treated differently from other aliases. Any token alias that has icon as at the second level (i.e. *.icon.*), will be treated as an icon.

Icon aliases are expected to resolve to a icon file that can be imported. Icon imports are assumed to importable from an index file, ignoring the filename in the palette.

For example, if a icon alias resolves to the palette key: AddUser: '@telus-uds/palette-allium/build/rn/icons/add-user.icon.svg' the built theme will import AddUser from '@telus-uds/palette-allium/build/rn/icons'.

Fonts

Fonts are treated differently from other aliases. Any token alias that has font at the second level (i.e. *.font.*), will be treated as an font.

Palette fonts are unwrapped to create virtual fontName and fontWeight palette keys. For example, if the palette has the font keys:

{
  font: {
    Times: {
      200: 'path/to/times-200.ttf',
      300: 'path/to/times-300.ttf'
    }
  }
}

The theme build will create the virtual palette keys:

{
  fontName: {
    Times: 'Times'
  },
  fontWeight: {
    200: '200',
    300: '300'
  }
}

Themes should reference fonts by referencing a valid fontName and fontWeight combination. The build will validate that these pairs reference a valid font in the original palette.

Javascript API

A JS API can also be consumed directly.

const buildTheme = require('@telus-uds/system-tokens/theme-build/build')

const options = {
  themeInput: {
    // Your theme input
  },
  tokens: {
    // Token aliases in the theme will be resolved to paths here
    system: {}
    palette: {}
  },
  // Appearances and component token types
  schema: {
    appearances: {},
    components: {}
  }
}

const context = builtTheme(options)

// The build theme
const {themeOutput} = context

Change usage

system-tokens provides a wrapper around beachball to autogenerate change files for brand palettes and themes. When using beachball for package release and publishing, this provides calculated semver version bumps and changelogs by diffing changes to the brand palette and theme.

Quick start

1. Install as a dev dependency along with beachball into your repository that contains brand palettes or themes or both:

   npm install --save --dev @telus-uds/system-tokens beachball

2. Add a change script to package.json (use the root package.json for monorepos)

   {
     // ...
     "scripts": {
       "change": "system-tokens-change"
     }
   }

3. Use the change script add change files 🪄. For packages that don't support automatic semver bump and changes logs (packages not starting with palette- or theme-), beachball will be executed to prompt the user for the change details:

   npm run change

   ℹ️ Change files will be automatically committed to the current branch inside the change folder.

Refer to the UDS monorepo README for details.