@dankupfer/dn-tokens

⚠️ EXPERIMENTAL - NOT FOR PRODUCTION USE

This package is experimental and under active development. APIs are subject to breaking changes without notice. Not recommended for production applications.

Status

• 🚧 Pre-alpha: APIs will change frequently
• ❌ No semantic versioning: Breaking changes may occur in any version
• 🔬 Research project: Used for prototyping and experimentation

Design tokens and assets for the DN design system. This package provides a centralized source of truth for colors, typography, spacing, icons, and fonts used across DN projects with comprehensive brand and theme support.

Features

• 🎨 Comprehensive Design Tokens - Advanced token system with 15+ brand variants
• 🏢 Multi-Brand Support - Lloyds, Halifax, BOS, MBNA, Scottish Widows with light/dark variants
• 🌓 Advanced Theme Processing - Sophisticated light/dark mode handling through brand variants
• 🔤 Font Assets - GT-Ultra font family files
• 🎯 TypeScript Support - Full type safety for all tokens and processing functions
• 🖼️ SVG Icon System - Brand-specific icons with light/dark variants
• 🔧 Advanced Token Processor - Utilities for typography, shadows, and complex token types

Installation

npm install @dankupfer/dn-tokens

Quick Start

import { processTokens, getAllTokens, getAllIcons, type Token } from '@dankupfer/dn-tokens';

// Get all tokens
const tokens: Token[] = getAllTokens();

// Process tokens for a specific brand
const lightTheme = processTokens(tokens, 'lloyds', 'light');
const darkTheme = processTokens(tokens, 'reimaginedLloydsDark', 'dark');

// Access processed theme values
console.log(lightTheme.colors.action.background);
console.log(lightTheme.spacing.md);
console.log(lightTheme.typography.body.fontSize);

// Get all icons
const icons = getAllIcons();

Available Brands

The token system supports comprehensive brand coverage:

Core Brands

• lloyds - Lloyds Bank standard theme
• halifax - Halifax brand theme
• bos - Bank of Scotland theme
• mbna - MBNA brand theme
• scottishWidows - Scottish Widows theme

Reimagined Variants

• reimaginedLloyds / reimaginedLloydsDark - Modern Lloyds themes
• reimaginedBos / reimaginedBosDark - Modern Bank of Scotland themes
• reimaginedHalifax / reimaginedHalifaxDark - Modern Halifax themes
• reimaginedMbna / reimaginedMbnaDark - Modern MBNA themes
• reimaginedScottishWidows / reimaginedScottishWidowsDark - Modern Scottish Widows themes

Advanced Token System

Token Structure

Each token follows a comprehensive structure supporting multiple brands and complex value types:

interface Token {
  name: string;
  type: 'color' | 'spacing' | 'borderRadius' | 'borderWidth' | 'typography' | 'shadow';
  description?: string;
  values: {
    [brandKey: string]: string | TypographyValue | ShadowValue;
  };
}

Token Processing

import { 
  processTokens, 
  getToken, 
  getTypographyToken, 
  getShadowToken,
  type ProcessedTheme 
} from '@dankupfer/dn-tokens';

const tokens = getAllTokens();

// Process into runtime theme
const theme: ProcessedTheme = processTokens(tokens, 'lloyds', 'light');

// Direct token access
const backgroundColor = getToken('background_page_default', 'lloyds', 'light', tokens);
const spacing = getNumericToken('spacing_size_16', 'lloyds', 'light', tokens);

// Complex token types
const typography = getTypographyToken('style_3', 'lloyds', 'light', tokens);
const shadow = getShadowToken('shadow_default', 'lloyds', 'light', tokens);

Processed Theme Structure

The ProcessedTheme provides structured access to common design patterns:

interface ProcessedTheme {
  // Direct token access
  tokens: { [tokenName: string]: string | number };
  
  // Structured convenience accessors
  colors: {
    action: {
      background: string;
      backgroundPressed: string;
      backgroundDisabled: string;
      text: string;
      border: string;
    };
    brandAccent: { background: string; backgroundPressed: string; text: string; };
    page: { background: string; };
    panel: { background: string; };
    text: { default: string; subdued: string; };
    border: { default: string; action: string; };
  };
  
