/* Colors - Neutral */ --color-background: #ffffff; --color-surface: #f8fafc; --color-border: #e2e8f0; --color-text: #1e293b; --color-text-muted: #64748b;

/* Spacing Scale (4px base) / --space-1: 0.25rem; / 4px / --space-2: 0.5rem; / 8px / --space-3: 0.75rem; / 12px / --space-4: 1rem; / 16px / --space-5: 1.25rem; / 20px / --space-6: 1.5rem; / 24px / --space-8: 2rem; / 32px / --space-10: 2.5rem; / 40px / --space-12: 3rem; / 48px / --space-16: 4rem; / 64px */

/* Typography */ --font-sans: 'Inter', system-ui, sans-serif; --font-mono: 'JetBrains Mono', 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: 1.875rem; / 30px */

--leading-tight: 1.25; --leading-normal: 1.5; --leading-relaxed: 1.75;

--font-normal: 400; --font-medium: 500; --font-semibold: 600; --font-bold: 700;

/* Borders */ --radius-sm: 0.25rem; --radius-md: 0.375rem; --radius-lg: 0.5rem; --radius-xl: 0.75rem; --radius-full: 9999px;

/* Shadows */ --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05); --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1); --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);

/* Transitions */ --duration-fast: 150ms; --duration-normal: 250ms; --duration-slow: 350ms; --ease-default: cubic-bezier(0.4, 0, 0.2, 1); }


## Dark Mode

```css
[data-theme="dark"] {
  --color-primary: #3b82f6;
  --color-primary-hover: #60a5fa;
  
  --color-background: #0f172a;
  --color-surface: #1e293b;
  --color-border: #334155;
  --color-text: #f1f5f9;
  --color-text-muted: #94a3b8;
  
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.3);
  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.4);
}

Usage in Components

// Button.tsx
const buttonStyles: CSSProperties = {
  backgroundColor: 'var(--color-primary)',
  color: 'var(--color-background)',
  padding: 'var(--space-2) var(--space-4)',
  borderRadius: 'var(--radius-md)',
  fontSize: 'var(--text-sm)',
  fontWeight: 'var(--font-medium)',
  transition: `background-color var(--duration-fast) var(--ease-default)`,
};

/* Button.css */
.btn {
  background-color: var(--color-primary);
  color: var(--color-background);
  padding: var(--space-2) var(--space-4);
  border-radius: var(--radius-md);
  font-size: var(--text-sm);
  font-weight: var(--font-medium);
  transition: background-color var(--duration-fast) var(--ease-default);
}

.btn:hover {
  background-color: var(--color-primary-hover);
}

Token Naming Convention

--{category}-{property}-{variant}

Examples:
--color-primary
--color-primary-hover
--space-4
--text-lg
--radius-md
--shadow-lg

Component Token Mapping

Component	Tokens
Button	`--color-primary`, `--space-2/4`, `--radius-md`, `--text-sm`
Input	`--color-border`, `--space-2/3`, `--radius-md`, `--text-base`
Card	`--color-surface`, `--space-4`, `--radius-lg`, `--shadow-md`
Badge	`--color-*`, `--space-1/2`, `--radius-full`, `--text-xs`

Theme Provider Pattern

// ThemeProvider.tsx
type Theme = 'light' | 'dark' | 'system';

export const ThemeProvider: FC<{ children: ReactNode }> = ({ children }) => {
  const [theme, setTheme] = useState<Theme>('system');
  
  useEffect(() => {
    const root = document.documentElement;
    const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    const resolved = theme === 'system' ? (systemDark ? 'dark' : 'light') : theme;
    root.setAttribute('data-theme', resolved);
  }, [theme]);
  
  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
};

Best Practices

Use semantic names (--color-primary) over literal (--color-blue)
Define scales with consistent ratios (4px spacing, modular type)
Keep token count minimal but comprehensive
Document token purpose in comments
Test all tokens in both light/dark modes

css-tokens

CSS Design Tokens

Token Structure