🎨 BP Design System

A comprehensive React component library built with BP 3.0 design tokens, Tailwind CSS v4, and TypeScript.

Current Version: 1.3.9 | React 18/19 | TypeScript Ready

📦 View on npm | 🎮 Live Storybook | 🔗 Repository

🎮 Try It Live

• 📖 Interactive Storybook - Explore all components live
• ⚡ CodeSandbox Demo - Ready-to-use starter
• 🖥️ Full App Example - See it in action

📊 Bundle Impact

• Gzipped: ~45KB (fully tree-shakeable)
• Per Component: 2-8KB each when imported individually
• Icons: ~1KB per icon (loaded on-demand via SVG)
• Zero Runtime: All styling via CSS - no JavaScript overhead

// ✅ Tree-shaken imports (recommended) - only bundles what you use
import { Button, Icon } from 'bp-design-system'

// ❌ Avoid - imports entire library
import * as DS from 'bp-design-system'

🚀 Quick Start

1. Install

npm install bp-design-system

2. Basic Setup (3 Essential Steps)

Step 1: Configure Tailwind

// tailwind.config.ts
import type { Config } from "tailwindcss"
import { bpTheme } from 'bp-design-system/tailwind.theme'

export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
    // 🔥 IMPORTANT: Include design system components in scan
    "./node_modules/bp-design-system/dist/**/*.{js,mjs}",
  ],
  theme: {
    extend: bpTheme,
  },
} satisfies Config

Step 2: Import CSS

// src/main.tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'

// 🔥 REQUIRED: Import design system CSS first
import 'bp-design-system/tokens.css'
import 'bp-design-system/dist/index.css'

// Then your app CSS
import './index.css'
import App from './App.tsx'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

/* src/index.css */
@import 'tailwindcss';

body {
  @apply bg-porcelain;
}

Step 3: Add Vite Middleware (⚠️ CRITICAL)

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'
import fs from 'fs'

export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),
    // 🔥 REQUIRED: Serve design system assets
    {
      name: 'serve-design-system-assets-and-fonts',
      configureServer(server) {
        server.middlewares.use((req, res, next) => {
          // Serve assets (icons)
          if (req.url?.startsWith('/assets/')) {
            const assetPath = path.join(__dirname, 'node_modules/bp-design-system/dist', req.url)
            if (fs.existsSync(assetPath)) {
              const content = fs.readFileSync(assetPath)
              const contentType = path.extname(assetPath) === '.svg' ? 'image/svg+xml' : 'application/octet-stream'
              res.setHeader('Content-Type', contentType)
              res.setHeader('Cache-Control', 'public, max-age=31536000')
              res.end(content)
              return
            }
          }
          // Serve fonts
          if (req.url?.startsWith('/fonts/')) {
            const fontPath = path.join(__dirname, 'node_modules/bp-design-system/dist', req.url)
            if (fs.existsSync(fontPath)) {
              const content = fs.readFileSync(fontPath)
              const contentType = {
                '.woff2': 'font/woff2',
                '.woff': 'font/woff',
              }[path.extname(fontPath)] || 'application/octet-stream'
              res.setHeader('Content-Type', contentType)
              res.setHeader('Cache-Control', 'public, max-age=31536000')
              res.end(content)
              return
            }
          }
          next()
        })
      },
    },
  ],
})

📖 Complete Setup Guide

For a comprehensive setup guide with troubleshooting, see the CONSUMING_APPS_SETUP.md file included in this package (available in the npm package files).

🎯 Ready-to-Use Example

import { Button, Icon, Input, Checkbox, Switch, FooterAfterLogin } from 'bp-design-system'

