The "Why": Understanding Design Tokens

This section introduces the foundational concepts of design tokens. You'll learn what they are, the significant benefits they bring to a project, and the common types of visual properties they represent. This is the starting point for building a scalable and consistent design system.

What are Design Tokens?

Design tokens are the single source of truth for a design system's visual style. They are named entities that store design decisions—like colors, fonts, or spacing—instead of hard-coded values. For example, instead of using `#007BFF`, you'd use a token like `color-action-primary`. If the brand color changes, you only update the token, and the change propagates everywhere.

Core Benefits

  • ✓ Consistency: Ensures a uniform visual appearance across all platforms (web, iOS, Android).
  • ✓ Efficiency: Drastically simplifies maintenance. Update a style once, and it changes everywhere.
  • ✓ Collaboration: Creates a shared language between designers and developers.
  • ✓ Scalability: Provides a robust framework that supports product growth without losing visual coherence.

How to Use Cssman CLI

Get started quickly with the Cssman Command Line Interface. Follow these steps to install, initialize, and build your design tokens.

1. Installation

Install `cssman-cli` globally or as a project dependency using npm or yarn:

# Using npm
npm install -g cssman-cli

# Using yarn
yarn global add cssman-cli

# For local project usage
npm install --save-dev cssman-cli
yarn add --dev cssman-cli

2. Initialize Configuration

Generate a configuration file in your project root:

cssman init

This creates a `cssman.config.js` file. You'll need to define your style sources in this file. Here's a simple example:

// cssman.config.js (example)
module.exports = {
  source: ['./styles/tokens.json'], // Path to your token definitions
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'dist/css/',
      files: [{
        destination: 'variables.css',
        format: 'css/variables'
      }]
    },
    // Add other platforms like scss, js, android, ios etc.
  }
};

3. Build Your Tokens

Generate your design tokens based on the configuration:

cssman build

Your generated tokens will typically be placed in the `dist/` directory, or as specified in your configuration.

Other Useful Commands

Clean previous builds:

cssman clean

Get help:

cssman --help

The "How": Library Architecture Explorer

A well-designed token library functions as a pipeline. This interactive diagram visualizes the core modules and the flow of data from raw input to consumable output. Click on any module to learn more about its specific role and the key technologies involved in its implementation.

Input Adapters
(CSS, Figma, Miro)
Parsing Engine
(Data to AST/Object)
↓
Output Formatters
(JSON, CSS, etc.)
Transformation Engine
(Normalize & Unify)

Configuration Manager & CLI/API Layer

Orchestrates the entire process based on user settings.

The "From Where": Input Source Comparator

The quality of your design tokens depends heavily on the source. Not all inputs are created equal. Use this comparator to understand the pros, cons, and characteristics of each potential source. Select a source to see its analysis and visual rating chart.

The "What It Becomes": Token System Designer

Once data is extracted, it must be organized into a coherent system. This involves a clear naming convention and a logical hierarchy. Use the tools below to understand how raw values are transformed into a structured, semantic system that is easy for developers to use.

Interactive Token Namer

Build a token name using the CTI (Category-Type-Item) convention to see how a structured name communicates a token's purpose.

Generated Token Name:

Token Hierarchy

A tiered hierarchy separates raw values from their semantic purpose, making the system flexible and maintainable.

1. Primitive Tokens

Raw, context-agnostic values from your palette.

color-blue-500: #007BFF;
↓

2. Semantic Tokens

Give purpose to primitives by creating an alias.

color-text-interactive: {color-blue-500};
↓

3. Component Tokens (Optional)

Scope tokens to a specific component for overrides.

button-primary-text-color: {color-text-interactive};

The "What You Get": Output Formatter Showcase

The final step is to generate files that developers can use. The library must serialize the unified tokens into various formats for different platforms. Select a format below to see an example of the final output file.

The "Build It Right": Developer Best Practices

Building a Node.js library for other developers requires discipline. Following best practices ensures your tool is reliable, maintainable, and easy to use. Use this checklist to guide your development process.

  • ✓
    Use a modular project structure (e.g., /src, /parsers, /formatters).
  • ✓
    Manage `dependencies` vs. `devDependencies` correctly in `package.json`.
  • ✓
    Handle all async operations with `async/await` and robust `try...catch` blocks.
  • ✓
    Implement comprehensive unit and integration tests (e.g., with Jest).
  • ✓
    Provide clear API documentation (JSDoc/TSDoc) and a thorough README.
  • ✓
    Use Semantic Versioning (SemVer) to communicate changes.