npm package: @folksam/ui-design-tokens
Description: 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 applica
Latest version: 1.2.1

# @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](https://styledictionary.com/) for scalable token management  
♿ **Accessibility Ready**: Color tokens meet WCAG contrast requirements

## Installation

```bash
# 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`:

```tsx
// 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:

```tsx
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)

```css
/* 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:

```tsx
// 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:

```tsx
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:

```tsx
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:

```tsx
// ✅ 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:

```tsx
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:

```tsx
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

```tsx
// 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

```tsx
// 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`](https://www.npmjs.com/package/@folksam/ui-components) - React component library
- [`@folksam/ui-styles`](https://www.npmjs.com/package/@folksam/ui-styles) - Utility styles and responsive helpers

---

**Built with ❤️ by the Folksam Design System Team**