Kulcare Design System Documentation

A comprehensive guide to the Kulcare healthcare platform design system, built with React, TypeScript, and Tailwind CSS.

OverviewCopy Anchor Link

The Kulcare Design System is a healthcare-optimized component library and styling framework that ensures consistency, accessibility, and professional aesthetics across all platform applications.

Core TechnologiesCopy Anchor Link

• Tailwind CSS: Utility-first CSS framework with custom preset
• shadcn/ui: High-quality, accessible React components
• CSS Custom Properties: Dynamic theming and typography
• TypeScript: Type-safe component APIs and utilities

Design PhilosophyCopy Anchor Link

1. Healthcare-First: Optimized for medical data display and clinical workflows
2. Accessibility: WCAG 2.1 AA compliant components
3. Performance: Hybrid CSS/TypeScript approach for optimal runtime performance
4. Consistency: Unified design language across all micro-frontends

Quick StartCopy Anchor Link

// Import theme provider and styles
import { ThemeProvider } from '@kulcare/ui-kit'
import '@kulcare/ui-kit/src/styles/globals.css'

// Use typography utilities
import { type, getVitalSignClasses } from '@kulcare/ui-kit/lib/typography'

// Use table and healthcare styling constants
import { tableHeaderStyles, tableCellStyles, vitalSignStyles } from '@kulcare/ui-kit'

// Apply healthcare-optimized typography
<span className={type.vitalSign}>
  BP: 120/80
</span>

// Use consistent table styling
<TableHead className={tableHeaderStyles.currency}>Amount</TableHead>
<TableCell className={tableCellStyles.currency}>₹12,500</TableCell>

// Dynamic vital sign styling with status
<span className={vitalSignStyles.getValueClass('warning')}>
  95
</span>
<span className={vitalSignStyles.unit}>bpm</span>

Note: For comprehensive styling guidelines, design tokens, anti-patterns, and migration from v3, see the STYLE-GUIDE.md.

Documentation StructureCopy Anchor Link

🎨 FoundationCopy Anchor Link

Spacing & LayoutCopy Anchor Link

Comprehensive spacing system and layout patterns for medical data presentation. Includes the 4px grid system, container patterns, healthcare-specific spacing guidelines, and responsive layout strategies optimized for clinical workflows.

When to use: Building new components, creating layouts, displaying medical data, implementing responsive designs

Typography SystemCopy Anchor Link

Healthcare-optimized typography with semantic classes, medical value formatting, and the new type utility system. Features monospace fonts for medical data, status-based text styling, and WCAG-compliant contrast ratios.

When to use: Text styling, medical data display, consistent typography across apps

🧩 ComponentsCopy Anchor Link

Date And Time ControlsCopy Anchor Link

Shared calendar, time, and combined local date/time fields, including form validation, timezone ownership, and end-of-day support.

Component LibraryCopy Anchor Link

Complete guide to shadcn/ui components customized for healthcare applications. Covers all core components (Button, Card, Input, Select, Dialog, etc.) with healthcare context and usage examples.

When to use: Building interfaces, finding existing components, understanding variant options, ensuring UI consistency

Healthcare ComponentsCopy Anchor Link

Specialized UI patterns for medical workflows including PatientCard, VitalSignsCard, MedicationList, AppointmentCard, and clinical workflow components with HIPAA-compliant data display patterns.

When to use: Displaying medical data, building clinical workflows, creating medical forms, showing health metrics, implementing clinical features

Form ComponentsCopy Anchor Link

Comprehensive form patterns for patient intake, clinical documentation, and medical data collection. Includes validation, accessibility, file upload, date pickers, and healthcare-specific input patterns.

When to use: Building patient forms, creating clinical workflows, implementing data entry, designing user interfaces, ensuring form accessibility

Data DisplayCopy Anchor Link

Specialized patterns for presenting medical data including vital signs, lab results, patient information, and health metrics with optimal clarity and accessibility for clinical decision-making.

When to use: Presenting medical data, building dashboards, showing patient information, creating reports, designing lists and tables

Table & Healthcare StylesCopy Anchor Link

Focused, high-value styling constants for consistent table formatting and healthcare-specific data display. TypeScript constants that compose with Tailwind utilities for tables, medical values, and status indicators.

When to use: Building tables, displaying patient IDs, formatting currency, showing vital signs, medical data consistency

🛠️ UtilitiesCopy Anchor Link

Typography UtilitiesCopy Anchor Link

Comprehensive typography utilities and helper functions including the refactored type export, medical data formatting, responsive text scaling, and theme-aware typography patterns.

When to use: Building components, displaying medical data, creating layouts, implementing themes, ensuring accessibility

Theme UtilitiesCopy Anchor Link

Theme management system supporting light/dark modes, healthcare-specific color schemes, CSS custom properties, dynamic theme switching, and accessibility compliance.

When to use: Implementing theming, customizing colors, building components, managing user preferences, ensuring accessibility

Responsive DesignCopy Anchor Link

Mobile-first responsive design patterns optimized for medical devices and clinical settings. Includes breakpoint systems, touch optimization, and healthcare-specific responsive patterns.

When to use: Building new components, creating layouts, optimizing for mobile, supporting tablets, desktop optimization

Animation GuidelinesCopy Anchor Link

Animation system emphasizing accessibility, performance, and clinical workflow enhancement. Includes micro-interactions, loading states, medical-specific animations, and reduced motion support.

