@nice2dev/design-tokens

W3C Design Tokens implementation for Nice2Dev UI library.

Features

• 📋 W3C Design Tokens Format - Compliant with W3C Design Tokens Community Group
• 🎨 Multiple Output Formats - CSS, SCSS, JS, TypeScript, Tailwind
• 🌙 Theme Support - Light, dark, high-contrast modes
• 🔗 Token References - Reference tokens with {category.token} syntax
• 🧮 Computed Values - Auto-resolve references and composite tokens
• 🛠️ CLI Tool - Generate tokens from command line
• 📦 Programmatic API - Use in build scripts

Installation

npm install @nice2dev/design-tokens
# or
pnpm add @nice2dev/design-tokens

Quick Start

Using CLI

# Initialize a new tokens project
npx nice-tokens init

# Build tokens
npx nice-tokens build -i ./tokens -o ./dist -f css,scss,ts

# Watch mode
npx nice-tokens build --watch

Token Format (W3C)

{
  "color": {
    "$type": "color",
    "primary": {
      "500": {
        "$value": "#3b82f6",
        "$description": "Primary brand color"
      }
    }
  },
  "spacing": {
    "$type": "dimension",
    "md": {
      "$value": "1rem"
    }
  }
}

Using References

{
  "semantic": {
    "button": {
      "background": {
        "$value": "{color.primary.500}"
      }
    }
  }
}

API Usage

import { createGenerator } from '@nice2dev/design-tokens';

const generator = createGenerator({
  formats: ['css', 'ts'],
  outputDir: './dist',
  prefix: 'nice',
});

generator.loadDirectory('./tokens');
await generator.generate();

Token Types

| Type | Description | Example | | ------------- | ---------------- | ------------------------------ | | color | Color values | #3b82f6, rgb(59, 130, 246) | | dimension | Sizes, spacing | 1rem, 16px | | fontFamily | Font stacks | ["Inter", "sans-serif"] | | fontWeight | Font weights | 400, "bold" | | duration | Animation timing | 200ms, 0.3s | | cubicBezier | Easing curves | [0.4, 0, 0.2, 1] | | shadow | Box shadows | Complex object | | typography | Font shorthand | Complex object |

Output Formats

CSS

:root {
  --nice-color-primary-500: #3b82f6;
  --nice-spacing-md: 1rem;
}

TypeScript

export const tokens = {
  color: {
    primary: {
      '500': '#3b82f6',
    },
  },
  spacing: {
    md: '1rem',
  },
};

Tailwind

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          500: '#3b82f6',
        },
      },
    },
  },
};

Themes

The package supports multiple themes:

• light - Default light theme
• dark - Dark mode
• high-contrast - WCAG AAA compliant
• high-contrast-dark - High contrast dark mode
• dim - Reduced brightness mode

Theme Switcher

<script src="./dist/theme-switcher.js"></script>
<script>
  // Set theme
  setTheme('dark');

  // Toggle between light/dark
  toggleTheme();

  // Use system preference
  useSystemTheme();
</script>

React Theme Provider

import { ThemeProvider, useTheme } from '@nice2dev/design-tokens/ThemeContext';

function App() {
  return (
    <ThemeProvider>
      <MyComponent />
    </ThemeProvider>
  );
}

function MyComponent() {
  const { theme, setTheme, toggleTheme } = useTheme();

  return <button onClick={toggleTheme}>Current: {theme}</button>;
}

CLI Commands

# Build tokens
nice-tokens build [options]
  -i, --input <dir>     Input directory (default: ./tokens)
  -o, --output <dir>    Output directory (default: ./dist)
  -f, --formats <list>  Output formats (css,scss,js,ts,json,tailwind)
  -p, --prefix <str>    CSS variable prefix (default: nice)
  --separate            Generate separate files by category
  --watch               Watch for changes

# Initialize project
nice-tokens init [-d <dir>]

# Validate token files
nice-tokens validate <files...>
nice-tokens validate -d ./tokens

# Convert formats
nice-tokens convert <input> <output> -f <format>

# Show token info
nice-tokens info <dir>

# Compare tokens
nice-tokens diff <source> <target>

License

MIT © Nice2Dev