@battmobility/fleet-design-tokens

A comprehensive design token system for Batt Mobility's Fleet Platform that transforms Figma design decisions into code

Table of Contents

• What Are Design Tokens?
• How This Repository Works
• Repository Structure
• The Token Pipeline Explained
• Token Architecture
• Build System Deep Dive
• Installation
• Usage Guide
• Output Formats Explained
• Development Workflow
• Troubleshooting
• Glossary

What Are Design Tokens?

Design tokens are the smallest pieces of a design system - they store design decisions as data. Think of them as variables that contain visual design attributes like colors, typography, spacing, and more.

Why Use Design Tokens?

1. Single Source of Truth: Define once, use everywhere
2. Platform Agnostic: Same tokens work in CSS, JavaScript, iOS, Android
3. Consistency: Ensures design consistency across all products
4. Maintainability: Change a color in one place, updates everywhere
5. Theming: Easy theme switching (light/dark modes)

Real-World Example

Instead of hardcoding colors:

/* ❌ Without tokens - scattered, hard to maintain */
.button { background: #635bff; }
.header { border-color: #635bff; }
.link { color: #635bff; }

Use design tokens:

/* ✅ With tokens - centralized, easy to maintain */
.button { background: var(--primary-main); }
.header { border-color: var(--primary-main); }
.link { color: var(--primary-main); }

How This Repository Works

This repository is a build pipeline that transforms design tokens from Figma into multiple code formats:

┌─────────────┐      ┌──────────────┐      ┌─────────────┐      ┌──────────┐
│   FIGMA     │ ---> │ TOKEN STUDIO │ ---> │ THIS REPO   │ ---> │   NPM    │
│   Designs   │      │   Plugin     │      │ Build System│      │ Package  │
└─────────────┘      └──────────────┘      └─────────────┘      └──────────┘
      ↓                     ↓                      ↓                   ↓
  Designers           Export JSON            Transform &          Developers
  define colors       token files             Build to            import and use
  & styles                                    multiple            in their apps
                                              formats

The Complete Workflow

1. Design Phase (Figma)

   • Designers create colors, typography, spacing in Figma
   • Token Studio plugin captures these as structured data

2. Export Phase (Token Studio)

   • Exports design decisions as JSON files
   • Maintains relationships between tokens (e.g., "primary color uses blue-500")

3. Transformation Phase (This Repository)

   • token-transformer: Processes Token Studio format into standard format
   • style-dictionary: Transforms tokens into various code formats
   • Custom scripts: Create proper module exports

4. Distribution Phase (NPM)

   • Published as @battmobility/fleet-design-tokens
   • Developers install and use in their projects

Repository Structure

Figma-FleetPlatform/
├── tokens/                      # 🎨 Source design tokens (from Figma)
│   ├── $metadata.json           # Token loading order configuration
│   ├── $themes.json             # Theme definitions (Light/Dark)
│   ├── globals.json             # Base color palettes & scales
│   ├── light/                   # Light theme tokens
│   │   ├── default.json         # Core theme colors
│   │   └── components.json      # Component-specific tokens
│   ├── dark/                    # Dark theme tokens
│   │   ├── default.json         # Core theme colors
│   │   └── components.json      # Component-specific tokens
│   └── brands/                  # Brand-specific overrides
│       └── batt/
│           ├── B2B.json         # Business customer branding
│           └── B2C.json         # Consumer branding
│
├── build-config-base.js         # 🔧 Shared Style Dictionary config
├── build-config-light.js        # Light theme build config
├── build-config-dark.js         # Dark theme build config
├── build-config.js              # Combined themes build (legacy)
├── create-index.js              # Creates main index files
│
├── dist/                        # 📦 Built output (git-ignored)
│   ├── css/                     # CSS variables
│   │   ├── variables.css        # All tokens as CSS vars
│   │   ├── light.css           # Light theme CSS
│   │   └── dark.css            # Dark theme CSS
│   ├── js/                      # JavaScript modules
│   │   ├── index.js            # CommonJS main export
│   │   ├── index.mjs           # ES modules main export
│   │   ├── index.d.ts          # TypeScript definitions
│   │   ├── light.js/mjs/d.ts   # Light theme modules
│   │   └── dark.js/mjs/d.ts    # Dark theme modules
│   ├── scss/                    # Sass variables
│   │   └── _variables.scss
│   └── json/                    # Processed JSON
│       ├── light.json
│       └── dark.json
│
├── package.json                 # Package configuration
├── .github/workflows/           # CI/CD automation
│   ├── ci.yml                  # Build validation
│   └── publish.yml             # Auto-publish to NPM
└── README.md                   # You are here! 📍

The Token Pipeline Explained

Step 1: Raw Tokens (Token Studio Format)

Token Studio exports tokens with special features like references and modifiers:

// tokens/light/default.json
{
  "primary": {
    "main": {
      "value": "{neonBlue.500}",  // Reference to another token
      "type": "color"
    }
  },
  "text": {
    "primary": {
      "value": "{neutral.900}",   // Reference to global token
      "type": "color"
    }
  }
}

Step 2: Token Transformation

The token-transformer tool resolves these references:

# Command that runs during build
token-transformer tokens dist/light.json \
  --sets=globals,light/default,light/components \
  --expandTypography=true

This produces:

// dist/light.json (transformed)
{
  "primary": {
    "main": {
      "value": "#635bff",  // Resolved to actual color
      "type": "color"
    }
  }
}

Step 3: Style Dictionary Processing

Style Dictionary takes the transformed tokens and generates multiple formats:

// How tokens flow through Style Dictionary
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ Transformed  │ --> │ Custom       │ --> │   Output     │
│   Tokens     │     │ Formatters   │     │   Files      │
└──────────────┘     └──────────────┘     └──────────────┘
  light.json          ES6, CSS,            index.mjs
  dark.json           TypeScript,          variables.css
                      SCSS formats         _variables.scss

Step 4: Module Creation

The create-index.js script creates the main entry points:

// Creates dist/js/index.mjs
import lightTheme from './light.mjs';
import darkTheme from './dark.mjs';

export default { light: lightTheme, dark: darkTheme };

Token Architecture

The token system has four layers, each building on the previous:

1️⃣ Global Tokens (Foundation)

Raw color palettes and scales - the building blocks:

// tokens/globals.json
{
  "neonBlue": {
    "500": { "value": "#635bff", "type": "color" },
    "600": { "value": "#4e36f5", "type": "color" }
  },
  "neutral": {
    "900": { "value": "#111827", "type": "color" },
    "100": { "value": "#f3f4f6", "type": "color" }
  }
}

2️⃣ Theme Tokens (Semantic)

Meaningful names that reference global tokens:

// tokens/light/default.json
{
  "primary": {
    "main": { "value": "{neonBlue.500}" },    // Brand color
    "dark": { "value": "{neonBlue.600}" }     // Hover state
  },
  "background": {
    "paper": { "value": "{neutral.100}" }     // Card backgrounds
  }
}

3️⃣ Component Tokens

Specific to UI components:

// tokens/light/components.json
{
  "button": {
    "background": { "value": "{primary.main}" },
    "text": { "value": "{primary.contrast}" }
  }
}

4️⃣ Brand Tokens (Optional)

Override for different brands:

// tokens/brands/batt/B2C.json
{
  "primary": {
    "main": { "value": "{blueRibbon.500}" }  // Different blue for consumers
  }
}

Token Resolution Example

Here's how a button color is resolved:

Button Background Color Resolution:

1. Component token:    button.background = {primary.main}
                             ↓
2. Theme token:        primary.main = {neonBlue.500}
                             ↓
3. Global token:       neonBlue.500 = #635bff
                             ↓
4. Final output:       --button-background: #635bff;

Build System Deep Dive

Why Multiple Build Configs?

The repository uses several build configuration files for different purposes:

build-config-base.js

• Purpose: Shared configuration and custom formatters
• Contains:
  • Custom Style Dictionary transforms
  • ES6/TypeScript/CSS formatters
  • Collision handling for token names
• Used by: Light and dark theme builds

build-config-light.js & build-config-dark.js

• Purpose: Theme-specific builds
• Why separate:
  • Smaller bundle sizes (import only what you need)
  • Clear separation of themes
  • Parallel build processing

Custom Formatters Explained

The build system includes custom formatters for different needs:

ES6 Module Formatter

// Handles name collisions and creates clean exports
StyleDictionary.registerFormat({
  name: 'javascript/es6-default',
  formatter: function({ dictionary }) {
    // Converts token.name.with.dots → tokenNameWithDots
    // Handles collisions: adds _2, _3 suffixes
    // Creates both named and default exports
  }
});

CSS Variables Formatter

// Creates theme-specific CSS
StyleDictionary.registerFormat({
  name: 'css/variables-themed',
  formatter: function({ dictionary, options }) {
    // Outputs: [data-theme="light"] { --token-name: value; }
  }
});

Installation

NPM Installation

# Install the package
npm install @battmobility/fleet-design-tokens

# Or with yarn
yarn add @battmobility/fleet-design-tokens

# Or with pnpm
pnpm add @battmobility/fleet-design-tokens

CDN Usage

For quick prototypes or static sites:

<!-- Latest version -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@battmobility/fleet-design-tokens/dist/css/variables.css">

<!-- Specific version (recommended for production) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@battmobility/[email protected]/dist/css/variables.css">

Usage Guide

JavaScript/TypeScript

Basic Import

// Import all tokens
import tokens from '@battmobility/fleet-design-tokens';

// Use in your code
const primaryColor = tokens.light.primary.main; // "#635bff"
const darkBackground = tokens.dark.background.paper; // "#1a1a1a"

Theme-Specific Imports

// Import only what you need - smaller bundle!
import lightTokens from '@battmobility/fleet-design-tokens/light';
import darkTokens from '@battmobility/fleet-design-tokens/dark';

// TypeScript gets full type safety
const color: string = lightTokens.primary.main;

React Example

import { useState } from 'react';
import tokens from '@battmobility/fleet-design-tokens';
import '@battmobility/fleet-design-tokens/css';

function App() {
  const [theme, setTheme] = useState('light');
  
  // Apply theme to root element
  useEffect(() => {
    document.documentElement.setAttribute('data-theme', theme);
  }, [theme]);
  
  return (
    <div style={{
      backgroundColor: tokens[theme].background.default,
      color: tokens[theme].text.primary
    }}>
      <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
        Toggle Theme
      </button>
    </div>
  );
}

CSS Variables

Basic Usage

/* Tokens are available as CSS custom properties */
.button {
  background-color: var(--primary-main);
  color: var(--primary-contrast);
  border-radius: var(--radius-medium);
}

.button:hover {
  background-color: var(--primary-dark);
}

Theme Switching

<!-- Light theme -->
<html data-theme="light">
  <body>
    <button class="primary-button">Click me</button>
  </body>
</html>

<!-- Dark theme -->
<html data-theme="dark">
  <!-- Same HTML, different colors! -->
</html>

// JavaScript theme switcher
function setTheme(theme) {
  document.documentElement.setAttribute('data-theme', theme);
  localStorage.setItem('theme', theme);
}

// Load saved theme on page load
const savedTheme = localStorage.getItem('theme') || 'light';
setTheme(savedTheme);

Styled Components

import styled from 'styled-components';
import tokens from '@battmobility/fleet-design-tokens';

const Button = styled.button`
  background: ${props => tokens[props.theme].primary.main};
  color: ${props => tokens[props.theme].primary.contrast};
  padding: ${tokens.spacing.medium};
  border-radius: ${tokens.radius.medium};
  
  &:hover {
    background: ${props => tokens[props.theme].primary.dark};
  }
`;

// Usage
<Button theme="light">Light Button</Button>
<Button theme="dark">Dark Button</Button>

Tailwind CSS Integration

// tailwind.config.js
const tokens = require('@battmobility/fleet-design-tokens');

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          main: tokens.light.primary.main,
          dark: tokens.light.primary.dark,
          light: tokens.light.primary.light,
        },
        // ... more colors
      },
    },
  },
};

