Design Token Monorepo Setup

Design token monorepo setup organizes tokens alongside components, documentation, and tooling in a single repository. Monorepos enable coordinated changes across the design system while maintaining clear package boundaries. Understanding monorepo patterns helps teams manage tokens effectively within larger design system architectures.

What Is Design Token Monorepo Setup

Design token monorepo setup places token source files and transformation tooling within a monorepo that may also contain component libraries, documentation, and other design system packages. This co-location enables atomic commits spanning tokens and components while maintaining separate publishable packages.

How Design Token Monorepo Setup Works

Typical monorepo structure:

design-system/
  packages/
    tokens/
      src/
        color/
        spacing/
        typography/
      build/
        config.js
      dist/
        css/
        js/
        ios/
        android/
      package.json
    react-components/
      src/
      package.json
    docs/
      package.json
  package.json
  lerna.json (or pnpm-workspace.yaml)

Token package configuration:

// packages/tokens/package.json
{
  "name": "@company/tokens",
  "version": "2.3.0",
  "main": "dist/js/tokens.js",
  "style": "dist/css/tokens.css",
  "files": ["dist"],
  "scripts": {
    "build": "style-dictionary build",
    "clean": "rm -rf dist"
  },
  "devDependencies": {
    "style-dictionary": "^3.0.0"
  }
}

Workspace configuration:

# pnpm-workspace.yaml
packages:
  - 'packages/*'

Cross-package dependency:

// packages/react-components/package.json
{
  "name": "@company/react-components",
  "dependencies": {
    "@company/tokens": "workspace:*"
  }
}

Key Considerations

• Token builds should precede dependent package builds
• Versioning strategy affects package relationships
• Changes spanning packages should be atomic
• CI should understand package dependencies
• Local development should use workspace linking
• Published packages should be independent
• Documentation should reflect current token state
• Test infrastructure should cover cross-package scenarios

Common Questions

How should build order be managed?

Dependent packages need tokens built first.

Turborepo configuration:

// turbo.json
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "@company/tokens#build": {
      "outputs": ["dist/**"]
    },
    "@company/react-components#build": {
      "dependsOn": ["@company/tokens#build"],
      "outputs": ["dist/**"]
    }
  }
}

Lerna with topological sorting:

# Builds in dependency order automatically
npx lerna run build

npm workspaces scripts:

// Root package.json
{
  "scripts": {
    "build": "npm run build -w @company/tokens && npm run build -w @company/react-components"
  }
}

How should versioning work in a monorepo?

Versioning strategies affect how packages relate.

Fixed versioning (lockstep):

// All packages share version
{
  "@company/tokens": "2.3.0",
  "@company/react-components": "2.3.0",
  "@company/docs": "2.3.0"
}

Pros: Simple dependency management Cons: Token-only changes bump all packages

Independent versioning:

// Each package versions independently
{
  "@company/tokens": "2.3.0",
  "@company/react-components": "1.5.0",
  "@company/docs": "3.1.0"
}

Pros: Precise versioning Cons: Complex dependency tracking

Changesets for independent versioning:

<!-- .changeset/add-new-color.md -->
---
"@company/tokens": minor
---

Added new status colors for feedback states.

npx changeset # Create changeset
npx changeset version # Apply versions
npx changeset publish # Publish packages

How should local development work?

Local development should enable rapid iteration.

Workspace linking:

# pnpm automatically links workspace packages
pnpm install

# Component package imports local tokens, not published
import { tokens } from '@company/tokens';

Watch mode for tokens:

// packages/tokens/package.json
{
  "scripts": {
    "dev": "style-dictionary build --watch"
  }
}

Parallel development:

# Run all dev scripts in parallel
pnpm run dev --parallel

# Or with Turborepo
turbo dev

Hot reloading:

// Vite config for hot reloading linked packages
export default {
  optimizeDeps: {
    exclude: ['@company/tokens']
  }
};

Summary

Design token monorepo setup co-locates tokens with components and documentation while maintaining separate publishable packages. Build order management ensures tokens build before dependent packages. Versioning strategies range from fixed (simpler) to independent (precise). Local development uses workspace linking for rapid iteration with watch modes and hot reloading. Monorepo tooling like Turborepo, Lerna, or npm workspaces coordinates these workflows.