function App() {
  return (
    <div className="min-h-screen bg-porcelain p-8">
      {/* Icons */}
      <div className="flex gap-4 mb-8">
        <Icon name="check-circle" size="md" className="text-green-600" />
        <Icon name="bell" size="md" className="text-blue-600" />
        <Icon name="user" size="md" className="text-gray-600" />
      </div>

      {/* Buttons */}
      <div className="flex gap-4 mb-8">
        <Button variant="primary">Primary</Button>
        <Button variant="secondary">Secondary</Button>
        <Button variant="tertiary">Tertiary</Button>
        <Button variant="hyperlink">Hyperlink</Button>
      </div>

      {/* Form Controls */}
      <div className="space-y-4 max-w-md mb-8">
        <Input label="Full Name" placeholder="Enter your name..." />
        <Input label="Email" type="email" placeholder="[email protected]" />
        
        <div className="flex items-center gap-3">
          <Checkbox id="terms" />
          <label htmlFor="terms">I agree to the terms</label>
        </div>
        
        <div className="flex items-center gap-3">
          <Switch id="notifications" />
          <label htmlFor="notifications">Enable notifications</label>
        </div>
      </div>

      {/* Footer */}
      <FooterAfterLogin
        companyInfo={{
          name: 'Your Company',
          phone: '1-800-123-4567',
          hours: '24/7 Customer Support',
        }}
        quickLinks={[
          { label: 'Help Center', href: '/help' },
          { label: 'Contact Us', href: '/contact' },
        ]}
        legalLinks={[
          { label: 'Privacy Policy', href: '/privacy' },
          { label: 'Terms of Service', href: '/terms' },
        ]}
        copyright="© 2026 Your Company. All rights reserved."
      />
    </div>
  )
}

📦 What's Included

// 🎯 Available Component Imports
import { 
  // Form Controls
  Button, Input, Checkbox, Switch, RadioButton, RadioGroup,
  ToggleButton, ToggleGroup, Dropdown, RangeSlider,
  RoundedButton, RoundedIconButton, SearchButton,
  
  // Data Display
  Icon, StatusTag, Pill, PillsGroup, Progress, Alert, Tooltip,
  
  // Badges
  BalanceBadge, IconBadge, NotificationBadge, ShoppingCartBadge,
  
  // Date & Time
  Calendar, DatePicker, TimePicker,
  
  // Overlays
  Modal, ModalTrigger, ModalContent, ModalHeader, ModalTitle,
  ModalBody, ModalFooter, ModalClose,
  Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle,
  SheetBody, SheetFooter,
  
  // Navigation & Layout
  Tabs, TabsList, TabsTrigger, TabsContent,
  Accordion, AccordionItem, AccordionTrigger, AccordionContent,
  
  // Specialized
  UserAccountMenu, LanguageSelector, AssistancePhone,
  SocialMediaIcons, ProductCardButtonSet,
  
  // Patterns
  Header, HeaderAfterLogin, HeaderPreLogin, HeaderCheckout,
  Footer, FooterAfterLogin, FooterPreLogin,
  ProductCard, ProductGrid, Filter, Search, Carousel,
  
  // Utilities & Helpers
  cn, formatCurrency, formatDate, parseDate,
  formatTime12Hour, parseTime12Hour,
  
  // Hooks
  useToast, useDatePicker, useSearch, useFilter, useCarousel,
  
  // TypeScript Types
  ButtonProps, IconProps, InputProps, ModalContentProps,
  FooterAfterLoginProps, ProductCardProps, // ... and many more
} from 'bp-design-system'

// 🎨 Required CSS Imports
import 'bp-design-system/tokens.css'     // Design tokens & fonts (required)
import 'bp-design-system/dist/index.css' // Component styles (required)

// 🎯 Tailwind Theme Extension
import { bpTheme } from 'bp-design-system/tailwind.theme'

📦 Available Components

🎯 50+ Production-Ready Components - This design system includes a comprehensive library of atoms, patterns, and utilities. All components are fully typed, accessible, and follow BP 3.0 design standards.

✨ Atoms (UI Components)

Form Controls

• Button - 4 variants: primary, secondary, tertiary, hyperlink
• RoundedButton - Rounded variant button
• RoundedIconButton - Icon-only rounded button
• SearchButton - Specialized search button component
• Input - Text inputs with floating labels, validation, and icons
• Checkbox - Styled checkbox with label support
• RadioButton / RadioGroup - Radio button groups with validation
• Switch - Toggle switch component
• ToggleButton / ToggleGroup - Toggle button groups
• Dropdown - Select dropdown with search and filtering
• RangeSlider - Range input slider component

Data Display

• Icon - 349+ SVG icons with size variants
• StatusTag - Status indicators with color variants
• Pill / PillsGroup - Pill/tag components with variants
• Progress - Progress bar component
• Alert - Alert messages (success, error, warning, info)
• Tooltip - Tooltip with all placement options

Badges & Indicators

• BalanceBadge - Balance display badge
• IconBadge - Base icon badge component
• NotificationBadge - Notification count badge
• ShoppingCartBadge - Shopping cart indicator badge

Date & Time

