Design Tokens

Design tokens are the single source of truth for visual design decisions — colors, spacing, typography, and more. They ensure consistency across all components and applications.

Token Architecture

primitives.json          → Raw values (colors, sizes, fonts)
    ↓ Style Dictionary
semantic/light.json      → Contextual meanings (light theme)
semantic/dark.json       → Contextual meanings (dark theme)
    ↓ Build
tokens.css               → CSS Variables (:root + [data-theme])
tokens.d.ts              → TypeScript constants

Token Categories

Colors

Token	Light	Dark	Usage
--color-primary	#4F46E5	#818CF8	Primary actions, links
--color-bg-primary	#FFFFFF	#0F0F19	Page background
--color-text-primary	#111827	#F9FAFB	Primary text
--color-border	#E5E7EB	#374151	Borders, dividers
--color-success	#059669	#34D399	Success states
--color-danger	#DC2626	#F87171	Error states
--color-warning	#D97706	#FBBF24	Warning states

Spacing

Based on a 4px grid:

Token	Value	Usage
--spacing-1	4px	Tight gaps
--spacing-2	8px	Default padding
--spacing-3	12px	Component padding
--spacing-4	16px	Section gaps
--spacing-6	24px	Card padding
--spacing-8	32px	Section spacing

Typography

Token	Value	Usage
--font-family-sans	Inter, system-ui	Body text
--font-family-mono	JetBrains Mono	Code
--font-size-xs	0.75rem	Captions
--font-size-sm	0.875rem	Secondary text
--font-size-base	1rem	Body text
--font-size-lg	1.125rem	Emphasis
--font-size-xl	1.25rem	Headings

Using Tokens

In CSS Modules

/* Button.module.css */
.button {
  background: var(--color-primary);
  padding: var(--spacing-2) var(--spacing-4);
  font-family: var(--font-family-sans);
  border-radius: var(--radius-md);
}

In Inline Styles

<div style={{ padding: 'var(--spacing-4)', color: 'var(--color-text-primary)' }}>
  Content
</div>

Token Format (W3C Draft)

Tokens follow the W3C Design Tokens Community Group draft specification:

{
  "color": {
    "primary": {
      "$value": "#4F46E5",
      "$type": "color",
      "$description": "Primary brand color"
    }
  }
}

Package

pnpm add @kikumi3n/tokens

// Import CSS Variables
import '@kikumi3n/tokens/css';

// Import TypeScript constants (optional)
import { tokens } from '@kikumi3n/tokens';