  spacing: { xs: number; sm: number; md: number; lg: number; };
  borderRadius: { button: number; };
  borderWidth: { button: number; };
  typography: {
    heading: number;
    body: { fontSize: number; fontFamily: string; };
    small: number;
  };
}

Icon System

Advanced SVG icon system with brand and theme variants:

import { getAllIcons } from '@dankupfer/dn-tokens';

const icons = getAllIcons();

// Icons are organized by category and support brand/theme variants
const depositIcon = icons['icons|finance|deposit'];
const lloydLightIcon = depositIcon.lloyds.light; // SVG string
const lloydDarkIcon = depositIcon.lloyds.dark;   // SVG string

Icon Categories

• Finance: icons|finance|deposit, icons|finance|cashpoint, icons|finance|cheque
• Components: components|size|compact, components|size|default
• Navigation: Icons for common UI patterns
• Brand-specific: Custom icons per brand

Icon Resolver Utility

The package includes a powerful icon resolution system that maps simple names to full icon paths:

import { resolveIcon, addIconMapping, getAvailableIconNames } from '@dankupfer/dn-tokens';

// Simple name resolution
const homePath = resolveIcon('home'); // Returns 'icons|navigation|home'
const settingsPath = resolveIcon('settings'); // Returns 'icons|miscellaneous|settings'

// Full paths pass through unchanged
const fullPath = resolveIcon('icons|finance|deposit'); // Returns 'icons|finance|deposit'

// Get all available simple names
const availableNames = getAvailableIconNames(); // ['home', 'settings', 'cards', ...]

// Extend mappings at runtime
addIconMapping('custom-icon', 'icons|custom|my_icon');

Features:

• Simple name mapping - Use friendly names like 'home' instead of 'icons|navigation|home'
• Fallback support - Full paths work unchanged for advanced usage
• Runtime extension - Add custom mappings with addIconMapping()
• Development helpers - getAvailableIconNames() for debugging and discovery

Available Simple Names:

• Navigation: home, back, close, search, menu
• Actions: settings, notification, help, plus, minus, tick
• Arrows: chevron-left, chevron-right, arrow-left, arrow-right
• Finance: cards, wallet, payments, apply, bank
• Communication: phone, email, chat, message
• Security: lock, unlock, shield, key
• Sentiment: success, error, warning, info
• Miscellaneous: star, calendar, clock, camera, printer

The IconResolver bridges the gap between developer-friendly naming and the structured token system, allowing both simple usage (resolveIcon('home')) and advanced control (resolveIcon('icons|navigation|home')).

Typography System

Comprehensive typography support with complex font definitions:

interface TypographyValue {
  font_family: string;
  default_font_size: string;
  max_font_size: string;
  font_weight: string;
  line_height: string;
  line_spacing: string;
  letter_spacing: string;
  ios_classification: string;
}

// Access typography tokens
const bodyTypography = getTypographyToken('style_3', 'lloyds', 'light', tokens);
console.log(bodyTypography?.font_family); // GT-Ultra-Standard-Regular
console.log(bodyTypography?.default_font_size); // 17

Font Assets

The package includes GT-Ultra font files and a React Native font loading component:

@dankupfer/dn-tokens/fonts/
├── GT-Ultra-Standard-Regular.ttf
├── GT-Ultra-Standard-Bold.ttf
├── GT-Ultra-Median-Regular.ttf
└── GT-Ultra-Median-Bold.ttf

Font Loading Component

The package provides a ready-to-use FontLoader component that automatically loads all GT-Ultra fonts:

import { FontLoader } from '@dankupfer/dn-tokens';

export default function App() {
  return (
    <FontLoader>
      {/* Your app content - fonts will be loaded automatically */}
      <YourAppContent />
    </FontLoader>
  );
}

Features:

• Automatically loads all GT-Ultra font variants
• Handles loading states and errors gracefully
• Uses expo-font under the hood
• Children render only after fonts are loaded (or on error)
• Console logging for debugging font loading issues

Font Constants

import { fontFamilies, type FontFamily } from '@dankupfer/dn-tokens';

// Available font families
const fonts = {
  primary: "GT-Ultra-Median-Regular",
  primaryBold: "GT-Ultra-Median-Bold", 
  primarySemiBold: "GT-Ultra-Standard-Bold",
  secondary: "GT-Ultra-Standard-Regular",
};