• Calendar - Full-featured calendar component
• DatePicker - Date selection picker
• TimePicker - Time selection component

Overlays & Dialogs

• Modal - Modal dialog with composition API (ModalTrigger, ModalContent, ModalHeader, ModalTitle, ModalBody, ModalFooter, ModalClose)
• Sheet - Side sheet/drawer component (SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetBody, SheetFooter)

Navigation & Layout

• Tabs - Tab navigation component (TabsList, TabsTrigger, TabsContent)
• Accordion - Collapsible accordion component (AccordionItem, AccordionTrigger, AccordionContent)

Specialized Components

• UserAccountMenu - User account dropdown menu
• LanguageSelector - Language selection dropdown
• AssistancePhone - Phone assistance component
• SocialMediaIcons - Social media icon links
• ProductCardButtonSet - Product card action buttons

🏗️ Patterns (Complex Components)

Navigation

• Header - Site header component
  • HeaderAfterLogin - Authenticated user header
  • HeaderPreLogin - Pre-authentication header
  • HeaderCheckout - Checkout flow header
• Footer - Site footer component
  • FooterAfterLogin - Complete footer with company info, links
  • FooterPreLogin - Pre-authentication footer variant

Product & E-commerce

• ProductCard - Product card component with image, pricing, actions
• ProductGrid - Responsive product grid layout
• Filter - Advanced filtering system with multiple filter types
• Search - Search component with suggestions (SearchType1, SearchType2)

Media & Display

• Carousel - Two variants matching BP 3.0 Figma specifications:
  • Carousel Banner - Full-width promotional hero with auto-scroll (8 seconds), looping, pause on hover
  • Carousel Belt (Aisles) - Horizontal product carousel with manual navigation only
  • Components: CarouselRoot, CarouselTrack, CarouselSlide, CarouselControls, CarouselIndicators
  • Responsive heights: 280px (mobile) → 320px (tablet) → 360px (desktop)
  • Full keyboard navigation, ARIA support, and accessibility compliance

🔧 Utilities & Helpers

Design System

• Design Tokens - CSS variables for colors, typography, spacing
• Tailwind Theme - Pre-configured Tailwind theme extension (bpTheme)
• TypeScript Types - Full type definitions for all components

Utility Functions

• cn() - Class name utility (clsx + tailwind-merge)
• formatCurrency() - Format numbers as currency
• formatDate() - Format dates with localization (from Calendar)
• parseDate() - Parse date strings (from Calendar)
• formatTime12Hour() - Format time in 12-hour format (from TimePicker)
• parseTime12Hour() - Parse 12-hour time strings (from TimePicker)

Hooks

• useToast() - Toast notification hook (from Alert)
• useDatePicker() - Date picker state management
• useSearch() - Search functionality hook
• useFilter() - Filter state management hook
• useCarousel() - Carousel navigation hook

🎨 Icons

The design system includes 349+ icons that render as optimized SVG components:

import { Icon } from 'bp-design-system'

// Basic usage
<Icon name="calendar" />
<Icon name="bell" size="lg" />
<Icon name="user" className="text-primary" />

// With accessibility
<Icon name="warning-circle" size="sm" alt="Warning icon" />

Icon names use kebab-case. Common icons include:

• check-circle, x-circle, warning-circle
• calendar, bell, user, settings
• arrow-left, arrow-right, chevron-down
• And 340+ more!

⚡ Performance & Bundle Tips

Icon Optimization

// ✅ Icons load on-demand automatically
<Icon name="calendar" /> // Only loads calendar.svg when rendered

// ✅ Multiple icons = multiple small requests (cached)
<Icon name="user" />     // ~1KB
<Icon name="settings" /> // ~1KB  
<Icon name="bell" />     // ~1KB

Font Loading

// ✅ Proxima Nova fonts are preloaded automatically via tokens.css
// No additional configuration needed!

// ✅ For even faster loading, add to your HTML <head>:
<link rel="preload" href="/fonts/ProximaNova-Regular.woff2" as="font" type="font/woff2" crossOrigin="">
<link rel="preload" href="/fonts/ProximaNova-Semibold.woff2" as="font" type="font/woff2" crossOrigin="">

Tree Shaking

// ✅ Best - Individual imports (recommended)
import { Button, Icon } from 'bp-design-system'

// ✅ Also good - Specific component imports  
import Button from 'bp-design-system/Button'
import Icon from 'bp-design-system/Icon'