SCSS/Sass

// Import all variables
@import '@battmobility/fleet-design-tokens/scss';

// Use in your styles
.card {
  background: $background-paper;
  border: 1px solid $border-default;
  box-shadow: $shadow-medium;
  
  .title {
    color: $text-primary;
  }
}

Output Formats Explained

CSS Variables (dist/css/)

• What: CSS custom properties
• When to use: Web applications, runtime theming
• Files:
  • variables.css: All tokens
  • light.css: Light theme with [data-theme="light"]
  • dark.css: Dark theme with [data-theme="dark"]

JavaScript Modules (dist/js/)

• What: ES modules and CommonJS
• When to use: React, Vue, Node.js apps
• Files:
  • .mjs: ES modules (import/export)
  • .js: CommonJS (require)
  • .d.ts: TypeScript definitions

SCSS (dist/scss/)

• What: Sass variables
• When to use: Projects using Sass/SCSS
• Note: Compile-time only, no runtime theming

JSON (dist/json/)

• What: Raw token values
• When to use: Custom build tools, native apps

Development Workflow

Local Development

1. Clone the repository

git clone https://github.com/Battmobility/Figma-FleetPlatform.git
cd Figma-FleetPlatform

2. Install dependencies

npm install

3. Make changes to tokens

# Edit token files in tokens/ directory
vim tokens/light/default.json

