Pixie Design System

A comprehensive React component library designed specifically for dental practice management applications. Built with modern React, TypeScript support, and Tailwind CSS for consistent, accessible, and beautiful user interfaces.

🚀 Features

• 50+ Components - Complete set of UI components for healthcare applications
• TypeScript Support - Full type definitions for all components
• Responsive Design - Mobile-first approach with tablet and desktop optimizations
• Accessibility First - WCAG compliant with ARIA support and keyboard navigation
• Dark Mode - Built-in dark mode support with CSS variables
• Tree-Shakeable - Import only what you need for optimal bundle size
• Tailwind CSS - Utility-first CSS with custom design tokens
• Storybook Documentation - Interactive component playground

📦 Installation

npm install @phase3dental/pixie-design-system

or with yarn/pnpm:

yarn add @phase3dental/pixie-design-system
# or
pnpm add @phase3dental/pixie-design-system

Peer Dependencies

Make sure you have the required peer dependencies installed:

npm install react react-dom

🎨 Setup

1. Import Styles

Import the CSS file in your app's entry point:

import '@phase3dental/pixie-design-system/styles'

2. Configure Tailwind CSS (Required)

Your consumer project needs Tailwind CSS configured to work with the design system:

# Install Tailwind CSS in your project
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Update your tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './node_modules/@phase3dental/pixie-design-system/dist/**/*.{js,jsx}'
  ],
  theme: {
    extend: {
      colors: {
        sky: {
          50: '#f0f9ff',
          100: '#e0f2fe',
          200: '#bae6fd',
          300: '#7dd3fc',
          400: '#38bdf8',
          500: '#0ea5e9',
          600: '#0284c7',
          700: '#0369a1',
          800: '#075985',
          900: '#0c4a6e',
        }
      }
    },
  },
  plugins: [],
}

🔧 Usage

Basic Example

import { 
  Navigation, 
  Button, 
  Card, 
  PatientCard, 
  KPICard 
} from '@phase3dental/pixie-design-system'
import '@phase3dental/pixie-design-system/styles'

function App() {
  const navigationItems = [
    { label: 'Dashboard', href: '/', active: true },
    { label: 'Patients', href: '/patients' },
    { label: 'Appointments', href: '/appointments' }
  ]

  return (
    <div className="min-h-screen">
      <Navigation 
        logo="/logo.svg"
        items={navigationItems}
        user={{
          name: "Dr. Smith",
          email: "[email protected]",
          avatar: "/avatar.jpg"
        }}
      />
      
      <main className="container mx-auto p-6">
        <div className="grid gap-4 md:grid-cols-3">
          <KPICard
            title="Total Patients"
            value="1,234"
            change={12.5}
            changeType="increase"
            period="vs last month"
          />
          <PatientCard 
            patient={{
              id: "P001",
              name: "John Doe",
              age: 35,
              lastVisit: "2024-01-15",
              nextAppointment: "2024-02-20"
            }}
            variant="compact"
          />
          <Card className="p-4">
            <Button variant="default">Schedule Appointment</Button>
          </Card>
        </div>
      </main>
    </div>
  )
}

Utility Functions

import { cn } from '@phase3dental/pixie-design-system'

// Utility for conditional classNames
const buttonClass = cn(
  'base-button-class',
  isActive && 'active-class',
  variant === 'primary' && 'primary-class'
)

📚 Component Library

Navigation Components

Navigation

Main application navigation bar with user menu and search.

import { Navigation } from '@phase3dental/pixie-design-system'

<Navigation
  logo="/logo.svg"
  items={[
    { label: 'Dashboard', href: '/', active: true },
    { label: 'Patients', href: '/patients' }
  ]}
  user={{ name: 'Dr. Smith', email: '[email protected]' }}
  onSearch={(query) => console.log('Search:', query)}
/>

SubNav

Secondary navigation with multiple layout variants.

import { SubNav } from '@phase3dental/pixie-design-system'

<SubNav
  variant="section" // or "accordion", "activities", "activityDetails"
  items={[
    { id: '1', label: 'Overview', href: '/overview', active: true },
    { id: '2', label: 'Reports', href: '/reports' }
  ]}
/>

Sidebar

Collapsible sidebar navigation.

import { Sidebar } from '@phase3dental/pixie-design-system'

<Sidebar
  items={[
    { label: 'Dashboard', icon: Home, href: '/' },
    { label: 'Patients', icon: Users, href: '/patients' }
  ]}
  collapsed={false}
  onToggle={() => setCollapsed(!collapsed)}