// ❌ Avoid - Imports entire library (~45KB)
import * as BP from 'bp-design-system'

🏗️ Framework Support

| Framework | Status | Bundle Size | Setup Complexity | |-----------|--------|-------------|------------------| | Vite | ✅ Recommended | ~45KB gzipped | Easy (3 steps) | | Next.js 15+ | ✅ Fully Supported | ~45KB gzipped | Medium (4 steps) | | Create React App | ⚠️ Limited Support* | ~45KB gzipped | Hard (requires eject) | | Remix | ✅ Supported | ~45KB gzipped | Medium (4 steps) |

*CRA Note: Requires ejecting for Tailwind CSS v4 support. Consider migrating to Vite for better performance.

Vite Setup (Recommended)

Already covered in Quick Start above! ⬆️

Next.js 15+ Setup

// next.config.js
module.exports = {
  experimental: {
    esmExternals: true
  },
  transpilePackages: ['bp-design-system']
}

🎨 Styling & Customization

Custom CSS Classes

All components accept className for custom styling:

<Button className="w-full shadow-lg" variant="primary">
  Full Width Button
</Button>

<Input 
  className="border-2 border-primary" 
  label="Custom Styled Input"
/>

Component Slots

Many components support slotClassNames for granular control:

<Button 
  slotClassNames={{
    base: "custom-button-base",
    content: "custom-button-content"
  }}
>
  Styled Button
</Button>

🔧 Development

# Install dependencies
npm install

# Start Storybook (component playground)
npm run storybook

# Build package
npm run build

# Run tests
npm test

# Lint code
npm run lint

📋 Requirements

• React: 18.0.0+ or 19.0.0+
• React DOM: 18.0.0+ or 19.0.0+
• Tailwind CSS: 4.1.14+
• Vite: 7+ (for middleware setup)

✅ Compatibility

• ✅ React 18 & 19
• ✅ TypeScript 5+
• ✅ Vite 7+
• ✅ Next.js 15+
• ✅ Modern browsers (Chrome, Firefox, Safari, Edge)

🌐 Browser Support

| Browser | Version | Status | Notes | |---------|---------|--------|-------| | Chrome | 90+ | ✅ Full Support | Recommended for development | | Firefox | 88+ | ✅ Full Support | All features work |
| Safari | 14+ | ✅ Full Support | iOS Safari included | | Edge | 90+ | ✅ Full Support | Chromium-based versions | | Mobile Safari | iOS 14+ | ✅ Full Support | Touch interactions optimized | | Chrome Mobile | Android 90+ | ✅ Full Support | Responsive design included |

Modern browsers only - Requires CSS custom properties, CSS Grid, and ES2020 support.

♿ Accessibility First

All components are built with WCAG 2.1 AA compliance in mind:

✅ What's Included

• Keyboard Navigation - Full keyboard support for all interactive elements
• Screen Reader - Tested with NVDA, JAWS, and VoiceOver
• Focus Management - Proper focus indicators and logical tab order
• ARIA Labels - Comprehensive labeling for assistive technologies
• Color Contrast - Exceeds AA standards (4.5:1 minimum ratio)
• Motion Respect - Respects prefers-reduced-motion settings

🎯 Accessibility Examples

// ✅ Components include accessibility by default
<Button aria-label="Save document to cloud storage">
  Save <Icon name="cloud-upload" alt="" />
</Button>

<Input 
  label="Email Address"
  required
  aria-describedby="email-help"
  error={emailError}
/>
<div id="email-help">We'll never share your email</div>

<Icon name="warning" alt="Warning: Action required" />

📚 Common Patterns

Loading States

const [loading, setLoading] = useState(false)

<Button variant="primary" disabled={loading}>
  {loading ? (
    <>
      <Icon name="spinner" className="animate-spin mr-2" />
      Saving...
    </>
  ) : (
    'Save Changes'
  )}
</Button>

Form Validation

const [email, setEmail] = useState('')
const [error, setError] = useState('')

<Input 
  label="Email Address"
  value={email}
  onChange={(e) => {
    setEmail(e.target.value)
    setError('') // Clear error on change
  }}
  error={error}
  required
  type="email"
  placeholder="[email protected]"
/>

Icon Buttons

<Button variant="tertiary" className="p-2" aria-label="Settings">
  <Icon name="settings" size="sm" />
</Button>

