@winzenburg/tokens

Design tokens for consistent visual design across all platforms

Design tokens are the foundation of our design system, providing a single source of truth for colors, typography, spacing, and more. This package generates platform-specific outputs from a central JSON source.

Installation

npm install @winzenburg/tokens

Usage

CSS Variables (Recommended)

Import the CSS file to use tokens as CSS custom properties:

/* Import in your CSS */
@import '@winzenburg/tokens/css';

/* Or import in your JavaScript/TypeScript */
import '@winzenburg/tokens/css';

.my-component {
  /* Colors */
  color: var(--ds-color-primary-500);
  background-color: var(--ds-color-bg);
  
  /* Spacing */
  padding: var(--ds-spacing-4) var(--ds-spacing-6);
  margin-bottom: var(--ds-spacing-3);
  
  /* Typography */
  font-size: var(--ds-font-size-lg);
  line-height: var(--ds-line-height-normal);
  
  /* Border radius */
  border-radius: var(--ds-radius-md);
  
  /* Shadows */
  box-shadow: var(--ds-shadow-sm);
}

JavaScript/TypeScript

Access tokens programmatically in your JavaScript or TypeScript:

// ESM Import
import { tokens, getToken, cssVariables } from '@winzenburg/tokens';

// CommonJS Import  
const { tokens, getToken, cssVariables } = require('@winzenburg/tokens');

// Access token values
console.log(tokens.color.primary[500]); // "#3b82f6"
console.log(tokens.spacing[4]); // "1rem"

// Type-safe token access
const primaryColor = getToken('color.primary.500'); // "#3b82f6"
const spacing = getToken('spacing.4'); // "1rem"

// Get CSS variable names
console.log(cssVariables.colorPrimary500); // "--ds-color-primary-500"
console.log(cssVariables.spacing4); // "--ds-spacing-4"

Token Categories

Colors

Brand Colors

--ds-color-primary-50   /* Lightest primary */
--ds-color-primary-100
--ds-color-primary-200
--ds-color-primary-300
--ds-color-primary-400
--ds-color-primary-500  /* Base primary */
--ds-color-primary-600
--ds-color-primary-700
--ds-color-primary-800
--ds-color-primary-900  /* Darkest primary */

Semantic Colors

--ds-color-bg           /* Background */
--ds-color-fg           /* Foreground text */
--ds-color-muted        /* Muted text */
--ds-color-accent       /* Accent color */
--ds-color-success      /* Success state */
--ds-color-warning      /* Warning state */
--ds-color-error        /* Error state */

Gray Scale

--ds-color-gray-50      /* Lightest gray */
--ds-color-gray-100
/* ... */
--ds-color-gray-900     /* Darkest gray */

Typography

/* Font Sizes */
--ds-font-size-xs       /* 0.75rem */
--ds-font-size-sm       /* 0.875rem */
--ds-font-size-md       /* 1rem */
--ds-font-size-lg       /* 1.125rem */
--ds-font-size-xl       /* 1.25rem */
--ds-font-size-2xl      /* 1.5rem */

/* Line Heights */
--ds-line-height-tight  /* 1.25 */
--ds-line-height-normal /* 1.5 */
--ds-line-height-loose  /* 1.75 */

/* Font Weights */
--ds-font-weight-normal /* 400 */
--ds-font-weight-medium /* 500 */
--ds-font-weight-bold   /* 700 */

Spacing

Based on a 0.25rem (4px) scale:

--ds-spacing-0    /* 0 */
--ds-spacing-1    /* 0.25rem - 4px */
--ds-spacing-2    /* 0.5rem - 8px */
--ds-spacing-3    /* 0.75rem - 12px */
--ds-spacing-4    /* 1rem - 16px */
--ds-spacing-5    /* 1.25rem - 20px */
--ds-spacing-6    /* 1.5rem - 24px */
--ds-spacing-8    /* 2rem - 32px */
--ds-spacing-10   /* 2.5rem - 40px */
--ds-spacing-12   /* 3rem - 48px */
--ds-spacing-16   /* 4rem - 64px */
--ds-spacing-20   /* 5rem - 80px */

Border Radius

--ds-radius-none  /* 0 */
--ds-radius-sm    /* 0.125rem */
--ds-radius-md    /* 0.375rem */
--ds-radius-lg    /* 0.5rem */
--ds-radius-xl    /* 0.75rem */
--ds-radius-full  /* 9999px */

Shadows

--ds-shadow-sm    /* Small shadow */
--ds-shadow-md    /* Medium shadow */
--ds-shadow-lg    /* Large shadow */
--ds-shadow-xl    /* Extra large shadow */

Theming

Light and Dark Themes

The tokens automatically support light and dark themes:

<!-- Light theme (default) -->
<div data-theme="light">
  <p>This uses light theme colors</p>
</div>

<!-- Dark theme -->
<div data-theme="dark">
  <p>This uses dark theme colors</p>
</div>

<!-- Automatic theme based on user preference -->
<div data-theme="auto">
  <p>This respects prefers-color-scheme</p>
</div>

Custom Themes

Override token values to create custom themes:

/* Custom brand theme */
.theme-custom {
  --ds-color-primary-500: #your-brand-color;
  --ds-color-primary-600: #your-darker-shade;
}

/* High contrast theme */
.theme-high-contrast {
  --ds-color-bg: #000000;
  --ds-color-fg: #ffffff;
  --ds-color-primary-500: #ffff00;
}

TypeScript Support

Full TypeScript support with autocomplete and type checking:

import { TokenPath, getToken } from '@winzenburg/tokens';

// Autocomplete available for all token paths
const color: string = getToken('color.primary.500');
const spacing: string = getToken('spacing.4');

// Type error for invalid paths
const invalid = getToken('invalid.path'); // ❌ TypeScript error

Examples

CSS Component

.button {
  /* Use semantic tokens when possible */
  background-color: var(--ds-color-primary-500);
  color: var(--ds-color-bg);
  
  /* Consistent spacing */
  padding: var(--ds-spacing-3) var(--ds-spacing-6);
  
  /* Consistent border radius */
  border-radius: var(--ds-radius-md);
  
  /* Consistent typography */
  font-size: var(--ds-font-size-md);
  font-weight: var(--ds-font-weight-medium);
  
  /* Consistent shadows */
  box-shadow: var(--ds-shadow-sm);
}

.button:hover {
  background-color: var(--ds-color-primary-600);
}

JavaScript Styling

import { tokens, cssVariables } from '@winzenburg/tokens';

const buttonStyles = {
  backgroundColor: `var(${cssVariables.colorPrimary500})`,
  padding: `var(${cssVariables.spacing3}) var(${cssVariables.spacing6})`,
  borderRadius: `var(${cssVariables.radiusMd})`,
  fontSize: `var(${cssVariables.fontSizeMd})`,
};

// Or with direct values (less flexible for theming)
const staticStyles = {
  backgroundColor: tokens.color.primary[500],
  padding: `${tokens.spacing[3]} ${tokens.spacing[6]}`,
};

Development

Token Source

Tokens are defined in src/tokens.json and built using our custom build system:

# Build tokens
npm run build

# Watch for changes
npm run dev

# Clean build artifacts
npm run clean

Token Structure

{
  "color": {
    "primary": {
      "500": "#3b82f6"
    },
    "bg": {
      "$value": "{color.neutral.50}",
      "$type": "color"
    }
  },
  "spacing": {
    "4": "1rem"
  }
}

Token references use the format {category.subcategory.token} and are automatically resolved during build.

Contributing

See the main Contributing Guide for development setup and contribution guidelines.

License

MIT © Your Organization