Alternative Font Loading

If you prefer to implement your own font loading strategy, you can import the font assets directly and use your preferred loading solution:

// Manual font loading approach
import * as Font from 'expo-font';

const loadFonts = async () => {
  await Font.loadAsync({
    "GT-Ultra-Standard-Regular": require('@dankupfer/dn-tokens/fonts/GT-Ultra-Standard-Regular.ttf'),
    // ... other fonts
  });
};

Usage Examples

Basic Theme Creation

import { processTokens, getAllTokens } from '@dankupfer/dn-tokens';

const createTheme = (brand: string, mode: 'light' | 'dark') => {
  const tokens = getAllTokens();
  const brandName = mode === 'dark' ? `${brand}Dark` : brand;
  return processTokens(tokens, brandName as any, mode);
};

// Create themes
const lloydLight = createTheme('lloyds', 'light');
const lloydDark = createTheme('reimaginedLloyds', 'dark');

Component Integration

import { useTheme } from 'your-app';
import { getToken, getAllTokens } from '@dankupfer/dn-tokens';

const MyComponent = () => {
  const tokens = getAllTokens();
  const backgroundColor = getToken('background_panel_default', 'lloyds', 'light', tokens);
  
  return (
    <View style={{ backgroundColor }}>
      {/* Component content */}
    </View>
  );
};

TypeScript Support

Comprehensive TypeScript definitions:

import type { 
  Token,
  ProcessedTheme,
  BrandName,
  ThemeMode,
  TypographyValue,
  ShadowValue,
  FontFamily
} from '@dankupfer/dn-tokens';

// Type-safe brand selection
const brandName: BrandName = 'lloyds';
const themeMode: ThemeMode = 'light';

// Fully typed theme processing
const tokens: Token[] = getAllTokens();
const theme: ProcessedTheme = processTokens(tokens, brandName, themeMode);

Integration with Other Projects

This package is designed to be consumed by:

• dn-component-library - React Native component library
• dn-starter-kit - React Native application templates

Example integration:

// In your component library or app
import { processTokens, getAllTokens } from '@dankupfer/dn-tokens';

export const createAppTheme = (brand: string, mode: 'light' | 'dark') => {
  const tokens = getAllTokens();
  return processTokens(tokens, brand as any, mode);
};

Token File Management

Important: The core token and icon files (tokens/tokens.json and tokens/icons.json) are managed locally due to security requirements and are not included in the published package or git repository.

Local Development Setup

# Clone the repository
git clone <repository-url>
cd dn-tokens

# Add your token files locally (not committed to git)
# tokens/tokens.json - Your comprehensive token array
# tokens/icons.json - Your SVG icon definitions

npm install
npm run build

The package structure expects these files to be present locally:

• tokens/tokens.json - Complete token definitions for all brand variants
• tokens/icons.json - SVG icon definitions with brand and theme support

These files are in .gitignore to prevent accidental commits of sensitive design system data.

Project Structure

@dankupfer/dn-tokens/
├── src/                          # TypeScript source files
│   ├── index.ts                  # Main entry point with all exports
│   └── tokenProcessor.ts         # Advanced token processing utilities
├── tokens/                       # Design token files (local only)
│   ├── tokens.json              # Comprehensive token array (not in git)
│   └── icons.json               # SVG icon definitions (not in git)
├── fonts/                        # Font asset files
│   └── *.ttf                    # GT-Ultra font family
├── dist/                         # Compiled JavaScript (generated)
├── .gitignore                    # Excludes token files
└── package.json

Development

Building

npm run build

Development with Watch Mode

npm run dev

Publishing

npm run build
npm publish

Migration Notes

v1.1.0+ introduces a comprehensive token system replacing the previous simple brand-based approach:

• Before: Simple brand files (lloyds.json, brandA.json, brandB.json)
• After: Comprehensive token array with 15+ brand variants
• Before: Basic getBrandTokens() function
• After: Advanced processing with getToken(), getTypographyToken(), getShadowToken()

Contributing

1. Clone the repository
2. Install dependencies: npm install
3. Make your changes
4. Build and test: npm run build
5. Submit a pull request