When to use: Enhancing user experience, indicating system status, guiding attention, creating visual hierarchy, improving workflow

📖 GuidelinesCopy Anchor Link

AccessibilityCopy Anchor Link

Comprehensive WCAG 2.1 AA compliance guidelines including color contrast, screen reader support, keyboard navigation, and healthcare-specific accessibility requirements.

When to use: Building components, reviewing features, testing interfaces, supporting users with disabilities, meeting regulatory requirements

Healthcare UXCopy Anchor Link

User experience patterns for healthcare professionals including clinical workflows, error prevention, efficiency patterns, mobile optimization, and medical-specific interaction patterns.

When to use: Designing clinical workflows, building medical interfaces, optimizing for efficiency, ensuring patient safety, supporting healthcare users

PerformanceCopy Anchor Link

Performance optimization strategies for healthcare applications including component optimization, data loading, bundle optimization, memory management, and virtualization for large datasets.

When to use: Building components, optimizing features, handling large datasets, mobile optimization, network constraints

Migration GuideCopy Anchor Link

Step-by-step migration guides for upgrading design system versions including breaking changes, automated migration tools, and compatibility matrices for seamless updates.

When to use: Upgrading design system versions, adopting new patterns, refactoring existing code, onboarding team members, planning upgrades

Key FeaturesCopy Anchor Link

1. Healthcare-Optimized TypographyCopy Anchor Link

/* Monospace fonts for medical values */
.type-vital-sign {
  font-family: "JetBrains Mono", monospace;
  font-size: 14px;
  font-weight: 500;
}

/* Status-based coloring */
.status-normal {
  color: rgb(134, 239, 172);
}
.status-warning {
  color: rgb(251, 191, 36);
}
.status-critical {
  color: rgb(239, 68, 68);
}

2. App-Specific ThemingCopy Anchor Link

Each micro-frontend has its own color identity while maintaining consistency:

• CMS: Blue (#078DFF) - Clinical management
• Growth: Green (#52c41a) - Marketing and growth
• Doctor: Purple (#722ed1) - Doctor-specific features
• Reports: Cyan (#13c2c2) - Analytics and reporting

3. Dark Mode SupportCopy Anchor Link

Full dark mode support with smooth transitions and proper contrast ratios for medical data visibility.

4. Component ArchitectureCopy Anchor Link

• Shared UI Kit: @kulcare/ui-kit package with common components
• App-Specific Components: Each app maintains its own specialized components
• Composition Pattern: Build complex UIs from simple, reusable parts

Development WorkflowCopy Anchor Link

Setting UpCopy Anchor Link

# Install dependencies
pnpm install

# Start Storybook for component development
pnpm storybook

# Build the design system
pnpm build:ui-kit

Adding ComponentsCopy Anchor Link

# Add new shadcn/ui component to an app
cd apps/cms
npx shadcn-ui@latest add dialog

# Components are app-specific, not shared by default

Creating Custom ComponentsCopy Anchor Link

// Use design system utilities
import { cn } from "@kulcare/ui-kit/lib/utils";
import { type } from "@kulcare/ui-kit/lib/typography";

export function PatientCard({ patient, className }) {
  return (
    <div className={cn("rounded-lg border p-4", className)}>
      <h3 className={type.cardTitle}>{patient.name}</h3>
      <span className={type.patientId}>ID: {patient.id}</span>
    </div>
  );
}

Best PracticesCopy Anchor Link

1. Use Semantic TypographyCopy Anchor Link

// ✅ Good - Semantic class names
<h1 className={type.pageTitle}>Patient Dashboard</h1>

// ❌ Bad - Direct utility classes
<h1 className="text-3xl font-bold">Patient Dashboard</h1>

2. Leverage CSS Custom PropertiesCopy Anchor Link

/* ✅ Good - Use CSS variables for theming */
.custom-component {
  background: hsl(var(--card));
  color: hsl(var(--card-foreground));
}

/* ❌ Bad - Hardcoded colors */
.custom-component {
  background: #ffffff;
  color: #000000;
}

3. Healthcare Data DisplayCopy Anchor Link

// ✅ Good - Use monospace for medical values
<span className="font-medical">120/80 mmHg</span>

// ✅ Good - Status-based coloring
<span className={getVitalSignClasses(vitalStatus)}>
  {heartRate} bpm
</span>

4. Accessibility FirstCopy Anchor Link

• Always include proper ARIA labels
• Ensure sufficient color contrast (especially in dark mode)
• Test with keyboard navigation
• Provide clear focus indicators

ResourcesCopy Anchor Link

Internal DocumentationCopy Anchor Link

• Architecture Overview
• Component Storybook - Interactive component explorer
• Theme Configuration

External ResourcesCopy Anchor Link

• Tailwind CSS Documentation
• shadcn/ui Components
• WCAG Guidelines

ContributingCopy Anchor Link

When contributing to the design system:

1. Follow the established patterns - Consistency is key
2. Document new components - Add Storybook stories and documentation
3. Test accessibility - Ensure WCAG compliance
4. Consider healthcare context - Optimize for medical use cases
5. Review performance impact - Keep bundle sizes small

SupportCopy Anchor Link

For questions or issues related to the design system:

• Check the Troubleshooting Guide
• Review existing GitHub Issues
• Contact the platform team in #frontend Slack channel