Overview

Chassis Tokens uses a robust build system to transform design tokens (from JSON or Figma variables) into platform-ready assets (SCSS, CSS, iOS, Android, etc.). The process is highly configurable, supporting multiple brands, themes, apps, and screens.

1. Source of Truth

• Tokens are defined in JSON files under the tokens/ directory.
• Each token set can represent a brand, theme, app, or screen size.
• $themes.json describes all available theme permutations.

2. Build Orchestration

• The main build script is build/tokens/build.js.
• It uses Style Dictionary and @tokens-studio/sd-transforms for transformation logic.
• The build can be filtered by CLI parameters:
  pnpm tokens --brand=chassis --theme=light --app=docs --screen=large
  

3. Task Generation

• The build script generates a list of transformation tasks for all combinations of:
  • Brand (e.g., chassis)
  • Theme (e.g., light, dark)
  • App (e.g., docs)
  • Screen (e.g., small, large)
• Each task defines:
  • The source token files
  • The output platform (web, iOS, Android, etc.)
  • The output file(s) and format(s)

4. Transformation Steps

1. Preprocessing Custom preprocessors (e.g., cx/global) can modify tokens before transformation.
2. Filtering Only relevant tokens for the current brand/theme/app/screen are included.
3. Transforms Custom and standard transforms (e.g., color conversion, size scaling) are applied.
4. Formatting Output files are generated in the required format (SCSS variables, CSS custom properties, Swift, XML, etc.).
5. File Headers Each output file includes a standard header with version and license info.

5. Output

• Web: SCSS/CSS files in icons/package/ and build/
• iOS: Swift files
• Android: XML files
• Other platforms as configured

6. Customization

• Add new brands/themes/apps/screens by editing package.json and tokens/$themes.json.
• Add new transforms/filters/formats in build/tokens/transforms.js, filters.js, and formats.js.
• Configure output in build/tokens/config.js.

7. Example: Adding a New Theme

1. Add the theme to package.json under chassis.build.themes.
2. Add the theme permutation to tokens/$themes.json.
3. Add or update token files in tokens/.
4. Run the build:
   pnpm tokens --theme=newtheme
   

8. CLI Usage

• Build all tokens: pnpm tokens
• Build for a specific brand/theme/app/screen: pnpm tokens --brand=chassis --theme=dark --app=docs --screen=large

9. Extending the System

• Add new output platforms by updating config.js and providing new formatters.
• Integrate with Figma/Token Studio by updating token import scripts.

10. Troubleshooting

• Deprecation warnings: See the build output and update your tokens or config as needed.
• Custom transforms/filters: Ensure they are registered in the build script.

References

• Style Dictionary Documentation
• Tokens Studio SD Transforms
• Chassis Tokens GitHub

For more details, see the source code in build/tokens/ and the README in the project root.