DN Component Library

⚠️ Not Recommended for Production: This component library is experimental and not recommended for any production work. APIs and component interfaces are subject to breaking changes without notice.

A comprehensive React Native component library built with TypeScript, featuring a modular design system with theme support, custom fonts, and Storybook documentation. Powered by dn-tokens for centralized design tokens.

Features

• 🎨 Comprehensive Theme System - Light/dark mode support with brand customization
• 🎯 Centralized Design Tokens - Uses dn-tokens package for consistent theming across projects
• 📱 React Native Components - Cross-platform components for iOS, Android, and Web
• 🔤 Custom Fonts - GT-Ultra font family integration with automatic loading
• 📚 Storybook Integration - Interactive component documentation and testing
• 🎯 TypeScript Support - Full type safety and IntelliSense support
• 🧩 Modular Architecture - Import only what you need
• 📄 JSON-Driven Screens - Build complete screens from JSON configuration with ScreenBuilder

Installation

npm install dn-components

Dependencies

This library requires the following peer dependencies:

npm install react react-native react-native-svg expo-font dn-tokens

Note: This library uses dn-tokens for design tokens. The tokens package provides centralized color, typography, spacing, and icon definitions shared across DN projects.

Quick Start

import React from 'react';
import { ThemeProvider, Tile, ActionButton, Tabs, ScreenBuilder } from 'dn-components';

export default function App() {
  const [activeTab, setActiveTab] = useState(0);
  
  const screenConfig = {
    scrollable: true,
    components: [
      {
        type: 'SectionHeader',
        props: { title: 'Your Accounts' }
      },
      {
        type: 'AccountCard',
        props: {
          id: 'my-account',
          title: 'Club Lloyds',
          subtitle: '12-34-56 / 12345678',
          accountNumber: '12-34-56 / 12345678',
          balance: 935.68,
          variant: 'condensed',
        }
      }
    ]
  };
  
  return (
    <ThemeProvider initialTheme="light" initialBrand="lloyds">
      <ScreenBuilder 
        config={screenConfig}
        screenWidth={400}
      />
      
      <Tabs 
        tabs={[
          { id: 'summary', title: 'Summary' },
          { id: 'everyday', title: 'Everyday' },
          { id: 'cards', title: 'Cards' },
        ]}
        activeTab={activeTab}
        scrollProgress={activeTab}
        onTabPress={setActiveTab}
        screenWidth={400}
      />
      
      <ActionButton type="Primary">
        Get Started
      </ActionButton>
    </ThemeProvider>
  );
}

Design System Integration

This component library is part of the DN design system and uses the centralized dn-tokens package for all design tokens:

• Colors: Primary, neutral, semantic colors with light/dark variants
• Typography: Font families, sizes, and text styles from GT-Ultra font family
• Spacing: Consistent spacing scale across all components
• Icons: SVG icon definitions with brand-specific variants
• Fonts: GT-Ultra font assets loaded automatically

For more details about the design tokens, see the dn-tokens repository.

Theme System

The component library uses a comprehensive theme system that supports multiple brands and light/dark modes with token-based architecture.

ThemeProvider

Wrap your application with the ThemeProvider to enable theming:

import { ThemeProvider } from 'dn-components';

<ThemeProvider 
  initialTheme="light"
  initialBrand="lloyds"
>
  {/* Your app content */}
</ThemeProvider>

Using Theme in Components

import { useTheme } from 'dn-components';

const MyComponent = () => {
  const { theme, themeName, brandName, toggleTheme, setBrand } = useTheme();
  
  return (
    <View style={{ backgroundColor: theme.colors.background }}>
      <Text style={{ color: theme.colors.text }}>
        Current theme: {themeName} ({brandName})
      </Text>
      <Button onPress={() => setBrand('brandA')}>
        Switch to Brand A
      </Button>
    </View>
  );
};

Available Theme Properties

• Colors: Primary, neutral, semantic colors with light/dark variants
• Typography: Font families, sizes, and text styles
• Spacing: Consistent spacing scale
• Border Radius: Standardized border radius values
• Brand Support: Multiple brand configurations (lloyds, brandA, brandB)

