Token TypeScript Types

Token TypeScript types provide compile-time type safety and IDE autocompletion for design token usage. Generated types prevent typos, enable refactoring support, and improve the developer experience by making tokens discoverable through code completion. TypeScript integration represents a significant quality-of-life improvement for token consumers.

What Are Token TypeScript Types

Token TypeScript types are TypeScript declaration files (.d.ts) or inline type definitions that describe the shape and types of design token values. These types enable TypeScript to validate token usage, provide autocomplete suggestions, and catch errors before runtime.

How Token TypeScript Types Work

Type generation from tokens:

// Build script generating types
function generateTypes(tokens) {
  const lines = [
    '// Auto-generated token types',
    'declare module "@company/tokens" {',
  ];

  tokens.forEach(token => {
    lines.push(`  export const ${token.jsName}: ${getType(token)};`);
  });

  lines.push('}');
  return lines.join('\n');
}

function getType(token) {
  switch (token.type) {
    case 'color': return 'string';
    case 'dimension': return 'number';
    case 'fontFamily': return 'string';
    default: return 'string';
  }
}

Generated type definitions:

// dist/tokens.d.ts
declare module "@company/tokens" {
  export const colorPrimary: string;
  export const colorBackground: string;
  export const spacingXs: number;
  export const spacingMd: number;
  export const fontFamilySans: string;

  export interface ColorTokens {
    primary: string;
    background: string;
    text: {
      primary: string;
      secondary: string;
    };
  }

  export interface SpacingTokens {
    xs: number;
    sm: number;
    md: number;
    lg: number;
  }

  export interface Tokens {
    color: ColorTokens;
    spacing: SpacingTokens;
  }

  export const tokens: Tokens;
}

Consumer usage with types:

import { colorPrimary, tokens } from '@company/tokens';

// Type-safe usage
const primaryColor: string = colorPrimary;

// Autocomplete works for nested tokens
const textColor = tokens.color.text.primary;

// Type error caught at compile time
const wrong = tokens.color.nonexistent; // Error: Property 'nonexistent' does not exist

Key Considerations

• Types should be generated alongside token builds
• Type accuracy must match actual token values
• Complex token structures need interface definitions
• Theme variants may need conditional types
• Types should be included in package distribution
• IDE configuration affects autocomplete experience
• Type updates should accompany token changes
• Generic utility types can enhance flexibility

Common Questions

How should complex token structures be typed?

Complex tokens like typography composites need structured type definitions.

Typography composite types:

interface TypographyToken {
  fontFamily: string;
  fontSize: string;
  fontWeight: number;
  lineHeight: number;
  letterSpacing: string;
}

interface TypographyTokens {
  body: {
    sm: TypographyToken;
    md: TypographyToken;
    lg: TypographyToken;
  };
  heading: {
    sm: TypographyToken;
    md: TypographyToken;
    lg: TypographyToken;
  };
}

export const typography: TypographyTokens;

Shadow composite types:

interface ShadowLayer {
  offsetX: string;
  offsetY: string;
  blur: string;
  spread: string;
  color: string;
}

interface ShadowTokens {
  sm: ShadowLayer[];
  md: ShadowLayer[];
  lg: ShadowLayer[];
}

Union types for constrained values:

type SpacingScale = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
type ColorCategory = 'primary' | 'secondary' | 'accent' | 'error' | 'success';

function getSpacing(scale: SpacingScale): number;
function getColor(category: ColorCategory): string;

How should theme variants be typed?

Theme variants require types that represent different token configurations.

Theme-specific types:

interface ThemeTokens {
  color: {
    background: string;
    text: string;
    primary: string;
  };
}

interface LightTheme extends ThemeTokens {}
interface DarkTheme extends ThemeTokens {}

export const lightTheme: LightTheme;
export const darkTheme: DarkTheme;

// Generic theme accessor
export function getTheme(name: 'light' | 'dark'): ThemeTokens;

Discriminated union for themes:

type Theme =
  | { name: 'light'; tokens: LightTheme }
  | { name: 'dark'; tokens: DarkTheme };

function applyTheme(theme: Theme): void;

How should type generation be automated?

Automation ensures types stay synchronized with tokens.

Style Dictionary type format:

// Custom format for TypeScript
StyleDictionary.registerFormat({
  name: 'typescript/declarations',
  formatter: ({ dictionary }) => {
    const lines = ['// Auto-generated - do not edit'];

    dictionary.allTokens.forEach(token => {
      lines.push(`export declare const ${token.name}: ${inferType(token)};`);
    });

    return lines.join('\n');
  }
});

// Config
{
  platforms: {
    ts: {
      transformGroup: 'js',
      buildPath: 'dist/',
      files: [{
        destination: 'tokens.d.ts',
        format: 'typescript/declarations'
      }]
    }
  }
}

CI verification:

- name: Generate types
  run: npm run build:types

- name: Verify types match
  run: |
    git diff --exit-code dist/tokens.d.ts || {
      echo "Types out of sync with tokens"
      exit 1
    }

Summary

Token TypeScript types provide compile-time safety and IDE autocompletion for token usage. Generated types describe token shapes and values, enabling TypeScript to validate usage. Complex structures like typography and shadows need interface definitions. Theme variants may require conditional or union types. Automated type generation ensures synchronization with token changes. Well-typed tokens significantly improve developer experience and code quality.