Quick Start Guide

Overview

Chassis Tokens is a comprehensive multi-brand design token system that bridges design and development. Create and manage tokens with Tokens Studio, sync to Figma as variables, and transform them into platform-specific code with Style Dictionary.

This guide walks you through setting up the repository, managing tokens, building platform-specific distributions, and integrating them into your applications.

Prerequisites

Before working with Chassis Tokens, ensure you have the following installed and configured:

• Node.js: Version 18 or higher required for running the build scripts
• pnpm: Package manager used by Chassis Tokens (install with npm install -g pnpm)
• Git: For cloning the repository and version control
• Repository Access: Appropriate permissions to clone or fork the Chassis Tokens repository
• Figma & Tokens Studio: (Optional) For creating and managing design tokens

Installation

To get started with Chassis Tokens, you can either clone the repository directly or add it as a Git submodule to your existing project. Choose the approach that best fits your workflow and project structure.

Clone the Repository

Cloning the repository creates a standalone copy that you can use to manage and distribute tokens:

# Clone the repository
git clone https://github.com/chassis-ui/tokens.git chassis-tokens
cd chassis-tokens

Alternatively, for existing projects, you can add it as a Git submodule to keep it synchronized with your main project:

# Add as Git submodule to your project
git submodule add https://github.com/chassis-ui/tokens.git tokens
cd tokens

Install Dependencies

Once the repository is cloned, install the required dependencies for building and distributing tokens:

# Install using pnpm
pnpm install

This installs the Style Dictionary and Tokens Studio SD Transforms plugin along with the necessary packages for the documentation website.

Package Customization

When adopting Chassis Tokens for your organization, customize the package metadata and configuration to match your project structure and requirements.

Change Metadata

Modify the package metadata in package.json to reflect your organization's details:

{
  "name": "@your-org/chassis-tokens",
  "repository": {
    "type": "git",
    "url": "https://github.com/your-org/chassis-tokens.git"
  },
  ...
}

Update Git Remote URL

If you've moved the repository to a different organization or renamed it, update the Git remote URL:

git remote set-url origin https://github.com/your-org/chassis-tokens.git

Configure Build Options

Define your specific brands, themes, and applications in the chassis configuration object within package.json. This determines which outputs the build system generates:

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

See the Style Dictionary documentation for detailed information on configuring brands, apps, and build options.

Token Management

Customize and manage your design tokens to fit your brand and project needs. Chassis Tokens supports a hierarchical structure for token definitions, allowing you to create base tokens and override them for specific brands, themes, or screens.

Token Definitions

Tokens are defined in JSON files within the tokens/ directory. You can edit these files directly or use the Tokens Studio plugin in Figma to manage them visually. See Tokens Studio documentation for instructions on how to create and manage tokens.

Sync with Figma

If you're using Figma and Tokens Studio, you can sync your tokens between Figma and the repository. This allows designers to manage tokens visually while developers maintain the source of truth in code. Refer to the Figma Variables documentation for detailed instructions on setting up and using the sync feature.

Build System

Once your tokens are defined, use the build system to generate platform-specific distributions. The build process uses Style Dictionary to transform tokens into CSS, SCSS, JavaScript, JSON, and platform-specific formats for iOS and Android.

# Generate all tokens
pnpm tokens

# Build for specific brand
pnpm tokens --brand chassis

# Build for specific application
pnpm tokens --app docs

# Build for specific platform
pnpm tokens --platform web

Selective Builds

Use command-line filters to build specific combinations. All filter options accept space-separated values:

# Filter by brand
pnpm tokens --brand chassis example

# Filter by theme
pnpm tokens --theme light dark

# Filter by application
pnpm tokens --app docs demo

# Filter by platform
pnpm tokens --platform web ios android

# Combine multiple filters
pnpm tokens --brand chassis --theme light dark --app docs

CLI Reference

Available command-line options:

• --brand <brands...> — Filter by brand (e.g., chassis example)
• --theme <themes...> — Filter by theme (e.g., light dark)
• --app <apps...> — Filter by app (e.g., docs demo)
• --platform <platforms...> — Filter by platform (e.g., web ios android)
• --dry-run — Preview tasks without executing builds
• --help, -h — Show help message
• --version, -v — Show version number

Build Features:

• Progress indicators show build status ([1/5], [2/5], etc.)
• Build summary displays success/failure count and duration
• Set DEBUG=1 for verbose output with stack traces

Build Output

The build system generates organized output directories for each platform with appropriate formats and naming conventions:

dist/[platform]/[app]/[brand]/
├── main.[ext]            -> Base tokens
├── string.[ext]          -> String tokens
├── color-light.[ext]     -> Light theme colors
├── color-dark.[ext]      -> Dark theme colors
└── number.[ext]          -> Number tokens

The build system uses Style Dictionary with custom transforms and formatters. See the Style Dictionary documentation for details on how the build system works and how to customize it.

Use Tokens in Your Project

After building tokens, you can integrate them into your applications. Tokens can be imported as CSS, SCSS variables, JavaScript modules, or platform-specific formats.

Import Built Tokens

Import tokens directly into your project, or install the package from npm:

# Install from npm
npm install @chassis-ui/tokens

# Or copy built tokens to your project
cp -r dist/css/* /path/to/project/src/styles/

# Create a sync script in your project's package.json
{
  "scripts": {
    "sync-tokens": "cp -r node_modules/@chassis-ui/tokens/dist/css/* src/styles/tokens/"
  }
}

Platform Integrations

Each platform has specific requirements for consuming tokens. Refer to the platform-specific integration guides for detailed instructions, code examples, and best practices:

• Web Applications - Using tokens in web projects (React, Vue, Next.js, etc.)
• iOS Applications - Using Swift constants in iOS
• Android Applications - Using resource XML in Android

Quick Reference

Use this reference for quick access to common information about Chassis Tokens structure and commands.

Directory Structure

Key directories in the Chassis Tokens repository:

Common Commands

Frequently used commands for managing and building tokens:

pnpm install                    # Install dependencies
pnpm tokens                     # Build all tokens
pnpm tokens --brand chassis     # Build specific brand
pnpm tokens --dry-run           # Preview without building
pnpm tokens:test                # Run build tests
pnpm dev                        # Start documentation site

Key Concepts

Fundamental concepts that drive the Chassis Tokens architecture:

• Multi-brand structure: Shared base tokens with brand-specific overrides
• Theme system: Light/dark mode and custom theme support
• Platform-specific builds: Automatic transformation for Web, iOS, Android
• Style Dictionary: Token transformation engine with custom transforms
• Screen tokens: Responsive breakpoint sizes for number tokens (optional)

Next Steps

Continue your journey with Chassis Tokens by exploring these related topics.

Learn the System

Deepen your understanding of Chassis Tokens architecture and principles:

• Token Studio - Understand Chassis Tokens architecture
• Style Dictionary - Learn how the build system works and how to customize it
• Figma Variables - Learn how to sync tokens with Figma and manage them visually

Manage Tokens

Learn how to work with specific token types:

• Colors - Define and manage color tokens
• Typography - Define and manage typography tokens
• Sizing - Define and manage sizing tokens
• Spacing - Define and manage spacing tokens
• Border Width - Define and manage border width tokens
• Border Radius - Define and manage border radius tokens
• Shadow - Define and manage shadow tokens
• Opacity - Define and manage opacity tokens

Use in Projects

Integrate built tokens into your platform-specific applications:

• Web Applications - Integrate into web projects
• iOS Applications - Integrate into iOS projects
• Android Applications - Integrate into Android projects