<Button variant="secondary" className="gap-2">
  <Icon name="download" size="sm" />
  Download PDF
</Button>

🐛 Troubleshooting

🖼️ Icons not loading (showing gray circles)?

// ✅ Fix: Add Vite middleware for `/assets/` path
// vite.config.ts - Add this plugin:
{
  name: 'serve-design-system-assets',
  configureServer(server) {
    server.middlewares.use((req, res, next) => {
      if (req.url?.startsWith('/assets/')) {
        const assetPath = path.join(__dirname, 'node_modules/bp-design-system/dist', req.url)
        // ... serve file
      }
      next()
    })
  }
}

🔤 Fonts not loading (console OTS errors)?

// ✅ Fix 1: Ensure Vite middleware serves fonts
// ✅ Fix 2: Import tokens.css FIRST
import 'bp-design-system/tokens.css'     // ← Must be first
import 'bp-design-system/dist/index.css'

// ✅ Fix 3: Add font preload to HTML head (optional speed boost)
<link rel="preload" href="/fonts/ProximaNova-Regular.woff2" as="font" type="font/woff2" crossOrigin="">

🎨 Styles not applying (classes not working)?

// ✅ Fix: Ensure Tailwind scans design system package
// tailwind.config.ts
export default {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/bp-design-system/dist/**/*.{js,mjs}", // ← Critical!
  ],
  theme: {
    extend: bpTheme, // ← Also critical!
  },
}

📦 "Module not found" errors?

# ✅ Fix: Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

# For Yarn users:
yarn cache clean
rm -rf node_modules yarn.lock
yarn install

🏗️ Build/Production issues?

// ✅ Fix 1: Ensure middleware works in production
// Option A: Configure your production server to serve assets
// Option B: Use CDN for assets in production builds

// ✅ Fix 2: Check build output includes fonts & assets
npm run build
ls dist/assets/  # Should contain SVG files
ls dist/fonts/   # Should contain .woff2 files

⚡ TypeScript errors?

// ✅ Fix: Add CSS module declarations
// Add to vite-env.d.ts or global.d.ts:
declare module 'bp-design-system/tokens.css'
declare module 'bp-design-system/dist/index.css'

// ✅ For stricter typing:
declare module 'bp-design-system' {
  export * from 'bp-design-system/dist/types'
}

🔍 Still stuck?

1. Check the setup guide: CONSUMING_APPS_SETUP.md (included in the npm package)
2. View working examples: Our test apps in the repo
3. View the repository: Azure DevOps Repository
4. Contact support: [email protected]

🤝 Community & Support

📖 Resources

• 📚 Full Documentation - Complete guides, API reference, and tutorials
• 🎮 Interactive Storybook - Explore and test components live
• ⚡ CodeSandbox Templates - Ready-to-use project starters
• 🖥️ Demo Applications - Real-world examples

💬 Get Help

• 🐛 Bug Reports - Found a bug? Report in Azure DevOps
• 💡 Feature Requests - Suggest improvements via Azure DevOps
• 📦 npm Package - Package info, versions, and documentation
• 📧 Email Support - Direct support for urgent issues

🚀 Contributing

We welcome contributions! Here's how you can help:

• 🐛 Report bugs with detailed reproduction steps
• 💡 Suggest features that would benefit the community
• 📝 Improve docs - typos, examples, clarity
• 🔧 Submit PRs - See CONTRIBUTING.md for guidelines

# Quick start for contributors
# Clone from Azure DevOps repository
git clone https://nationshearing.visualstudio.com/NationsOTCProject/_git/nb-benefit-portals-ui
cd nb-benefit-portals-ui
npm install
npm run storybook  # Start development environment

💼 Enterprise Support

• Priority support for production applications
• Custom component development
• Design system consulting
• Training and workshops

Contact: [email protected]

📚 Documentation

• Storybook - Interactive component playground
• Setup Guide - Comprehensive setup instructions
• Font Setup - Font configuration guide
• Icon Reference - Complete icon list

📄 License

MIT © NationsBenefits

🔗 Repository

Azure DevOps Repository

💡 Pro Tips

1. Start with the example above - It covers all major components
2. Use the Vite middleware - Critical for icons and fonts
3. 📖 Explore Storybook first - See all components with live examples
4. Follow the setup guide - Comprehensive troubleshooting included
5. Leverage TypeScript - Full type safety and IntelliSense support

Happy coding! 🚀