Icon Resolution System

The component library integrates with the dn-tokens icon resolution system for simplified icon usage. Import the resolver utilities from dn-tokens:

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

// Simple name resolution
const iconPath = resolveIcon('home'); // Returns 'icons|navigation|home'

// Use with Icon component
<Icon name={resolveIcon('settings')} />

// Or let Icon component handle resolution automatically
<Icon name="settings" /> // Icon component uses resolveIcon internally

// Get all available simple names for development
const availableIcons = getAvailableIconNames();
console.log('Available icons:', availableIcons);

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

Available Simple Icon 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

Components

Helper Components

ScreenBuilder

A powerful dynamic screen builder that renders complete screens from JSON configuration. Perfect for rapid prototyping, content management, and creating consistent layouts without writing component code.

import { ScreenBuilder } from 'dn-components';

const screenConfig = {
  scrollable: true,
  components: [
    {
      type: 'SectionHeader',
      props: { title: 'Your Accounts' }
    },
    {
      type: 'AccountCard',
      props: {
        id: 'account-1',
        title: 'Current Account',
        balance: 1234.56,
        variant: 'condensed'
      }
    },
    {
      type: 'ServiceGrid',
      props: {
        id: 'quick-actions',
        items: [
          {
            id: 'transfer',
            title: 'Transfer',
            description: 'Move money',
            icon: { name: 'wallet', color: '#006a4e' },
            onPress: () => console.log('Transfer pressed')
          }
        ]
      }
    }
  ]
};

<ScreenBuilder 
  config={screenConfig}
  screenWidth={screenWidth}
/>

Key Features:

• JSON-Driven: Define entire screens using simple JSON configuration
• Component Registry: Maps JSON types to actual React components
• Tile Integration: Built-in support for all Tile component types
• Scrollable/Fixed: Configure whether screens should scroll or have fixed height
• Custom Styling: Apply custom styles to both screen container and individual components
• Token-Based Theming: Uses design tokens for consistent styling across themes

Available Component Types:

• AccountCard - Bank account displays (variant: 'condensed' | 'detailed')
• CreditCard - Credit card information with balances and details
• ServiceCard - Service tiles with icons and descriptions
• ServiceGrid - 2x2 grids of service items
• PromotionalCard - Marketing and promotional content
• SectionHeader - Text headers for organizing content
• AnimatedHorse - Placeholder for animated content

HiddenDevMenu

A completely invisible developer menu activated by secret gestures. Perfect for production apps where you need access to developer tools without cluttering the main UI.

import { HiddenDevMenu, FlagManager, FlagProvider } from 'dn-components';

const developerFlags = {
  experimental: {
    name: 'Experimental Features',
    flags: {
      newDashboard: { 
        name: 'New Dashboard', 
        description: 'Beta version of redesigned dashboard',
        enabled: false, 
        persist: true 
      }
    }
  },
  development: {
    name: 'Development Tools',
    flags: {
      debugMode: {
        name: 'Debug Mode',
        description: 'Show debug information and logs',
        enabled: true,
        persist: true
      }
    }
  }
};

const DeveloperSettings = ({ flagConfig, onClose }) => (
  <ScrollView>
    <Text style={{ fontSize: 24, fontWeight: 'bold' }}>Developer Settings</Text>
    <FlagProvider>
      <FlagManager config={flagConfig} />
    </FlagProvider>
    <Button onPress={onClose}>Close</Button>
  </ScrollView>
);

<HiddenDevMenu 
  flagConfig={developerFlags}
  Settings={DeveloperSettings}
>
  <YourApp />
</HiddenDevMenu>

Key Features:

• Secret Gesture Access: Long press corners + tap sequence to access menu
• Invisible Integration: No UI changes to your app - completely hidden
• FlagManager Integration: Built-in support for feature flag management
• Development Mode: Skip gestures during development with devSkipClicks={true}
• Debug Visualization: Optional showDebugZones={true} for development
• Container-Aware: Works in both full apps and constrained environments