/>

ActivityMenu

Activity tracking and notifications menu.

import { ActivityMenu } from '@phase3dental/pixie-design-system'

<ActivityMenu
  activities={[
    { id: '1', type: 'appointment', title: 'New Appointment', time: '10:30 AM' },
    { id: '2', type: 'message', title: 'Patient Message', time: '2 hours ago' }
  ]}
  onActivityClick={(activity) => console.log(activity)}
/>

Card Components

PatientCard

Display patient information in various layouts.

import { PatientCard } from '@phase3dental/pixie-design-system'

<PatientCard
  patient={{
    id: 'P001',
    name: 'John Doe',
    age: 35,
    phone: '(555) 123-4567',
    email: '[email protected]',
    lastVisit: '2024-01-15',
    nextAppointment: '2024-02-20',
    insurance: 'Delta Dental'
  }}
  variant="detailed" // or "compact", "mini"
  onEdit={(patient) => console.log('Edit:', patient)}
  onViewDetails={(patient) => console.log('View:', patient)}
/>

KPICard

Key performance indicator display.

import { KPICard } from '@phase3dental/pixie-design-system'

<KPICard
  title="Total Revenue"
  value="$45,230"
  change={12.5}
  changeType="increase" // or "decrease"
  period="vs last month"
  icon={DollarSign}
  trend={[20, 35, 30, 45, 50, 65]}
/>

TaskCard

Task management cards.

import { TaskCard } from '@phase3dental/pixie-design-system'

<TaskCard
  task={{
    id: 'T001',
    title: 'Review X-rays',
    description: 'Review patient X-rays for appointment',
    priority: 'high',
    dueDate: '2024-01-20',
    assignee: 'Dr. Smith',
    status: 'in-progress'
  }}
  onStatusChange={(status) => console.log('Status:', status)}
  onEdit={(task) => console.log('Edit:', task)}
/>

MetricCard

Metric display with charts.

import { MetricCard } from '@phase3dental/pixie-design-system'

<MetricCard
  title="Patient Satisfaction"
  value="4.8"
  subtitle="out of 5.0"
  chart={{
    type: 'line',
    data: [4.5, 4.6, 4.7, 4.8, 4.8, 4.9]
  }}
  trend="up"
/>

DashboardWidget

Customizable dashboard widgets.

import { DashboardWidget } from '@phase3dental/pixie-design-system'

<DashboardWidget
  title="Upcoming Appointments"
  subtitle="Today"
  actions={[
    { label: 'View All', onClick: () => console.log('View all') }
  ]}
>
  {/* Widget content */}
</DashboardWidget>

Data Display Components

Table

Feature-rich data table.

import { Table } from '@phase3dental/pixie-design-system'

<Table
  columns={[
    { key: 'name', label: 'Patient Name', sortable: true },
    { key: 'age', label: 'Age', sortable: true },
    { key: 'lastVisit', label: 'Last Visit', sortable: true },
    { key: 'status', label: 'Status' }
  ]}
  data={patients}
  onRowClick={(row) => console.log('Selected:', row)}
  onSort={(column, direction) => console.log('Sort:', column, direction)}
  selectable
  pagination={{
    page: 1,
    pageSize: 10,
    total: 100
  }}
/>

CardTable

Card + table component with tabs, filters, and insights.

import { CardTable, type TabDefinition, Button } from '@phase3dental/pixie-design-system'
import '@phase3dental/pixie-design-system/styles'

const tabs: TabDefinition[] = [
  { id: 'all', label: 'All' },
  { id: 'recall', label: 'Recall Due', predicate: (row) => row.recallDue === true },
  { id: 'vip', label: 'VIP Patients', predicate: (row) => row.isVip === true },
]

<CardTable
  title="Patients"
  data={patients}
  columns={columns}
  tabs={tabs}
  headerRightActions={<Button size="sm">New Patient</Button>}
/>

Custom tabs (segmented pills) with dynamic counts via renderTabs:

<CardTable
  data={patients}
  columns={columns}
  tabs={tabs}
  renderTabs={({ tabs, activeTab, onTabChange, counts, insightsVisible, onInsightsToggle }) => (
    <div className="w-full">
      <div role="tablist" className="flex w-full rounded-full border border-gray-200 bg-white p-1">
        {tabs.map((t) => (
          <button
            key={t.id}
            role="tab"
            aria-selected={activeTab === t.id}
            onClick={() => onTabChange(t.id)}
            className={`flex-1 rounded-full px-3 py-2 text-sm font-medium transition-colors ${
              activeTab === t.id ? 'bg-sky-100 text-sky-700' : 'text-gray-600 hover:text-gray-900 hover:bg-gray-50'
            }`}
          >
            <span>{t.label}</span>
            <span className="ml-2 inline-flex h-5 min-w-[20px] items-center justify-center rounded-full bg-gray-100 px-1 text-xs text-gray-700">
              {counts?.[t.id] ?? 0}
            </span>
          </button>
        ))}
      </div>
      <div className="mt-2 flex justify-end">
        <button className="text-sm text-sky-700 hover:underline" onClick={onInsightsToggle}>
          {insightsVisible ? 'Hide Insights' : 'Show Insights'}
        </button>
      </div>
    </div>
  )}
/>

Progress & Visualization

ProgressArc

Circular progress indicator.

import { ProgressArc } from '@phase3dental/pixie-design-system'

<ProgressArc
  value={75}
  max={100}
  size="lg" // "sm", "md", "lg", "xl"
  label="Complete"
  showValue
  color="primary"
/>

WeatherWidget

Weather display widget.

import { WeatherWidget } from '@phase3dental/pixie-design-system'

<WeatherWidget
  location="New York, NY"
  temperature={72}
  condition="sunny"
  forecast={[
    { day: 'Mon', high: 75, low: 60, condition: 'sunny' },
    { day: 'Tue', high: 73, low: 58, condition: 'cloudy' }
  ]}
/>

Form Components

DatePicker

Date selection component.

import { DatePicker } from '@phase3dental/pixie-design-system'

<DatePicker
  selected={date}
  onChange={(date) => setDate(date)}
  minDate={new Date()}
  maxDate={addMonths(new Date(), 3)}
  excludeDates={[new Date('2024-12-25')]}
  placeholderText="Select appointment date"
/>

UI Primitives

All shadcn/ui components are included and can be imported:

import {
  Button,
  Card,
  Dialog,
  Input,
  Select,
  Checkbox,
  RadioGroup,
  Switch,
  Tabs,
  Alert,
  Badge,
  Avatar,
  Tooltip,
  Popover,
  DropdownMenu,
  Sheet,
  Form,
  Label,
  Textarea,
  Slider,
  Progress,
  Skeleton,
  Accordion,
  AlertDialog,
  AspectRatio,
  Breadcrumb,
  Calendar,
  Carousel,
  Collapsible,
  Command,
  ContextMenu,
  Drawer,
  HoverCard,
  InputOTP,
  Menubar,
  NavigationMenu,
  Pagination,
  ResizablePanel,
  ScrollArea,
  Separator,
  Sonner,
  Toast,
  Toggle,
  ToggleGroup
} from '@phase3dental/pixie-design-system'

## 🎭 Storybook

Explore all components interactively:

```bash
npm run storybook

View the live Storybook at: https://phase3dental.github.io/pixie-design-system

🛠 Development

Prerequisites

• Node.js 18+
• npm, yarn, or pnpm

Setup

# Clone the repository
git clone https://github.com/phase3dental/pixie-design-system.git
cd pixie-design-system

# Install dependencies
npm install

# Start Storybook for development
npm run storybook

# Build the library
npm run build

Scripts

• npm run build - Build the library for production
• npm run dev - Build in watch mode for development
• npm run storybook - Start Storybook development server
• npm run build-storybook - Build Storybook for deployment
• npm run lint - Run ESLint

🎨 Theming

CSS Variables

Customize the theme by overriding CSS variables:

:root {
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96.1%;
  --accent: 210 40% 96.1%;
  --destructive: 0 84.2% 60.2%;
  --border: 214.3 31.8% 91.4%;
  --radius: 0.5rem;
}

.dark {
  --primary: 210 40% 98%;
  --primary-foreground: 222.2 47.4% 11.2%;
  /* ... dark mode variables */
}

Dark Mode Support

import { ThemeProvider } from '@phase3dental/pixie-design-system'

function App() {
  return (
    <ThemeProvider defaultTheme="system" storageKey="app-theme">
      {/* Your application */}
    </ThemeProvider>
  )
}

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-component
3. Make your changes and add tests
4. Run tests: npm test
5. Submit a pull request

Component Guidelines

• Follow the existing component structure
• Include PropTypes for all props
• Add Storybook stories for new components
• Ensure accessibility compliance
• Write comprehensive documentation

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📚 Storybook

📈 Changelog

See CHANGELOG.md for version history and updates.