design-tokens

name	design-tokens
description	Parameterized design token system. Dynamically generates CSS variables for colors, border-radius, spacing, and typography based on brand parameters.

Design Tokens

Purpose: UI design foundation layer that dynamically generates design variables from style parameters.

Core Value: Automatic mapping from style dimension values to concrete CSS variables.

---

Design Philosophy

Core Principle: Parameter-driven, not hardcoded presets.

Principle	Description
Parameter mapping	0-100 dimension values automatically convert to concrete CSS values
Transparent formulas	Mapping logic is clear and predictable
Fine-tunable	Generated values can still be manually adjusted
Backward compatible	Default values used when parameters are unspecified

---

Parameter to Token Mapping

Input: Style Parameters

interface DesignTokenInput {
  primaryHue?: number;       // 0-360 (HSL hue)
  mode?: "light" | "dark";   // Color mode
  density?: "compact" | "normal" | "spacious";  // Spacing density
  borderRadius?: "sharp" | "rounded" | "pill";  // Border radius style
}

Output: CSS Variables

:root {
  /* Colors */
  --color-primary: ...;
  --color-surface: ...;
  --color-text: ...;

  /* Spacing */
  --space-0 through --space-9: ...;

  /* Border Radius */
  --radius-sm: ...;
  --radius-md: ...;
  --radius-lg: ...;
  --radius-full: ...;

  /* Typography */
  --font-sans: ...;
  --font-mono: ...;
  --text-xs through --text-3xl: ...;

  /* Shadows */
  --shadow-sm through --shadow-xl: ...;
}

---

Mapping Formula Details

1. Color Palette Generation (primaryHue + mode → CSS)

function generatePalette(hue: number, dark: boolean) {
  // Generates 15 color tokens from a single hue value
  // Dark mode inverts lightness values
  // Complementary accent color at hue+30°
  return {
    '--color-bg': hsl(hue, saturation, lightness),
    '--color-surface': ...,
    '--color-primary': hsl(hue, 70, dark ? 55 : 45),
    '--color-accent': hsl((hue + 30) % 360, 60, ...),
    // ... 15 total color tokens
  };
}

2. Spacing Scale (density → CSS)

function generateSpacing(density: string) {
  // base: compact=4px, normal=6px, spacious=8px
  // scale multipliers: [0.25, 0.5, 1, 1.5, 2, 3, 4, 6, 8, 12]
  // Generates --space-0 through --space-9
}

Density	Base	--space-2	--space-4	--space-6
compact	4px	4px	12px	24px
normal	6px	6px	18px	36px
spacious	8px	8px	24px	48px

3. Border Radius (borderRadius → CSS)

Style	--radius-sm	--radius-md	--radius-lg	--radius-full
sharp	2px	4px	6px	8px
rounded	4px	8px	12px	9999px
pill	9999px	9999px	9999px	9999px

4. Typography (fixed, does not vary with parameters)

:root {
  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;

  --text-xs: 0.75rem;    /* 12px */
  --text-sm: 0.875rem;   /* 14px */
  --text-base: 1rem;     /* 16px */
  --text-lg: 1.125rem;   /* 18px */
  --text-xl: 1.25rem;    /* 20px */
  --text-2xl: 1.5rem;    /* 24px */
  --text-3xl: 2rem;      /* 32px */

  --line-height-tight: 1.25;
  --line-height-normal: 1.5;
  --line-height-relaxed: 1.75;
}

5. Shadows (mode → CSS)

Shadow opacity scales with light/dark mode:

function generateShadows(dark: boolean) {
  const opacity = dark ? 0.5 : 0.1;
  return {
    '--shadow-sm': `0 1px 2px rgba(0,0,0,${opacity})`,
    '--shadow-md': `0 4px 6px rgba(0,0,0,${opacity})`,
    '--shadow-lg': `0 10px 15px rgba(0,0,0,${opacity})`,
    '--shadow-xl': `0 20px 25px rgba(0,0,0,${opacity})`,
  };
}

---

Usage Examples

Generate from Parameters

import { express } from './index';

const result = await express({
  primaryHue: 220,       // Blue
  mode: 'dark',
  density: 'normal',
  borderRadius: 'rounded'
});

console.log(result.css);        // Full :root { ... } block
console.log(result.totalTokens); // Number of generated tokens

Use in Components

<button style="
  background: var(--color-primary);
  color: var(--color-primary-fg);
  border-radius: var(--radius-md);
  padding: var(--space-2) var(--space-4);
  font-family: var(--font-sans);
  font-size: var(--text-sm);
  box-shadow: var(--shadow-md);
">
  Button
</button>

---

Default Tokens

When no parameters are specified, defaults are used:

• primaryHue: 220 (blue)
• mode: "dark"
• density: "normal"
• borderRadius: "rounded"

This generates approximately 48 CSS custom properties covering colors, spacing, radii, typography, and shadows.

---

Tailwind CSS Integration

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: 'var(--color-primary)',
        'primary-hover': 'var(--color-primary-hover)',
        surface: 'var(--color-surface)',
        accent: 'var(--color-accent)',
      },
      borderRadius: {
        sm: 'var(--radius-sm)',
        DEFAULT: 'var(--radius-md)',
        lg: 'var(--radius-lg)',
        full: 'var(--radius-full)',
      },
    },
  },
}