Gesture Sequence:

1. Long press any top corner for 0.8 seconds to activate
2. Tap left edge 3 times quickly
3. Tap right edge 3 times quickly
4. Developer menu opens

Props:

• flagConfig: FlagConfig - Feature flag configuration for your Settings component
• Settings: React.FC - Your custom settings component
• devSkipClicks?: boolean - Skip gesture sequence (development only)
• showDebugZones?: boolean - Show colored debug overlays
• children: ReactNode - Your app content

FlagManager

Simple feature flag management for development and testing with persistence support.

import { FlagManager, FlagProvider } from 'dn-components';

const flagConfig = {
  experimental: {
    name: 'Experimental Features',
    flags: {
      bottomNav2: {
        name: 'Bottom Nav 2.0',
        description: 'New bottom navigation component',
        enabled: false,
        persist: true
      }
    }
  }
};

<FlagProvider>
  <FlagManager config={flagConfig} />
</FlagProvider>

Features:

• Toggle experimental features on/off
• Persistent flags remember state across app restarts
• Non-persistent flags reset to default values
• Organized by categories for better management

ThemeSwitcher

Developer tool for switching between themes and brands during development.

import { ThemeSwitcher } from 'dn-components';

<ThemeSwitcher />

Features:

• Switch between light/dark themes
• Change brand configurations
• Real-time theme preview
• Development and testing tool

Navigation Components

Header

A flexible header component for navigation and page headers with configurable actions, variants, and notification support.

import { Header } from 'dn-components';

<Header 
  title="Settings"
  leftAction={{ type: 'back', onPress: () => navigation.goBack() }}
  rightActions={[
    { type: 'notification', notificationCount: 5, onPress: () => {} }
  ]}
/>

Features:

• Multiple variants: default (with shadow), modal, and dark themes
• Flexible actions: Configurable left and right side buttons
• Notification support: Built-in notification badge integration
• Status bar aware: Automatic spacing for device status bars
• Token integration: Uses design tokens for consistent theming

Tabs

A horizontal tabs component with animated sliding background for section navigation.

import { Tabs } from 'dn-components';

<Tabs 
  tabs={[
    { id: 'summary', title: 'Summary' },
    { id: 'everyday', title: 'Everyday' },
    { id: 'cards', title: 'Cards' },
    { id: 'apply', title: 'Apply' },
  ]}
  activeTab={0}
  scrollProgress={0}
  onTabPress={(index) => setActiveTab(index)}
  screenWidth={screenWidth}
/>

Features:

• Smooth animations - Sliding background that follows user interaction
• Touch/drag support - Responds to both taps and drag gestures
• Token integration - Uses design tokens for consistent theming
• Customizable dimensions - Configurable tab width, height, spacing, and border radius
• Accessibility support - Screen reader support and proper focus management
• Performance optimized - Uses native driver for smooth 60fps animations

Action Components

ActionButton

A versatile button component with multiple variants and states.

import { ActionButton, ButtonType } from 'dn-components';

<ActionButton 
  type={ButtonType.Primary}
  icon={true}
  onClick={() => console.log('Clicked!')}
>
  Primary Button
</ActionButton>

Props:

• type: Primary, Secondary, or Tertiary
• brandAccent: Boolean for brand accent styling
• icon: Show/hide chevron icon
• disabled: Disable the button
• iconRight: Position icon on right (default) or left

CompactButton & IconButton

Specialized button variants for specific use cases.

Content Components

Tile Component

The Tile component is a versatile container for displaying financial and informational content. It supports multiple variants and layouts optimized for banking applications.

Overview

The Tile component provides a consistent way to display different types of content:

• Account tiles for bank account information
• Credit card tiles for credit card details
• Service tiles for features and actions
• Service grids for multiple quick actions
• Promotional tiles for marketing content

Basic Usage

import { Tile } from 'dn-components';

<Tile 
  type="account"
  data={{
    id: 'club-lloyds',
    title: 'Club Lloyds',
    subtitle: '12-34-56 / 12345678',
    accountNumber: '12-34-56 / 12345678',
    balance: 935.68,
    variant: 'condensed',
    onPress: () => console.log('Account pressed'),
  }}
