{"_id":"@battmobility/fleet-design-tokens","_rev":"3-dbec5f5f44b12492389827e1f97cf9c3","name":"@battmobility/fleet-design-tokens","dist-tags":{"latest":"1.0.7"},"versions":{"1.0.5":{"name":"@battmobility/fleet-design-tokens","version":"1.0.5","keywords":["design-tokens","design-system","figma","tokens","batt-mobility","fleet-platform"],"author":{"name":"Batt Mobility"},"license":"MIT","_id":"@battmobility/fleet-design-tokens@1.0.5","maintainers":[{"name":"tijldeclerck","email":"tijl.declerck7@gmail.com"}],"homepage":"https://github.com/Battmobility/Figma-FleetPlatform#readme","bugs":{"url":"https://github.com/Battmobility/Figma-FleetPlatform/issues"},"dist":{"shasum":"c5f08475e76b219165420b195421658722abeefe","tarball":"https://registry.npmjs.org/@battmobility/fleet-design-tokens/-/fleet-design-tokens-1.0.5.tgz","fileCount":59,"integrity":"sha512-t2EfGXJj/GZ57NTFT47/4DF8tri2IHfNPrZeEMCDWhwzFfSPYaAa1Io3He3OrzFb6wzxjQUW3BVGIcZ0j7xIig==","signatures":[{"sig":"MEQCIGCksYaw9haoA7Qk+Oloej65/GnoduowpiwZziYQOfhIAiAWOemrwYO9QaoNaBmBOhf0Rtz+hGUb4517sV6w5JncZA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4120532},"main":"dist/js/index.js","style":"dist/css/variables.css","types":"dist/js/index.d.ts","module":"dist/js/index.mjs","exports":{".":{"types":"./dist/js/index.d.ts","import":"./dist/js/index.mjs","default":"./dist/js/index.mjs","require":"./dist/js/index.js"},"./css":{"default":"./dist/css/variables.css"},"./raw":{"default":"./tokens"},"./dark":{"types":"./dist/js/dark.d.ts","import":"./dist/js/dark.mjs","default":"./dist/js/dark.mjs","require":"./dist/js/dark.js"},"./scss":{"default":"./dist/scss/_variables.scss"},"./light":{"types":"./dist/js/light.d.ts","import":"./dist/js/light.mjs","default":"./dist/js/light.mjs","require":"./dist/js/light.js"},"./globals":{"types":"./dist/js/globals.d.ts","import":"./dist/js/globals.mjs","default":"./dist/js/globals.mjs","require":"./dist/js/globals.js"},"./css/dark":{"default":"./dist/css/dark.css"},"./css/light":{"default":"./dist/css/light.css"},"./json/dark":{"default":"./dist/json/dark.json"},"./json/light":{"default":"./dist/json/light.json"},"./json/globals":{"default":"./dist/json/globals.json"},"./brands/b2b-dark":{"types":"./dist/js/brands/b2b-dark.d.ts","import":"./dist/js/brands/b2b-dark.mjs","default":"./dist/js/brands/b2b-dark.mjs","require":"./dist/js/brands/b2b-dark.js"},"./brands/b2c-dark":{"types":"./dist/js/brands/b2c-dark.d.ts","import":"./dist/js/brands/b2c-dark.mjs","default":"./dist/js/brands/b2c-dark.mjs","require":"./dist/js/brands/b2c-dark.js"},"./brands/b2b-light":{"types":"./dist/js/brands/b2b-light.d.ts","import":"./dist/js/brands/b2b-light.mjs","default":"./dist/js/brands/b2b-light.mjs","require":"./dist/js/brands/b2b-light.js"},"./brands/b2c-light":{"types":"./dist/js/brands/b2c-light.d.ts","import":"./dist/js/brands/b2c-light.mjs","default":"./dist/js/brands/b2c-light.mjs","require":"./dist/js/brands/b2c-light.js"},"./css/brands/b2b-dark":{"default":"./dist/css/brands/b2b-dark.css"},"./css/brands/b2c-dark":{"default":"./dist/css/brands/b2c-dark.css"},"./css/brands/b2b-light":{"default":"./dist/css/brands/b2b-light.css"},"./css/brands/b2c-light":{"default":"./dist/css/brands/b2c-light.css"}},"gitHead":"fa4e0e6419a7d9c9e10c1f73ac0bf8a88015be5a","scripts":{"test":"npm run build","build":"npm run clean && npm run transform:all && npm run style-dictionary:all && npm run create-index","clean":"rm -rf dist","create-index":"node ./create-index.js","mkdir-brands":"mkdir -p dist/brands","transform:all":"npm run transform:globals && npm run transform:light && npm run transform:dark && npm run transform:brands","prepublishOnly":"npm run build","transform:dark":"token-transformer tokens dist/dark.json --sets=globals,dark/default,dark/components --expandTypography=true --expandShadow=true --expandComposition=true --expandBorder=true","transform:light":"token-transformer tokens dist/light.json --sets=globals,light/default,light/components --expandTypography=true --expandShadow=true --expandComposition=true --expandBorder=true","transform:brands":"npm run mkdir-brands && npm run transform:b2b-light && npm run transform:b2b-dark && npm run transform:b2c-light && npm run transform:b2c-dark","transform:globals":"token-transformer tokens dist/globals.json --sets=globals --expandTypography=true --expandShadow=true --expandComposition=true --expandBorder=true","transform:b2b-dark":"token-transformer tokens dist/brands/b2b-dark.json --sets=globals,dark/default,dark/components,brands/batt/B2B --expandTypography=true --expandShadow=true --expandComposition=true --expandBorder=true","transform:b2c-dark":"token-transformer tokens dist/brands/b2c-dark.json --sets=globals,dark/default,dark/components,brands/batt/B2C --expandTypography=true --expandShadow=true --expandComposition=true --expandBorder=true","transform:b2b-light":"token-transformer tokens dist/brands/b2b-light.json --sets=globals,light/default,light/components,brands/batt/B2B --expandTypography=true --expandShadow=true --expandComposition=true --expandBorder=true","transform:b2c-light":"token-transformer tokens dist/brands/b2c-light.json --sets=globals,light/default,light/components,brands/batt/B2C --expandTypography=true --expandShadow=true --expandComposition=true --expandBorder=true","style-dictionary:all":"npm run style-dictionary:globals && npm run style-dictionary:light && npm run style-dictionary:dark && npm run style-dictionary:brands","style-dictionary:dark":"style-dictionary build --config ./build-config-dark.js","style-dictionary:light":"style-dictionary build --config ./build-config-light.js","style-dictionary:brands":"npm run style-dictionary:b2b-light && npm run style-dictionary:b2b-dark && npm run style-dictionary:b2c-light && npm run style-dictionary:b2c-dark","style-dictionary:globals":"style-dictionary build --config ./build-config-globals.js","style-dictionary:b2b-dark":"style-dictionary build --config ./build-config-b2b-dark.js","style-dictionary:b2c-dark":"style-dictionary build --config ./build-config-b2c-dark.js","style-dictionary:b2b-light":"style-dictionary build --config ./build-config-b2b-light.js","style-dictionary:b2c-light":"style-dictionary build --config ./build-config-b2c-light.js"},"_npmUser":{"name":"tijldeclerck","email":"tijl.declerck7@gmail.com"},"repository":{"url":"git+https://github.com/Battmobility/Figma-FleetPlatform.git","type":"git"},"_npmVersion":"10.9.2","description":"Design tokens for Batt Mobility's Fleet Platform","directories":{},"sideEffects":false,"_nodeVersion":"22.13.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"style-dictionary":"^3.9.2","token-transformer":"^0.0.33"},"_npmOperationalInternal":{"tmp":"tmp/fleet-design-tokens_1.0.5_1756358490646_0.4372317971056363","host":"s3://npm-registry-packages-npm-production"}},"1.0.7":{"name":"@battmobility/fleet-design-tokens","version":"1.0.7","description":"Design tokens for Batt Mobility's Fleet Platform","main":"dist/js/index.js","module":"dist/js/index.mjs","types":"dist/js/index.d.ts","style":"dist/css/variables.css","sideEffects":false,"exports":{".":{"types":"./dist/js/index.d.ts","import":"./dist/js/index.mjs","require":"./dist/js/index.js","default":"./dist/js/index.mjs"},"./globals":{"types":"./dist/js/globals.d.ts","import":"./dist/js/globals.mjs","require":"./dist/js/globals.js","default":"./dist/js/globals.mjs"},"./light":{"types":"./dist/js/light.d.ts","import":"./dist/js/light.mjs","require":"./dist/js/light.js","default":"./dist/js/light.mjs"},"./dark":{"types":"./dist/js/dark.d.ts","import":"./dist/js/dark.mjs","require":"./dist/js/dark.js","default":"./dist/js/dark.mjs"},"./css":{"default":"./dist/css/variables.css"},"./css/light":{"default":"./dist/css/light.css"},"./css/dark":{"default":"./dist/css/dark.css"},"./scss":{"default":"./dist/scss/_variables.scss"},"./json/globals":{"default":"./dist/json/globals.json"},"./json/light":{"default":"./dist/json/light.json"},"./json/dark":{"default":"./dist/json/dark.json"},"./raw":{"default":"./tokens"},"./brands/*":{"types":"./dist/js/brands/*.d.ts","import":"./dist/js/brands/*.mjs","require":"./dist/js/brands/*.js","default":"./dist/js/brands/*.mjs"},"./css/brands/*":{"default":"./dist/css/brands/*.css"},"./json/brands/*":{"default":"./dist/json/brands/*.json"}},"scripts":{"build":"npm run clean && npm run transform:all && npm run style-dictionary:all && npm run create-index","clean":"rm -rf dist","mkdir-brands":"mkdir -p dist/brands","transform:globals":"token-transformer tokens dist/globals.json --sets=globals --expandTypography=true --expandShadow=true --expandComposition=true --expandBorder=true","transform:light":"token-transformer tokens dist/light.json --sets=globals,light/default,light/components --expandTypography=true --expandShadow=true --expandComposition=true --expandBorder=true","transform:dark":"token-transformer tokens dist/dark.json --sets=globals,dark/default,dark/components --expandTypography=true --expandShadow=true --expandComposition=true --expandBorder=true","transform:brands":"node build-brands.js transform","transform:all":"npm run transform:globals && npm run transform:light && npm run transform:dark && npm run transform:brands","style-dictionary:globals":"style-dictionary build --config ./build-config-globals.js","style-dictionary:light":"style-dictionary build --config ./build-config-light.js","style-dictionary:dark":"style-dictionary build --config ./build-config-dark.js","style-dictionary:brands":"node build-brands.js build","style-dictionary:all":"npm run style-dictionary:globals && npm run style-dictionary:light && npm run style-dictionary:dark && npm run style-dictionary:brands","create-index":"node ./create-index.js","prepublishOnly":"npm run build","test":"npm run build"},"repository":{"type":"git","url":"git+https://github.com/Battmobility/Figma-FleetPlatform.git"},"keywords":["design-tokens","design-system","figma","tokens","batt-mobility","fleet-platform"],"author":{"name":"Batt Mobility"},"license":"MIT","bugs":{"url":"https://github.com/Battmobility/Figma-FleetPlatform/issues"},"homepage":"https://github.com/Battmobility/Figma-FleetPlatform#readme","devDependencies":{"style-dictionary":"^3.9.2","token-transformer":"^0.0.33"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_id":"@battmobility/fleet-design-tokens@1.0.7","gitHead":"d6eaddc183ff3dca1643ec4990117e41344e2dc7","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-V5ZzLolStdTINCyYUd9Jx/fMGGLd04RVbgQhBRaBiK53rLYplZ2JELkKGRRvV4OKKmw0tfYs+N+k2Jic8kcwgg==","shasum":"885c5ae6d4ec44e2bcbdaa7a4169ba8fcfc3019f","tarball":"https://registry.npmjs.org/@battmobility/fleet-design-tokens/-/fleet-design-tokens-1.0.7.tgz","fileCount":53,"unpackedSize":1456774,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCBZRG6DAwCACATvl7VfSuw8xXG06iylGFsObYsH25TrAIgDIgd1xAx7o6nzGw72qR+ojKlTTGacrpGKYUjCed39kQ="}]},"_npmUser":{"name":"tijldeclerck","email":"tijl@battmobiel.be"},"directories":{},"maintainers":[{"name":"peter_vht","email":"peter@battmobiel.be"},{"name":"tijldeclerck","email":"tijl@battmobiel.be"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/fleet-design-tokens_1.0.7_1758109910608_0.1928726113607122"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-28T05:21:30.536Z","modified":"2025-09-17T11:51:50.986Z","1.0.5":"2025-08-28T05:21:30.892Z","1.0.7":"2025-09-17T11:51:50.802Z"},"bugs":{"url":"https://github.com/Battmobility/Figma-FleetPlatform/issues"},"author":{"name":"Batt Mobility"},"license":"MIT","homepage":"https://github.com/Battmobility/Figma-FleetPlatform#readme","keywords":["design-tokens","design-system","figma","tokens","batt-mobility","fleet-platform"],"repository":{"type":"git","url":"git+https://github.com/Battmobility/Figma-FleetPlatform.git"},"description":"Design tokens for Batt Mobility's Fleet Platform","maintainers":[{"name":"peter_vht","email":"peter@battmobiel.be"},{"name":"tijldeclerck","email":"tijl@battmobiel.be"}],"readme":"# @battmobility/fleet-design-tokens\n\n> A comprehensive design token system for Batt Mobility's Fleet Platform that transforms Figma design decisions into code\n\n## Table of Contents\n- [What Are Design Tokens?](#what-are-design-tokens)\n- [How This Repository Works](#how-this-repository-works)\n- [Repository Structure](#repository-structure)\n- [The Token Pipeline Explained](#the-token-pipeline-explained)\n- [Token Architecture](#token-architecture)\n- [Build System Deep Dive](#build-system-deep-dive)\n- [Installation](#installation)\n- [Usage Guide](#usage-guide)\n- [Output Formats Explained](#output-formats-explained)\n- [Development Workflow](#development-workflow)\n- [Troubleshooting](#troubleshooting)\n- [Glossary](#glossary)\n\n## What Are Design Tokens?\n\nDesign 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.\n\n### Why Use Design Tokens?\n\n1. **Single Source of Truth**: Define once, use everywhere\n2. **Platform Agnostic**: Same tokens work in CSS, JavaScript, iOS, Android\n3. **Consistency**: Ensures design consistency across all products\n4. **Maintainability**: Change a color in one place, updates everywhere\n5. **Theming**: Easy theme switching (light/dark modes)\n\n### Real-World Example\n\nInstead of hardcoding colors:\n```css\n/* ❌ Without tokens - scattered, hard to maintain */\n.button { background: #635bff; }\n.header { border-color: #635bff; }\n.link { color: #635bff; }\n```\n\nUse design tokens:\n```css\n/* ✅ With tokens - centralized, easy to maintain */\n.button { background: var(--primary-main); }\n.header { border-color: var(--primary-main); }\n.link { color: var(--primary-main); }\n```\n\n## How This Repository Works\n\nThis repository is a **build pipeline** that transforms design tokens from Figma into multiple code formats:\n\n```\n┌─────────────┐      ┌──────────────┐      ┌─────────────┐      ┌──────────┐\n│   FIGMA     │ ---> │ TOKEN STUDIO │ ---> │ THIS REPO   │ ---> │   NPM    │\n│   Designs   │      │   Plugin     │      │ Build System│      │ Package  │\n└─────────────┘      └──────────────┘      └─────────────┘      └──────────┘\n      ↓                     ↓                      ↓                   ↓\n  Designers           Export JSON            Transform &          Developers\n  define colors       token files             Build to            import and use\n  & styles                                    multiple            in their apps\n                                              formats\n```\n\n### The Complete Workflow\n\n1. **Design Phase** (Figma)\n   - Designers create colors, typography, spacing in Figma\n   - Token Studio plugin captures these as structured data\n\n2. **Export Phase** (Token Studio)\n   - Exports design decisions as JSON files\n   - Maintains relationships between tokens (e.g., \"primary color uses blue-500\")\n\n3. **Transformation Phase** (This Repository)\n   - `token-transformer`: Processes Token Studio format into standard format\n   - `style-dictionary`: Transforms tokens into various code formats\n   - Custom scripts: Create proper module exports\n\n4. **Distribution Phase** (NPM)\n   - Published as `@battmobility/fleet-design-tokens`\n   - Developers install and use in their projects\n\n## Repository Structure\n\n```\nFigma-FleetPlatform/\n├── tokens/                      # 🎨 Source design tokens (from Figma)\n│   ├── $metadata.json           # Token loading order configuration\n│   ├── $themes.json             # Theme definitions (Light/Dark)\n│   ├── globals.json             # Base color palettes & scales\n│   ├── light/                   # Light theme tokens\n│   │   ├── default.json         # Core theme colors\n│   │   └── components.json      # Component-specific tokens\n│   ├── dark/                    # Dark theme tokens\n│   │   ├── default.json         # Core theme colors\n│   │   └── components.json      # Component-specific tokens\n│   └── brands/                  # Brand-specific overrides\n│       └── batt/\n│           ├── B2B.json         # Business customer branding\n│           └── B2C.json         # Consumer branding\n│\n├── build-config-base.js         # 🔧 Shared Style Dictionary config\n├── build-config-light.js        # Light theme build config\n├── build-config-dark.js         # Dark theme build config\n├── build-config.js              # Combined themes build (legacy)\n├── create-index.js              # Creates main index files\n│\n├── dist/                        # 📦 Built output (git-ignored)\n│   ├── css/                     # CSS variables\n│   │   ├── variables.css        # All tokens as CSS vars\n│   │   ├── light.css           # Light theme CSS\n│   │   └── dark.css            # Dark theme CSS\n│   ├── js/                      # JavaScript modules\n│   │   ├── index.js            # CommonJS main export\n│   │   ├── index.mjs           # ES modules main export\n│   │   ├── index.d.ts          # TypeScript definitions\n│   │   ├── light.js/mjs/d.ts   # Light theme modules\n│   │   └── dark.js/mjs/d.ts    # Dark theme modules\n│   ├── scss/                    # Sass variables\n│   │   └── _variables.scss\n│   └── json/                    # Processed JSON\n│       ├── light.json\n│       └── dark.json\n│\n├── package.json                 # Package configuration\n├── .github/workflows/           # CI/CD automation\n│   ├── ci.yml                  # Build validation\n│   └── publish.yml             # Auto-publish to NPM\n└── README.md                   # You are here! 📍\n```\n\n## The Token Pipeline Explained\n\n### Step 1: Raw Tokens (Token Studio Format)\n\nToken Studio exports tokens with special features like references and modifiers:\n\n```json\n// tokens/light/default.json\n{\n  \"primary\": {\n    \"main\": {\n      \"value\": \"{neonBlue.500}\",  // Reference to another token\n      \"type\": \"color\"\n    }\n  },\n  \"text\": {\n    \"primary\": {\n      \"value\": \"{neutral.900}\",   // Reference to global token\n      \"type\": \"color\"\n    }\n  }\n}\n```\n\n### Step 2: Token Transformation\n\nThe `token-transformer` tool resolves these references:\n\n```bash\n# Command that runs during build\ntoken-transformer tokens dist/light.json \\\n  --sets=globals,light/default,light/components \\\n  --expandTypography=true\n```\n\nThis produces:\n```json\n// dist/light.json (transformed)\n{\n  \"primary\": {\n    \"main\": {\n      \"value\": \"#635bff\",  // Resolved to actual color\n      \"type\": \"color\"\n    }\n  }\n}\n```\n\n### Step 3: Style Dictionary Processing\n\nStyle Dictionary takes the transformed tokens and generates multiple formats:\n\n```javascript\n// How tokens flow through Style Dictionary\n┌──────────────┐     ┌──────────────┐     ┌──────────────┐\n│ Transformed  │ --> │ Custom       │ --> │   Output     │\n│   Tokens     │     │ Formatters   │     │   Files      │\n└──────────────┘     └──────────────┘     └──────────────┘\n  light.json          ES6, CSS,            index.mjs\n  dark.json           TypeScript,          variables.css\n                      SCSS formats         _variables.scss\n```\n\n### Step 4: Module Creation\n\nThe `create-index.js` script creates the main entry points:\n\n```javascript\n// Creates dist/js/index.mjs\nimport lightTheme from './light.mjs';\nimport darkTheme from './dark.mjs';\n\nexport default { light: lightTheme, dark: darkTheme };\n```\n\n## Token Architecture\n\nThe token system has **four layers**, each building on the previous:\n\n### 1️⃣ Global Tokens (Foundation)\nRaw color palettes and scales - the building blocks:\n\n```json\n// tokens/globals.json\n{\n  \"neonBlue\": {\n    \"500\": { \"value\": \"#635bff\", \"type\": \"color\" },\n    \"600\": { \"value\": \"#4e36f5\", \"type\": \"color\" }\n  },\n  \"neutral\": {\n    \"900\": { \"value\": \"#111827\", \"type\": \"color\" },\n    \"100\": { \"value\": \"#f3f4f6\", \"type\": \"color\" }\n  }\n}\n```\n\n### 2️⃣ Theme Tokens (Semantic)\nMeaningful names that reference global tokens:\n\n```json\n// tokens/light/default.json\n{\n  \"primary\": {\n    \"main\": { \"value\": \"{neonBlue.500}\" },    // Brand color\n    \"dark\": { \"value\": \"{neonBlue.600}\" }     // Hover state\n  },\n  \"background\": {\n    \"paper\": { \"value\": \"{neutral.100}\" }     // Card backgrounds\n  }\n}\n```\n\n### 3️⃣ Component Tokens\nSpecific to UI components:\n\n```json\n// tokens/light/components.json\n{\n  \"button\": {\n    \"background\": { \"value\": \"{primary.main}\" },\n    \"text\": { \"value\": \"{primary.contrast}\" }\n  }\n}\n```\n\n### 4️⃣ Brand Tokens (Optional)\nOverride for different brands:\n\n```json\n// tokens/brands/batt/B2C.json\n{\n  \"primary\": {\n    \"main\": { \"value\": \"{blueRibbon.500}\" }  // Different blue for consumers\n  }\n}\n```\n\n### Token Resolution Example\n\nHere's how a button color is resolved:\n\n```\nButton Background Color Resolution:\n\n1. Component token:    button.background = {primary.main}\n                             ↓\n2. Theme token:        primary.main = {neonBlue.500}\n                             ↓\n3. Global token:       neonBlue.500 = #635bff\n                             ↓\n4. Final output:       --button-background: #635bff;\n```\n\n## Build System Deep Dive\n\n### Why Multiple Build Configs?\n\nThe repository uses several build configuration files for different purposes:\n\n#### `build-config-base.js`\n- **Purpose**: Shared configuration and custom formatters\n- **Contains**: \n  - Custom Style Dictionary transforms\n  - ES6/TypeScript/CSS formatters\n  - Collision handling for token names\n- **Used by**: Light and dark theme builds\n\n#### `build-config-light.js` & `build-config-dark.js`\n- **Purpose**: Theme-specific builds\n- **Why separate**: \n  - Smaller bundle sizes (import only what you need)\n  - Clear separation of themes\n  - Parallel build processing\n\n### Custom Formatters Explained\n\nThe build system includes custom formatters for different needs:\n\n#### ES6 Module Formatter\n```javascript\n// Handles name collisions and creates clean exports\nStyleDictionary.registerFormat({\n  name: 'javascript/es6-default',\n  formatter: function({ dictionary }) {\n    // Converts token.name.with.dots → tokenNameWithDots\n    // Handles collisions: adds _2, _3 suffixes\n    // Creates both named and default exports\n  }\n});\n```\n\n#### CSS Variables Formatter\n```javascript\n// Creates theme-specific CSS\nStyleDictionary.registerFormat({\n  name: 'css/variables-themed',\n  formatter: function({ dictionary, options }) {\n    // Outputs: [data-theme=\"light\"] { --token-name: value; }\n  }\n});\n```\n\n## Installation\n\n### NPM Installation\n\n```bash\n# Install the package\nnpm install @battmobility/fleet-design-tokens\n\n# Or with yarn\nyarn add @battmobility/fleet-design-tokens\n\n# Or with pnpm\npnpm add @battmobility/fleet-design-tokens\n```\n\n### CDN Usage\n\nFor quick prototypes or static sites:\n\n```html\n<!-- Latest version -->\n<link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/@battmobility/fleet-design-tokens/dist/css/variables.css\">\n\n<!-- Specific version (recommended for production) -->\n<link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/@battmobility/fleet-design-tokens@1.0.4/dist/css/variables.css\">\n```\n\n## Usage Guide\n\n### JavaScript/TypeScript\n\n#### Basic Import\n```javascript\n// Import all tokens\nimport tokens from '@battmobility/fleet-design-tokens';\n\n// Use in your code\nconst primaryColor = tokens.light.primary.main; // \"#635bff\"\nconst darkBackground = tokens.dark.background.paper; // \"#1a1a1a\"\n```\n\n#### Theme-Specific Imports\n```javascript\n// Import only what you need - smaller bundle!\nimport lightTokens from '@battmobility/fleet-design-tokens/light';\nimport darkTokens from '@battmobility/fleet-design-tokens/dark';\n\n// TypeScript gets full type safety\nconst color: string = lightTokens.primary.main;\n```\n\n#### React Example\n```jsx\nimport { useState } from 'react';\nimport tokens from '@battmobility/fleet-design-tokens';\nimport '@battmobility/fleet-design-tokens/css';\n\nfunction App() {\n  const [theme, setTheme] = useState('light');\n  \n  // Apply theme to root element\n  useEffect(() => {\n    document.documentElement.setAttribute('data-theme', theme);\n  }, [theme]);\n  \n  return (\n    <div style={{\n      backgroundColor: tokens[theme].background.default,\n      color: tokens[theme].text.primary\n    }}>\n      <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>\n        Toggle Theme\n      </button>\n    </div>\n  );\n}\n```\n\n### CSS Variables\n\n#### Basic Usage\n```css\n/* Tokens are available as CSS custom properties */\n.button {\n  background-color: var(--primary-main);\n  color: var(--primary-contrast);\n  border-radius: var(--radius-medium);\n}\n\n.button:hover {\n  background-color: var(--primary-dark);\n}\n```\n\n#### Theme Switching\n```html\n<!-- Light theme -->\n<html data-theme=\"light\">\n  <body>\n    <button class=\"primary-button\">Click me</button>\n  </body>\n</html>\n\n<!-- Dark theme -->\n<html data-theme=\"dark\">\n  <!-- Same HTML, different colors! -->\n</html>\n```\n\n```javascript\n// JavaScript theme switcher\nfunction setTheme(theme) {\n  document.documentElement.setAttribute('data-theme', theme);\n  localStorage.setItem('theme', theme);\n}\n\n// Load saved theme on page load\nconst savedTheme = localStorage.getItem('theme') || 'light';\nsetTheme(savedTheme);\n```\n\n### Styled Components\n\n```javascript\nimport styled from 'styled-components';\nimport tokens from '@battmobility/fleet-design-tokens';\n\nconst Button = styled.button`\n  background: ${props => tokens[props.theme].primary.main};\n  color: ${props => tokens[props.theme].primary.contrast};\n  padding: ${tokens.spacing.medium};\n  border-radius: ${tokens.radius.medium};\n  \n  &:hover {\n    background: ${props => tokens[props.theme].primary.dark};\n  }\n`;\n\n// Usage\n<Button theme=\"light\">Light Button</Button>\n<Button theme=\"dark\">Dark Button</Button>\n```\n\n### Tailwind CSS Integration\n\n```javascript\n// tailwind.config.js\nconst tokens = require('@battmobility/fleet-design-tokens');\n\nmodule.exports = {\n  theme: {\n    extend: {\n      colors: {\n        primary: {\n          main: tokens.light.primary.main,\n          dark: tokens.light.primary.dark,\n          light: tokens.light.primary.light,\n        },\n        // ... more colors\n      },\n    },\n  },\n};\n```\n\n### SCSS/Sass\n\n```scss\n// Import all variables\n@import '@battmobility/fleet-design-tokens/scss';\n\n// Use in your styles\n.card {\n  background: $background-paper;\n  border: 1px solid $border-default;\n  box-shadow: $shadow-medium;\n  \n  .title {\n    color: $text-primary;\n  }\n}\n```\n\n## Output Formats Explained\n\n### CSS Variables (`dist/css/`)\n- **What**: CSS custom properties\n- **When to use**: Web applications, runtime theming\n- **Files**:\n  - `variables.css`: All tokens\n  - `light.css`: Light theme with `[data-theme=\"light\"]`\n  - `dark.css`: Dark theme with `[data-theme=\"dark\"]`\n\n### JavaScript Modules (`dist/js/`)\n- **What**: ES modules and CommonJS\n- **When to use**: React, Vue, Node.js apps\n- **Files**:\n  - `.mjs`: ES modules (import/export)\n  - `.js`: CommonJS (require)\n  - `.d.ts`: TypeScript definitions\n\n### SCSS (`dist/scss/`)\n- **What**: Sass variables\n- **When to use**: Projects using Sass/SCSS\n- **Note**: Compile-time only, no runtime theming\n\n### JSON (`dist/json/`)\n- **What**: Raw token values\n- **When to use**: Custom build tools, native apps\n\n## Development Workflow\n\n### Local Development\n\n1. **Clone the repository**\n```bash\ngit clone https://github.com/Battmobility/Figma-FleetPlatform.git\ncd Figma-FleetPlatform\n```\n\n2. **Install dependencies**\n```bash\nnpm install\n```\n\n3. **Make changes to tokens**\n```bash\n# Edit token files in tokens/ directory\nvim tokens/light/default.json\n```\n\n4. **Build and test**\n```bash\n# Build all formats\nnpm run build\n\n# Check the output\nls -la dist/\n```\n\n5. **Test in a project**\n```bash\n# Link for local testing\nnpm link\n\n# In your project\nnpm link @battmobility/fleet-design-tokens\n```\n\n### Adding New Tokens\n\n1. **Add to appropriate file**:\n   - Global colors → `tokens/globals.json`\n   - Theme colors → `tokens/[theme]/default.json`\n   - Component tokens → `tokens/[theme]/components.json`\n\n2. **Follow naming conventions**:\n```json\n{\n  \"category\": {\n    \"property\": {\n      \"variant\": {\n        \"value\": \"#value\",\n        \"type\": \"color\",\n        \"description\": \"Used for...\"\n      }\n    }\n  }\n}\n```\n\n3. **Build and verify**:\n```bash\nnpm run build\n# Check that your token appears in dist/\n```\n\n### Testing Changes\n\n```bash\n# Run build as a test\nnpm test\n\n# Validate JSON structure\nnpx jsonlint tokens/**/*.json\n\n# Check output files\nfind dist -name \"*.css\" -exec grep \"your-new-token\" {} \\;\n```\n\n## Troubleshooting\n\n### Common Issues and Solutions\n\n#### Tokens not appearing in output\n- **Check**: Token is in correct theme set (`$themes.json`)\n- **Verify**: Build command includes your token set\n- **Solution**: Check `selectedTokenSets` in `$themes.json`\n\n#### Build fails with \"Cannot resolve reference\"\n- **Cause**: Token references a non-existent token\n- **Solution**: Check that referenced token exists in globals or same theme\n\n#### Name collisions in JavaScript output\n- **Symptom**: Tokens with `_2`, `_3` suffixes\n- **Cause**: Multiple tokens resolve to same JavaScript variable name\n- **Solution**: Check build output for collision comments\n\n#### CSS variables not updating\n- **Check**: Correct theme attribute on HTML element\n- **Verify**: Both CSS files are loaded (variables.css + theme.css)\n- **Solution**: Ensure `data-theme` attribute matches CSS selector\n\n#### TypeScript types not found\n- **Solution**: Add to `tsconfig.json`:\n```json\n{\n  \"compilerOptions\": {\n    \"moduleResolution\": \"node\",\n    \"esModuleInterop\": true\n  }\n}\n```\n\n### Build Commands Reference\n\n```bash\n# Clean build directory\nnpm run clean\n\n# Transform tokens (Token Studio → Style Dictionary format)\nnpm run transform:light\nnpm run transform:dark\nnpm run transform:all\n\n# Run Style Dictionary builds\nnpm run style-dictionary:light\nnpm run style-dictionary:dark\nnpm run style-dictionary:all\n\n# Create index files\nnpm run create-index\n\n# Full build (runs all above)\nnpm run build\n```\n\n## Publishing\n\n### Automatic Publishing\nThe package is automatically published to NPM when:\n1. Version in `package.json` is updated\n2. Changes are pushed to `main` branch\n3. CI/CD checks pass\n\n### Manual Publishing\n```bash\n# 1. Update version\nnpm version patch  # 1.0.0 → 1.0.1\nnpm version minor  # 1.0.0 → 1.1.0\nnpm version major  # 1.0.0 → 2.0.0\n\n# 2. Build\nnpm run build\n\n# 3. Publish\nnpm publish\n\n# 4. Push changes\ngit push origin main --tags\n```\n\n## Glossary\n\n### Design Token Terms\n\n**Design Token**: A named entity that stores a design decision (color, spacing, etc.)\n\n**Token Reference**: A token that points to another token's value using `{token.path}` syntax\n\n**Token Set**: A collection of related tokens (e.g., \"light theme\" set)\n\n**Token Type**: The data type (color, dimension, typography, etc.)\n\n**Semantic Token**: A token with meaning (e.g., `primary.main` vs `blue-500`)\n\n**Global Token**: Base-level token without semantic meaning\n\n### Technical Terms\n\n**Token Studio**: Figma plugin for managing design tokens\n\n**Style Dictionary**: Amazon's build system for transforming tokens\n\n**token-transformer**: Tool that converts Token Studio format to Style Dictionary format\n\n**Platform**: Output target (web, iOS, Android)\n\n**Transform**: Function that modifies token values during build\n\n**Formatter**: Function that generates output files in specific formats\n\n**CommonJS**: Node.js module system using `require()` and `module.exports`\n\n**ES Modules**: Modern JavaScript module system using `import` and `export`\n\n## Contributing\n\n1. Make changes in Figma using Token Studio plugin\n2. Export and commit token JSON files\n3. Test locally with `npm run build`\n4. Create pull request\n5. CI/CD will validate and auto-publish when merged\n\n## Support\n\nFor issues or questions:\n- GitHub Issues: [github.com/Battmobility/Figma-FleetPlatform/issues](https://github.com/Battmobility/Figma-FleetPlatform/issues)\n- Documentation: This README\n- Token Studio Docs: [docs.tokens.studio](https://docs.tokens.studio/)\n- Style Dictionary Docs: [amzn.github.io/style-dictionary](https://amzn.github.io/style-dictionary/)\n","readmeFilename":"README.md"}