4. Build and test

# Build all formats
npm run build

# Check the output
ls -la dist/

5. Test in a project

# Link for local testing
npm link

# In your project
npm link @battmobility/fleet-design-tokens

Adding New Tokens

1. Add to appropriate file:

   • Global colors → tokens/globals.json
   • Theme colors → tokens/[theme]/default.json
   • Component tokens → tokens/[theme]/components.json

2. Follow naming conventions:

{
  "category": {
    "property": {
      "variant": {
        "value": "#value",
        "type": "color",
        "description": "Used for..."
      }
    }
  }
}

3. Build and verify:

npm run build
# Check that your token appears in dist/

Testing Changes

# Run build as a test
npm test

# Validate JSON structure
npx jsonlint tokens/**/*.json

# Check output files
find dist -name "*.css" -exec grep "your-new-token" {} \;

Troubleshooting

Common Issues and Solutions

Tokens not appearing in output

• Check: Token is in correct theme set ($themes.json)
• Verify: Build command includes your token set
• Solution: Check selectedTokenSets in $themes.json

Build fails with "Cannot resolve reference"

• Cause: Token references a non-existent token
• Solution: Check that referenced token exists in globals or same theme

Name collisions in JavaScript output

• Symptom: Tokens with _2, _3 suffixes
• Cause: Multiple tokens resolve to same JavaScript variable name
• Solution: Check build output for collision comments