/>

Account Tiles

Account tiles display bank account information with balance and account details.

// Condensed variant - compact layout
<Tile 
  type="account"
  data={{
    id: 'savings-account',
    title: 'Savings Account',
    subtitle: '12-34-56 / 87654321',
    accountNumber: '12-34-56 / 87654321',
    balance: 2500.75,
    variant: 'condensed',
    onPress: () => navigation.navigate('AccountDetails'),
  }}
/>

// Detailed variant - expanded layout
<Tile 
  type="account"
  data={{
    id: 'current-account',
    title: 'Current Account',
    subtitle: '12-34-56 / 12345678',
    accountNumber: '12-34-56 / 12345678',
    balance: 935.68,
    variant: 'detailed',
    balanceLabel: 'Available balance',
    additionalInfo: 'Overdraft limit: £500.00',
    showMenu: true,
    actions: [
      {
        label: 'Transfer',
        onPress: () => console.log('Transfer'),
      }
    ],
    onPress: () => navigation.navigate('AccountDetails'),
  }}
/>

Service Tiles

Service tiles provide navigation to features and services.

<Tile 
  type="service"
  data={{
    id: 'everyday-offers',
    title: 'Everyday Offers',
    description: 'Save money on your everyday spending',
    icon: {
      color: '#22c55e',
      name: 'everyday',
    },
    badge: {
      text: 'NEW',
      color: '#ef4444',
    },
    showArrow: true,
    onPress: () => navigation.navigate('Offers'),
  }}
/>

Service Grids

Service grids display multiple quick actions in a 2x2 layout.

<Tile 
  type="serviceGrid"
  data={{
    id: 'quick-actions',
    items: [
      {
        id: 'add-accounts',
        title: 'Add accounts',
        description: 'See all your money in one place',
        icon: { color: '#3b82f6', name: 'home' },
        onPress: () => console.log('Add accounts'),
      },
      {
        id: 'credit-score',
        title: 'Your credit score',
        description: 'Check for free with ClearScore',
        icon: { color: '#10b981', name: 'chart' },
        onPress: () => console.log('Credit score'),
      },
    ],
  }}
/>

Icon

An SVG icon system with theme integration and brand-specific icons.

import { Icon } from 'dn-components';

<Icon name="settings" size={24} />
<Icon name="home" size={32} color="#22c55e" />
<Icon name="chevron" brand="shared" />

Features:

• SVG-based icons for crisp rendering at any size
• Brand-specific icon sets (lloyds, shared)
• Theme-aware default coloring
• Customizable size and color
• Support for multiple paths per icon

Available Icons:

• settings - Settings/configuration
• home - Home/dashboard
• everyday - Daily banking
• chevron - Navigation arrows
• letter - Messages/documents
• And many more...

Typography

The library includes custom GT-Ultra fonts that are automatically loaded:

• GT-Ultra-Median-Regular - Primary font for body text
• GT-Ultra-Median-Bold - Primary font for headings
• GT-Ultra-Standard-Regular - Secondary font for UI elements
• GT-Ultra-Standard-Bold - Secondary font for emphasis

Fonts are automatically loaded when using the ThemeProvider.

Development

Running Storybook

npm run storybook

This starts the Storybook development server where you can:

• Browse all components interactively
• Test different props and states
• View component documentation
• Test theme switching

Token-Based Architecture

Components use a token mapping system for consistent theming:

// Each component has a tokenMapping.ts file
export const componentTokenMapping = {
  // Internal name -> Actual token name
  backgroundColor: 'background_page_default',
  textColor: 'text_default',
  primaryColor: 'color_primary_500',
  spacing: 'spacing_size_16',
};

This allows:

• Consistent theming across all components
• Easy token updates without changing component code
• Clear separation between design tokens and component logic
• Type safety with TypeScript interfaces

Dependencies

This package uses standard npm dependencies:

