Design Token npm Package

A design token npm package distributes tokens through the npm ecosystem, enabling standard JavaScript package management for design values. Well-structured packages provide clear entry points, comprehensive exports, and documentation that makes token adoption straightforward for consumers.

What Is a Design Token npm Package

A design token npm package is an npm package containing compiled token outputs in various formats. The package structure, exports configuration, and documentation determine how easily consumers can integrate tokens into their projects.

npm packages leverage the entire npm ecosystem: versioning, dependency management, installation, and updates all work through familiar tooling.

How Design Token npm Packages Work

Package structure:

@company/design-tokens/
  dist/
    css/
      tokens.css
      tokens.min.css
      variables.css
    js/
      index.js
      index.mjs
      index.d.ts
      tokens.json
    scss/
      _tokens.scss
      _mixins.scss
  package.json
  README.md
  CHANGELOG.md

Package.json configuration:

{
  "name": "@company/design-tokens",
  "version": "2.3.0",
  "description": "Design tokens for Company products",
  "main": "./dist/js/index.js",
  "module": "./dist/js/index.mjs",
  "types": "./dist/js/index.d.ts",
  "style": "./dist/css/tokens.css",
  "exports": {
    ".": {
      "import": "./dist/js/index.mjs",
      "require": "./dist/js/index.js",
      "types": "./dist/js/index.d.ts"
    },
    "./css": "./dist/css/tokens.css",
    "./css/variables": "./dist/css/variables.css",
    "./scss": "./dist/scss/_tokens.scss",
    "./json": "./dist/js/tokens.json"
  },
  "sideEffects": [
    "*.css"
  ],
  "files": ["dist"],
  "keywords": ["design-tokens", "design-system", "css-variables"],
  "repository": {
    "type": "git",
    "url": "https://github.com/company/design-system"
  },
  "license": "MIT"
}

Consumer usage:

// JavaScript import
import { colorPrimary, spacingMd } from '@company/design-tokens';

// CSS import
import '@company/design-tokens/css';

// SCSS import
@use '@company/design-tokens/scss' as tokens;

// JSON import
import tokens from '@company/design-tokens/json';

Key Considerations

• Entry points should cover common consumption patterns
• TypeScript types improve developer experience
• sideEffects field enables tree shaking
• README should provide quick start examples
• Keywords improve discoverability
• Peer dependencies should be documented
• Bundle size should be optimized
• Changelog should track all changes

Common Questions

How should entry points be designed?

Entry points determine how consumers import tokens.

JavaScript exports:

// dist/js/index.js
module.exports = {
  colorPrimary: '#3B82F6',
  colorBackground: '#FFFFFF',
  spacingMd: 16,
  // ...
};

// dist/js/index.mjs (ES modules)
export const colorPrimary = '#3B82F6';
export const colorBackground = '#FFFFFF';
export const spacingMd = 16;

CSS exports:

/* dist/css/tokens.css */
:root {
  --color-primary: #3B82F6;
  --color-background: #FFFFFF;
  --spacing-md: 16px;
}

SCSS exports:

/* dist/scss/_tokens.scss */
$color-primary: #3B82F6;
$color-background: #FFFFFF;
$spacing-md: 16px;

// As a map for iteration
$colors: (
  'primary': #3B82F6,
  'background': #FFFFFF
);

Subpath exports:

{
  "exports": {
    ".": "./dist/js/index.mjs",
    "./css": "./dist/css/tokens.css",
    "./colors": "./dist/js/colors.mjs",
    "./spacing": "./dist/js/spacing.mjs"
  }
}

How should TypeScript support be provided?

TypeScript types enable autocompletion and type checking.

Type definitions:

// dist/js/index.d.ts
export declare const colorPrimary: string;
export declare const colorBackground: string;
export declare const spacingMd: number;

export interface Tokens {
  color: {
    primary: string;
    background: string;
  };
  spacing: {
    md: number;
  };
}

export declare const tokens: Tokens;

Generated from tokens:

// Build script
function generateTypes(tokens) {
  const declarations = tokens.map(token =>
    `export declare const ${token.jsName}: ${token.tsType};`
  );

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

Package.json types field:

{
  "types": "./dist/js/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/js/index.d.ts",
      "import": "./dist/js/index.mjs"
    }
  }
}

How should the README guide consumers?

README provides the first impression and quick start guidance.

README structure:

# @company/design-tokens

Design tokens for Company design system.

## Installation

\`\`\`bash
npm install @company/design-tokens
\`\`\`

## Usage

### CSS Custom Properties

\`\`\`css
@import '@company/design-tokens/css';

.button {
  background: var(--color-primary);
  padding: var(--spacing-md);
}
\`\`\`

### JavaScript/TypeScript

\`\`\`javascript
import { colorPrimary, spacingMd } from '@company/design-tokens';
\`\`\`

### SCSS

\`\`\`scss
@use '@company/design-tokens/scss' as tokens;

.button {
  background: tokens.$color-primary;
}
\`\`\`

## Available Tokens

See [documentation](https://docs.company.com/tokens) for complete token reference.

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history.

Summary

Design token npm packages distribute tokens through familiar package management. Package structure with clear entry points for CSS, JavaScript, and SCSS enables flexible consumption. TypeScript types improve developer experience with autocompletion. README documentation provides quick start guidance. Proper exports configuration, sideEffects declaration, and file organization create consumer-friendly packages.