CSS variables not updating

• Check: Correct theme attribute on HTML element
• Verify: Both CSS files are loaded (variables.css + theme.css)
• Solution: Ensure data-theme attribute matches CSS selector

TypeScript types not found

• Solution: Add to tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Build Commands Reference

# Clean build directory
npm run clean

# Transform tokens (Token Studio → Style Dictionary format)
npm run transform:light
npm run transform:dark
npm run transform:all

# Run Style Dictionary builds
npm run style-dictionary:light
npm run style-dictionary:dark
npm run style-dictionary:all

# Create index files
npm run create-index

# Full build (runs all above)
npm run build

Publishing

Automatic Publishing

The package is automatically published to NPM when:

1. Version in package.json is updated
2. Changes are pushed to main branch
3. CI/CD checks pass

Manual Publishing

# 1. Update version
npm version patch  # 1.0.0 → 1.0.1
npm version minor  # 1.0.0 → 1.1.0
npm version major  # 1.0.0 → 2.0.0

# 2. Build
npm run build

# 3. Publish
npm publish

# 4. Push changes
git push origin main --tags

Glossary

Design Token Terms

Design Token: A named entity that stores a design decision (color, spacing, etc.)

Token Reference: A token that points to another token's value using {token.path} syntax

Token Set: A collection of related tokens (e.g., "light theme" set)

Token Type: The data type (color, dimension, typography, etc.)

Semantic Token: A token with meaning (e.g., primary.main vs blue-500)

Global Token: Base-level token without semantic meaning

Technical Terms

Token Studio: Figma plugin for managing design tokens

Style Dictionary: Amazon's build system for transforming tokens

token-transformer: Tool that converts Token Studio format to Style Dictionary format

Platform: Output target (web, iOS, Android)

Transform: Function that modifies token values during build

Formatter: Function that generates output files in specific formats

CommonJS: Node.js module system using require() and module.exports

ES Modules: Modern JavaScript module system using import and export

Contributing

1. Make changes in Figma using Token Studio plugin
2. Export and commit token JSON files
3. Test locally with npm run build
4. Create pull request
5. CI/CD will validate and auto-publish when merged

Support

For issues or questions:

• GitHub Issues: github.com/Battmobility/Figma-FleetPlatform/issues
• Documentation: This README
• Token Studio Docs: docs.tokens.studio
• Style Dictionary Docs: amzn.github.io/style-dictionary