Design Tokens

Tokens are the single source of truth for Fortune Kit's visual language.

What Are Tokens?

Design tokens are named values representing design decisions:

// A token
colors.win.DEFAULT = '#22c55e'

// Not a token (magic value)
color: '#22c55e'

Token Categories

Colors

import { colors } from '@fortune-kit/tokens'

colors.background.DEFAULT  // '#09090b'
colors.primary.500         // '#f59e0b' (gold)
colors.win.DEFAULT         // '#22c55e' (green)
colors.lose.DEFAULT        // '#ef4444' (red)
colors.info.DEFAULT        // '#3b82f6' (blue)

Typography

import { typography } from '@fortune-kit/tokens'

typography.fontFamily.sans     // ['Inter', 'system-ui', ...]
typography.fontSize.xl         // ['1.25rem', { lineHeight: '1.75rem' }]
typography.fontWeight.bold     // '700'

Spacing

import { spacing } from '@fortune-kit/tokens'

spacing[4]   // '1rem'
spacing[8]   // '2rem'
spacing[16]  // '4rem'

Motion

import { motion } from '@fortune-kit/tokens'

motion.duration.fast     // '100ms'
motion.duration.normal   // '200ms'
motion.easing.bounce     // 'cubic-bezier(0.68, -0.55, 0.265, 1.55)'
motion.easing.spin       // 'cubic-bezier(0.25, 0.1, 0.25, 1)'

Using Tokens

CSS Variables

Import the CSS file to get all tokens as custom properties:

import '@fortune-kit/tokens/css'

Then use in CSS:

.my-component {
  background: var(--fk-color-background-DEFAULT);
  color: var(--fk-color-win-DEFAULT);
  padding: var(--fk-space-4);
  transition: all var(--fk-duration-normal) var(--fk-ease-easeOut);
}

TypeScript

Import and use with full type safety:

import { colors, type Colors } from '@fortune-kit/tokens'

function getResultColor(isWin: boolean): string {
  return isWin ? colors.win.DEFAULT : colors.lose.DEFAULT
}

Dynamic Theming

Override tokens at runtime:

:root {
  /* Default Fortune Kit gold */
  --fk-color-primary-DEFAULT: #f59e0b;
}

/* Custom brand purple */
.theme-purple {
  --fk-color-primary-DEFAULT: #a855f7;
}

Semantic vs Primitive

Fortune Kit uses semantic token names:

// ✅ Semantic - describes purpose
colors.win.DEFAULT
colors.lose.DEFAULT

// ❌ Primitive - describes value
colors.green500
colors.red500

This allows theming without changing component code.