• @dankupfer/dn-tokens - Design tokens package providing centralized theming, colors, typography, and icons
• Peer dependencies - React, React Native, and react-native-svg are expected to be provided by the consuming application

Installation automatically includes:

• All necessary design tokens and theme definitions
• Component implementations with full TypeScript support
• Consistent styling system across all components

Peer Dependencies: The following packages must be installed in your project:

npm install react react-native react-native-svg expo-font

Why peer dependencies?

• Prevents version conflicts with your main application
• Ensures compatibility with your existing React/React Native setup
• Reduces bundle size by sharing common dependencies
• Follows React Native component library best practices

Development Workflow

1. Make changes to components or theme system
2. Test in Storybook to verify changes work correctly
3. Pack the library with npm pack to create distribution file
4. Test in consuming projects using the packed .tgz file
5. Publish when ready (bundling will be automatically cleaned up)

Project Structure

src/
├── components/                 # Component implementations
│   ├── Actions/                # Button and action components
│   │   └── Button/             # ActionButton, CompactButton, IconButton
│   ├── Navigation/             # Navigation components
│   │   ├── Header/             # Page headers with actions
│   │   ├── BottomNav/          # Bottom navigation tabs
│   │   └── Tabs/               # Horizontal tabs with animation
│   ├── Content/                # Content display components
│   │   ├── Tile/               # Versatile tile component
│   │   └── Icon/               # SVG icon system
│   ├── Helpers/                # Helper components
│   │   ├── ScreenBuilder/      # JSON-driven screen builder
│   │   ├── HiddenDevMenu/      # Secret developer menu
│   │   ├── FlagManager/        # Feature flag management
│   │   ├── HeaderManager/      # Header transition management
│   │   └── ThemeSwitcher/      # Brand and theme switcher
│   └── Notifications/          # Notification components
│       └── NotificationBadge/  # Count badges
├── theme/                      # Theme system
│   ├── ThemeProvider.tsx       # Theme provider and logic
│   ├── TokenProcessor.tsx      # Process tokens and icon logic
│   └── FontLoader.tsx          # Font loading utility
└── types/                      # TypeScript type definitions

Adding New Components

1. Create component folder in src/components/[Category]/[ComponentName]/
2. Follow the established file structure:
   • index.tsx - Component exports
   • ComponentName.tsx - Main component implementation
   • types.ts - TypeScript interfaces
   • styles.ts - Token-based styling with createComponentStyles function
   • tokenMapping.ts - Internal to actual token mappings
   • ComponentName.stories.tsx - Storybook documentation
3. Use theme system and token mapping for consistent styling
4. Export from main src/index.ts
5. Add comprehensive documentation and examples

Theme Customization

Theme customization is handled through the dn-tokens package. See the dn-tokens repository for details on:

• Adding new brand configurations
• Modifying color palettes
• Updating typography scales
• Adding new icons
• Managing font assets

TypeScript Support

The library is built with TypeScript and provides comprehensive type definitions:

import type { 
  TileProps, 
  AccountTileData, 
  TabsProps,
  TabItem,
  ScreenBuilderProps,
  ScreenConfig,
  ProcessedTheme 
} from 'dn-components';

const accountData: AccountTileData = {
  id: 'my-account',
  title: 'Savings',
  // TypeScript will provide autocomplete and validation
};

const screenConfig: ScreenConfig = {
  scrollable: true,
  components: [
    {
      type: 'AccountCard',
      props: accountData
    }
  ]
};

Browser Support

• React Native: iOS 11+, Android 5.0+
• Web: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

Related Projects

This component library is part of the DN design system:

• dn-tokens - Centralized design tokens and assets
• dn-starter - React Native application templates using these components

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests and documentation
4. Submit a pull request

Development Guidelines

• Use TypeScript for all new components
• Follow the token mapping system patterns
• Add Storybook stories for new components
• Include comprehensive prop documentation
• Test across light/dark themes
• Ensure compatibility with dn-tokens package
• Follow the established file structure and naming conventions
• Use token-based styling with tokenMapping.ts files
• Create createComponentStyles functions for theme-aware styling