Quick Start Guide

Introduction

This guide takes the shortest way from nothing to tokens in a project, and there are two of them. To use the tokens as they are published, with the brands of the committed configuration, follow Use the published tokens. To own the tokens, with your brands, themes, apps and platforms, follow Build your own tokens.

Prerequisites

What you need depends on the way you take.

• Web: a project with Sass and a package manager for npm packages.
• iOS: an app that targets iOS 13 or later and uses Swift Package Manager.
• Android: a module with a minimum SDK of 21 or later.
• Your own tokens: Git, Node.js 22 or later and pnpm. The root package.json names the version of pnpm in packageManager, and corepack enable installs it.

Use the published tokens

The published tokens are the files of packages/tokens/dist/ in version 0.6.0, built from the committed configuration: the app docs for the web, and the app demo for iOS and Android, each for the brands chassis and sinefil. The examples use the brand chassis.

Web

The npm package holds the SCSS files of each brand in dist/web/docs/<brand>/. Install it in your project:

npm install @chassis-ui/tokens

Use main.scss with @use and read a token as a variable of the module:

@use '@chassis-ui/tokens/dist/web/docs/chassis/main' as tokens;

.card {
  padding: tokens.$cx-space-context-medium;
}

Sass has to find the packages of node_modules. With the sass command, add --load-path=node_modules.

The web guide covers the other files, the themes and the screen sizes.

iOS

The Swift package holds one library per app and brand, such as ChassisTokensDemoChassis for the app demo and the brand chassis. Add the package https://github.com/chassis-ui/tokens.git to your app with Swift Package Manager, and add the library of your brand to your target.

Use the constants of the types ChassisTokens and ChassisTokensColor:

import ChassisTokensDemoChassis
import UIKit

enum CardStyle {
    static let background: UIColor = ChassisTokensColor.ColorContextDefaultBgMain
    static let padding: CGFloat = ChassisTokens.SpaceContextMedium
}

The colors of ChassisTokensColor follow the light and dark appearance. The iOS guide covers the other types, the screen sizes and the icons.

Android

The Android library holds the resource tree of one brand. Download chassis-tokens-demo-chassis-0.6.0.aar from the GitHub release and copy it to the libs/ folder of your module.

Add the file to the dependencies in the build.gradle.kts of the module:

dependencies {
  implementation(files("libs/chassis-tokens-demo-chassis-0.6.0.aar"))
}

Use the resources in a layout:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout
  xmlns:android="http://schemas.android.com/apk/res/android"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:background="@color/color_context_default_bg_main"
  android:padding="@dimen/space_context_medium" />

The library holds the colors of the dark theme in values-night, so a color follows the night mode of the device. The Android guide covers the resource folders, the screen sizes and the icons.

Build your own tokens

Chassis Tokens is meant to be owned and customized: you fork the repository, change the token sets, name your brands, themes and apps in chassis.build, and build. The token system is built on three core groups, brand, theme and app, and the optional group screen; the introduction describes them. The repository is a pnpm workspace, and every command runs from its root.

Set up the repository

Fork the repository on GitHub, clone your fork and install the dependencies:

git clone https://github.com/<account>/tokens.git chassis-tokens
cd chassis-tokens
pnpm install

To leave out the dependencies of the documentation site, run pnpm install --filter @chassis-ui/tokens in place of pnpm install.

Check the setup with a dry run, which prints the builds and the files of each and writes nothing:

pnpm tokens --dry-run

The plan of the committed configuration starts with the web files of the brand chassis:

  • chassis_docs_light_large
      dist/web/docs/chassis/: main.scss, string.scss, color-light.scss, number-large.scss
  • chassis_docs_dark_large
      dist/web/docs/chassis/: color-dark.scss

Change the tokens

The token sets are the JSON files of packages/tokens/source/, in Tokens Studio format. Edit them in Figma with Tokens Studio, synced to your fork with the file path packages/tokens/source, or edit the JSON files directly. A brand of your own is an option of the brand group with its own token set, as brand-sinefil/brand-base.json is for sinefil. The Tokens Studio guide describes the token sets and the groups.

Lint the token sets before you build:

pnpm tokens:lint:source

The lint names the token set and the token of each mistake that the build would accept, such as a token that one screen declares and another does not.

Configure the build

The build writes only what chassis.build lists. The committed configuration, in chassis.build of packages/tokens/package.json:

"chassis": {
  "build": {
    "brands": ["chassis", "sinefil"],
    "themes": ["light", "dark"],
    "screens": ["large", "medium", "small"],
    "apps": {
      "docs": ["web"],
      "demo": ["ios", "android"]
    }
  }
}

Replace the names with the options of your groups. Without screens, or with "screens": [], the build writes one number file for all screens, and source/$themes.json must have no screen group.

A platform is web, ios, android or a preset: web-scss, web-px and web-vw for a CSS framework other than Chassis CSS, ios-swiftui and android-compose for SwiftUI and Jetpack Compose. The Style Dictionary guide describes every key, platform and preset.

Build

Build the tokens of the configuration:

pnpm tokens

The build writes the files of every app and brand to packages/tokens/dist/<platform>/<app>/<brand>/. Filters build a part of the configuration, and you can combine them:

pnpm tokens --brand chassis --platform web

After a change to the brands or apps of chassis.build, write the manifest of the Swift package again, which has one library for every app and brand with an iOS platform:

pnpm tokens:swift-package

Review what the change does to the token names and values, compared with the main branch, and commit dist/ with your change:

pnpm tokens:diff

Your apps take the files from the folders of dist/: the SCSS files of dist/web/<app>/<brand>/, the Swift files and Icons.xcassets of dist/ios/<app>/<brand>/, and dist/android/<app>/<brand>/res as a resource folder. The platform guides describe each.

Troubleshooting

Stylesheet not found

Sass stops with Error: Can't find stylesheet to import. at the @use rule of the tokens. Sass does not search node_modules by itself. Add --load-path=node_modules to the sass command. For a bundler, see the web guide.

No token sets

The build stops with No token sets for <brand>_<app>_<theme>_<screen> in source/$themes.json, with the names of the list it looked for. chassis.build lists a brand, theme, app or screen that is not an option of its group in packages/tokens/source/$themes.json, or it lists no screens while $themes.json has a screen group. Correct the name in chassis.build, or add the option to the group in Tokens Studio.

Next steps

• The web, iOS and Android guides cover the files, themes and screen sizes of each platform.
• The Tokens Studio guide and the Figma Variables guide cover the token sets and their sync with Figma.
• The Style Dictionary guide is the reference of the build: its options, platforms, presets and files.
• The token categories start with the color tokens and the space tokens.