Project Setup

Learn how to set up and use the Design Tokens Visualizer to explore design system tokens and their relationships

What is This Project?

The Design Tokens Visualizer is an interactive tool for exploring design tokens from various design systems. It provides:

  • Visual relationship mapping between tokens and components
  • Interactive flow diagrams showing token dependencies
  • Component-based token exploration to see which tokens are used where
  • Token search and filtering to quickly find specific tokens

Currently supports: Carbon Design System, Salesforce Lightning Design System (SLDS), and Stellar Design System.

Prerequisites

Before you begin, ensure you have:

  • Node.js (v18 or higher)
  • npm (comes with Node.js)

Installation

Clone the repository and install dependencies:

git clone <repository-url>
cd design-tokens-visualizer
npm install

Running the Project

Start the development server:

npm run dev

Open http://localhost:3000 in your browser to see the application.

The page will automatically reload when you make changes to the code.

Using the Visualizer

Navigating the Interface

The application provides two main ways to explore design tokens:

1. Browse by Design System

Navigate to any of the supported design systems:

  • /design-systems/carbon - Carbon Design System tokens
  • /design-systems/slds - Salesforce Lightning Design System tokens
  • /design-systems/stellar - Stellar Design System tokens

Each design system page shows a complete interactive flow diagram of all tokens and components.

2. Search for Tokens

Use the search functionality (available on each design system page) to:

  • Search by token name - Find specific tokens like --cds-layer or --slds-color-background
  • Filter by component - See all tokens used in a specific component
  • View relationships - Explore how tokens reference each other

Understanding the Visualization

Node Types

The flow diagram displays two types of nodes:

  • Token Nodes - Design tokens (CSS custom properties like --token-name)
  • Component Nodes - CSS classes or components that use tokens (like cds--btn)

Relationships

Lines between nodes show:

  • Token → Token - One token references another (alias relationships)
  • Token → Component - A token is used in a component

Interacting with the Diagram

  • Pan - Click and drag the background to move around
  • Zoom - Use mouse wheel or pinch gesture to zoom in/out
  • Select nodes - Click on tokens or components to highlight relationships
  • Collapse/Expand - Use the toggle controls to show/hide specific node types

Project Structure

design-tokens-visualizer/
├── app/
│   ├── design-systems/     # Design system pages
│   │   ├── carbon/
│   │   ├── slds/
│   │   └── stellar/
│   └── getting-started/    # Documentation pages
├── assets/                 # JSON token files
│   ├── carbon-design-tokens.json
│   ├── slds-design-tokens.json
│   └── stellar-design-tokens.json
├── components/
│   ├── flow/              # Flow visualization components
│   └── ui/                # Reusable UI components
└── lib/
    ├── design-tokens-service.ts  # Server-side token service
    └── types/             # TypeScript type definitions

Adding Your Own Design System

To add a new design system to the visualizer:

Step 1: Extract Tokens

Use css-token-extractor to generate a JSON file from your CSS:

css-token-extractor \
  --input ./your-design-system.css \
  --output ./your-system-tokens.json

See the Extracting Tokens Guide for detailed instructions.

Step 2: Add JSON to Assets

Place your generated JSON file in the assets/ directory:

cp your-system-tokens.json ./assets/

Step 3: Update the Service

Add your design system to lib/design-tokens-service.ts:

const FILE_MAP: Record<string, string> = {
  carbon: 'carbon-design-tokens.json',
  slds: 'slds-design-tokens.json',
  stellar: 'stellar-design-tokens.json',
  'your-system': 'your-system-tokens.json', // Add this line
};

Step 4: Create a Route

Create a new page at app/design-systems/your-system/page.tsx:

import DesignSystemFlow from "@/components/flow/design-system-flow";

export default function YourSystemPage() {
  return <DesignSystemFlow designSystem="your-system" />;
}

Step 5: Add to Navigation (Optional)

Update the sidebar navigation in components/app-sidebar.tsx to include your new design system.

Building for Production

To create a production build:

npm run build

To start the production server:

npm start

Troubleshooting

Port Already in Use

If port 3000 is already in use, you can specify a different port:

PORT=3001 npm run dev

Missing Dependencies

If you encounter module errors, try reinstalling dependencies:

rm -rf node_modules package-lock.json
npm install

Turbopack Errors

If you experience issues with Turbopack, you can disable it:

npm run dev -- --no-turbopack

Next Steps

  • Extract Your Tokens - Learn how to extract tokens from your design system
  • Explore Examples - Browse the existing design systems to see how tokens are structured
  • Customize - Modify the visualization to fit your needs

Tech Stack

This project is built with: