@bernierllc/design-token-parser

A core utility for design token processing and format normalization with style-dictionary integration.

Installation

npm install @bernierllc/design-token-parser

Usage

Basic Token Parsing

import { DesignTokenParser } from '@bernierllc/design-token-parser';

const parser = new DesignTokenParser();

const tokens = {
  color: {
    primary: { value: '#007bff', type: 'color' },
    secondary: { value: '#6c757d', type: 'color' }
  },
  spacing: {
    small: { value: '8px', type: 'spacing' },
    medium: { value: '16px', type: 'spacing' }
  },
  typography: {
    heading: { 
      value: { fontSize: '24px', fontWeight: 'bold' }, 
      type: 'typography' 
    }
  }
};

const parsedTokens = await parser.parseTokens({ tokens });
console.log(parsedTokens.tokens);

File-Based Parsing

// Parse from JSON file
const tokens = await parser.parseFromFile('./tokens.json');

// Parse from CSS string
const cssString = `
  :root {
    --color-primary: #007bff;
    --spacing-small: 8px;
  }
`;
const cssTokens = await parser.parseFromString(cssString, { type: 'css' });

Generate Multiple Output Formats

const parsedTokens = await parser.parseTokens({ tokens });

// Generate CSS custom properties
const css = parser.generateOutput(parsedTokens, { type: 'css' });

// Generate SCSS variables
const scss = parser.generateOutput(parsedTokens, { type: 'scss' });

// Generate JSON
const json = parser.generateOutput(parsedTokens, { type: 'json' });

// Generate JavaScript module
const js = parser.generateOutput(parsedTokens, { type: 'javascript' });

// Generate TypeScript module
const ts = parser.generateOutput(parsedTokens, { type: 'typescript' });

Token Transformations

const transforms = [
  { name: 'scale', options: { factor: 1.5 } },
  { name: 'darkMode', options: { mode: 'invert' } }
];

const transformedTokens = parser.transformTokens(parsedTokens, transforms);
const css = parser.generateOutput(transformedTokens, { type: 'css' });

CSS Output with Utility Classes

const css = parser.generateOutput(transformedTokens, { 
  type: 'css',
  options: { 
    utilities: true,
    selector: '.theme'
  }
});

Token Validation

const validation = parser.validateTokens(parsedTokens);

if (!validation.isValid) {
  console.error('Validation errors:', validation.errors);
}

if (validation.warnings.length > 0) {
  console.warn('Warnings:', validation.warnings);
}

Reference Resolution

const tokens = {
  color: {
    primary: { value: '#007bff', type: 'color' },
    secondary: { value: '{color.primary}', type: 'color' }
  }
};

const parsed = await parser.parseTokens({ tokens });
const resolved = parser.resolveReferences(parsed);
console.log(resolved.tokens);

API Reference

DesignTokenParser

Constructor

new DesignTokenParser(config?: ParserConfig)

Methods

• parseTokens(input: TokenInput): Promise<ParsedTokens> - Parse design tokens from object
• parseFromFile(filePath: string): Promise<ParsedTokens> - Parse tokens from JSON file
• parseFromString(content: string, format: TokenFormat): Promise<ParsedTokens> - Parse tokens from string
• transformTokens(tokens: ParsedTokens, transforms: Transform[]): TransformedTokens - Apply transformations
• generateOutput(tokens: TransformedTokens, format: OutputFormat): string - Generate output format
• validateTokens(tokens: ParsedTokens): ValidationResult - Validate token structure
• resolveReferences(tokens: ParsedTokens): ResolvedTokens - Resolve token references
• flattenTokens(tokens: ParsedTokens): FlattenedTokens - Flatten token structure
• categorizeTokens(tokens: Record<string, DesignToken>): Record<string, DesignToken> - Categorize tokens

Configuration

interface ParserConfig {
  defaultFormat?: TokenFormat;
  platforms?: string[];
  transforms?: string[];
  cacheSize?: number;
  strictMode?: boolean;
  validateReferences?: boolean;
}

Token Types

The parser supports the following token types:

• color - Color values (#hex, rgb(), hsl())
• typography - Font and text properties
• spacing - Margin, padding, gaps
• sizing - Width, height, dimensions
• border - Border properties
• shadow - Box shadow values
• animation - Animation and transition properties
• layout - General layout properties
• component - Component-specific tokens

Output Formats

• css - CSS custom properties with optional utility classes
• scss - SCSS variables
• json - Structured JSON object
• javascript - ES6 module export
• typescript - TypeScript module with type definitions

Features

• Multi-format Support - Parse from JSON, CSS, and other formats
• Token Categorization - Automatic categorization by type and usage
• Reference Resolution - Handle token references and aliases
• Multiple Output Formats - Generate CSS, SCSS, JSON, JavaScript, TypeScript
• Transformations - Apply scaling, theming, and custom transformations
• Validation - Comprehensive token validation with warnings and suggestions
• Type Safety - Full TypeScript support with strict typing
• Style Dictionary Integration - Built on proven design token tooling

Supported Input Formats

JSON Tokens

{
  "color": {
    "primary": {
      "value": "#007bff",
      "type": "color",
      "description": "Primary brand color"
    }
  }
}

CSS Custom Properties

:root {
  --color-primary: #007bff;
  --spacing-small: 8px;
  --font-size-large: 18px;
}

Advanced Usage

Custom Parser Configuration

const parser = new DesignTokenParser({
  strictMode: true,
  validateReferences: true,
  platforms: ['web', 'ios', 'android'],
  cacheSize: 200
});

Complex Token Structure

const tokens = {
  theme: {
    light: {
      color: {
        primary: { value: '#007bff', type: 'color' },
        text: { value: '#333333', type: 'color' }
      }
    },
    dark: {
      color: {
        primary: { value: '#0056b3', type: 'color' },
        text: { value: '#ffffff', type: 'color' }
      }
    }
  }
};

Metadata Preservation

const parsed = await parser.parseTokens({
  tokens,
  metadata: {
    version: '2.0.0',
    author: 'Design Team',
    description: 'Primary design tokens'
  }
});

console.log(parsed.metadata);

Error Handling

try {
  const result = await parser.parseTokens({ tokens });
  
  if (result.errors.length > 0) {
    console.error('Token errors:', result.errors);
  }
  
} catch (error) {
  console.error('Parser error:', error.message);
}

See Also

• @bernierllc/template-engine - Template rendering for design systems
• @bernierllc/markdown-renderer - Markdown processing utilities

License

Copyright (c) 2025 Bernier LLC. All rights reserved.