@folksam/ui-design-tokens

A comprehensive design token system that provides consistent design values across all applications. These tokens define colors, typography, spacing, and other design properties, creating a scalable and maintainable visual foundation for modern web applications.

Features

✨ Design-to-Code Sync: Tokens exported directly from Figma 🎨 Comprehensive Token Library: Colors, typography, spacing, borders, shadows, and more
⚡ Multiple Output Formats: CSS variables, JavaScript objects, and JSON for maximum flexibility
📱 Theme Support: Built-in light/dark mode with extensible theming architecture
🎯 Type Safe: Full TypeScript support with comprehensive type definitions
🔧 Framework Agnostic: Works with any CSS framework or vanilla CSS
📚 Design System Integration: Powered by Style Dictionary for scalable token management
♿ Accessibility Ready: Color tokens meet WCAG contrast requirements

Installation

# Using npm
npm install @folksam/ui-design-tokens

# Using pnpm
pnpm add @folksam/ui-design-tokens

# Using yarn
yarn add @folksam/ui-design-tokens

Quick Start

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

// Import in your main CSS or index file
import '@folksam/ui-design-tokens/css/theme.css';

JavaScript/TypeScript Integration (Recommended)

For type-safe access to design tokens in your code:

import { theme } from '@folksam/ui-design-tokens';
import { css } from '@pigment-css/react';

const myComponent = css({
  backgroundColor: theme.background_primary,
  color: theme.text_primary,
  padding: theme.spacing_m,
  borderRadius: theme.radius_s,
});

CSS Variables (Not recommended)

/* Use CSS variables directly */
.my-component {
  background-color: var(--ui-background-primary);
  color: var(--ui-text-primary);
  padding: var(--ui-spacing-m);
  border-radius: var(--ui-radius-s);
}

Dark Mode Support

Automatic dark mode support with CSS custom properties:

// Tokens automatically adapt to theme
const component = css({
  backgroundColor: theme.background_primary, // Auto-switches
  color: theme.text_primary, // Auto-switches
  border: `1px solid ${theme.line_neutral_default}`,
});

// Manual dark mode detection
const themeAware = css({
  backgroundColor: theme.surface_neutral_amplified,

  '@media (prefers-color-scheme: dark)': {
    // Additional dark mode specific styles if needed
    boxShadow: 'none',
  },
});

Advanced Usage

Raw CSS Property Names

The theme object also provides access to raw CSS custom property names via theme.prop for advanced use cases:

import { theme } from '@folksam/ui-design-tokens';

// Regular usage with var() wrapper
const styles = css({
  color: theme.text_primary, // Returns: "var(--ui-text-primary)"
});

// Raw property names without var() wrapper
const rawProperty = theme.prop.text_primary; // Returns: "--ui-text-primary"

// Some possible use cases for raw properties:

// 1. JavaScript DOM manipulation
const element = document.querySelector('.my-element');
const currentColor = getComputedStyle(element).getPropertyValue(
  theme.prop.text_primary,
);
element.style.setProperty(theme.prop.background_primary, '#ffffff');

// 2. CSS var() with fallbacks
const stylesWithFallback = css({
  color: `var(${theme.prop.text_primary}, #333333)`,
  backgroundColor: `var(${theme.prop.background_primary}, #ffffff)`,
});

Custom Theme Extensions

Extend the token system with your own values:

import { theme } from '@folksam/ui-design-tokens';

// Create theme extensions
const customTheme = {
  ...theme,
  // Add custom tokens
  color_brand_gradient: 'linear-gradient(45deg, #ff6b6b, #4ecdc4)',
  spacing_custom: '1.25rem',
  animation_duration_slow: '0.5s',
};

const customComponent = css({
  background: customTheme.brand_gradient,
  padding: customTheme.spacing_custom,
  transition: `all ${customTheme.animation_duration_slow} ease`,
});

Token Validation

TypeScript ensures you only use valid tokens:

// ✅ Valid token usage
const validStyles = css({
  color: theme.text_primary, // Autocomplete works
  padding: theme.spacing_m, // Type-safe
});

// ❌ TypeScript error - invalid token
const invalidStyles = css({
  color: theme.invalid_token, // Error: Property doesn't exist
});

Conditional Theming

Apply different tokens based on conditions:

const getButtonStyles = (variant: 'primary' | 'secondary') =>
  css({
    padding: `${theme.spacing_s} ${theme.spacing_m}`,
    borderRadius: theme.radius_m,
    fontWeight: 'medium',

    ...(variant === 'primary' && {
      backgroundColor: theme.button_primary_surface,
      color: theme.button_primary_text,
      border: 'none',
    }),

    ...(variant === 'secondary' && {
      backgroundColor: 'transparent',
      color: theme.text_primary,
      border: `1px solid ${theme.line_neutral_default}`,
    }),
  });

Token Architecture

Design System Workflow

Figma Variables → Token Parser → Style Dictionary → Generated Outputs

1. Design Source: Tokens defined in Figma as variables and styles
2. Token Sync: Automated export via Figma API
3. Processing: Style Dictionary transforms tokens into multiple formats
4. Output Generation: CSS variables, JavaScript objects, and type definitions

Token Naming Convention

Tokens follow a hierarchical naming structure:

{category}_{property}_{variant?}_{state?}

Examples:

• color_background_primary - Background color, primary variant
• spacing_medium - Spacing token, medium size
• font_size_heading_large - Font size for large headings
• border_radius_small - Small border radius value

TypeScript Support

Comprehensive TypeScript integration:

import type {
  ColorTokens,
  SpacingTokens,
  TypographyTokens,
} from '@folksam/ui-design-tokens';

// Type-safe token access
const useThemeColors = (): ColorTokens => {
  // Implementation with full type safety
};

// Token validation
type ValidColorToken = keyof ColorTokens;
const getColorToken = (token: ValidColorToken) => theme[token];

Migration Guide

From Hard-coded Values

// Before: Magic numbers and hard-coded colors
const oldStyles = css({
  color: '#333333',
  backgroundColor: '#ffffff',
  padding: '16px 24px',
  borderRadius: '8px',
});

// After: Design tokens
const newStyles = css({
  color: theme.text_primary,
  backgroundColor: theme.background_primary,
  padding: `${theme.spacing_m} ${theme.spacing_l}`,
  borderRadius: theme.radius_m,
});

From CSS Variables

// Before: Manual CSS variables
const oldApproach = css({
  color: 'var(--text-color)',
  backgroundColor: 'var(--bg-color)',
});

// After: Type-safe theme object
const newApproach = css({
  color: theme.text_primary,
  backgroundColor: theme.background_primary,
});

Related Packages

• @folksam/ui-components - React component library
• @folksam/ui-styles - Utility styles and responsive helpers

Built with ❤️ by the Folksam Design System Team