Design Tokens

Design Tokens

Design tokens are the foundational elements of the Vanilla Design System. They represent the smallest pieces of our design language - colors, typography, spacing, and more.

Token Structure

Our tokens include:

  • Color scales - 12-step scales for consistent color usage
  • Typography - Font families, sizes, weights, and line heights
  • Spacing - Consistent spacing scale
  • Shadows - Elevation system
  • Animation - Duration and easing tokens

Color System

Our color system uses 12-step scales from the @beauginbey/vanilla-colors package:

// Colors are available as CSS variables
var(--gray-1)  // App background
var(--gray-7)  // UI element border
var(--gray-12) // High-contrast text
 
var(--blue-9)  // Solid button background
var(--blue-10) // Hovered solid background

Each color step has a specific purpose:

  • Steps 1-5: Backgrounds
  • Steps 6-8: Borders
  • Steps 9-10: Solid colors
  • Steps 11-12: Text

See the Theming page for more details on the color system.

Typography

// Font families
tokens.font.family.sans
tokens.font.family.mono
 
// Font sizes
tokens.font.size.xs  // 0.75rem
tokens.font.size.sm  // 0.875rem
tokens.font.size.base // 1rem
tokens.font.size.lg  // 1.125rem
 
// Font weights
tokens.font.weight.normal // 400
tokens.font.weight.medium // 500
tokens.font.weight.bold   // 700

Spacing

tokens.spacing[0]  // 0
tokens.spacing[1]  // 0.25rem
tokens.spacing[2]  // 0.5rem
tokens.spacing[4]  // 1rem
tokens.spacing[8]  // 2rem
tokens.spacing[16] // 4rem

Border Radius

tokens.radius.none // 0
tokens.radius.sm   // 0.125rem
tokens.radius.base // 0.25rem
tokens.radius.lg   // 0.5rem
tokens.radius.full // 9999px

Using Tokens

In Components

import { vars } from '@beauginbey/vanilla-components';
 
const styles = {
  backgroundColor: vars.color.background.primary,
  color: vars.color.text.primary,
  padding: vars.spacing[4],
  borderRadius: vars.radius.lg,
};

In CSS

.my-component {
  background-color: var(--color-background-primary);
  color: var(--color-text-primary);
  padding: var(--spacing-4);
  border-radius: var(--radius-lg);
}

Customizing Tokens

While our tokens provide a solid foundation, you may need to customize them for your brand. You can override tokens at the theme level:

import { createTheme } from '@vanilla-extract/css';
import { vars } from '@beauginbey/vanilla-components';
 
export const customTheme = createTheme(vars, {
  color: {
    brand: {
      primary: '#your-brand-color',
      secondary: '#your-secondary-color',
    },
  },
  font: {
    family: {
      sans: '"Your Font", system-ui, sans-serif',
    },
  },
});

Token Categories

Color Tokens

  • Background colors
  • Text colors
  • Border colors
  • Brand colors
  • Feedback colors (success, warning, error, info)

Typography Tokens

  • Font families
  • Font sizes
  • Font weights
  • Line heights
  • Letter spacing

Spacing Tokens

  • Consistent spacing scale from 0 to 24
  • Used for padding, margin, and gap

Visual Tokens

  • Border radius values
  • Shadow definitions
  • Transition durations
  • Z-index values

Best Practices

  1. Always use semantic tokens when available instead of primitive tokens
  2. Maintain consistency by using the spacing scale for all spacing needs
  3. Respect the type scale for hierarchy and readability
  4. Use feedback colors for their intended purpose
  5. Test with both themes to ensure your designs work in all contexts
Understanding the ScaleTheming