5. UI/UX Requirements

5.1 Calculator Page

5.1.1 Layout Specification

Component: packages/desktop-app/src/components/CalculatorPage.tsx

Layout Structure:

┌─────────────────────────────────────────────────┐
│  Calculator Page                                │
│                                                 │
│  ┌───────────────────────────────────────────┐  │
│  │  Input Section (Card)                     │  │
│  │                                           │  │
│  │  ┌─────────────────────────────────────┐  │  │
│  │  │ Amount Input (Large)                │  │  │
│  │  │ Placeholder: "Enter amount..."      │  │  │
│  │  └─────────────────────────────────────┘  │  │
│  │                                           │  │
│  │  ┌──────────────┐  ┌──────────────────┐   │  │
│  │  │ Currency     │  │ Optimization Mode│   │  │
│  │  │ Dropdown     │  │ Dropdown         │   │  │
│  │  └──────────────┘  └──────────────────┘   │  │ 
│  │                                           │  │
│  │  [Calculate Button] - Full Width, Blue    │  │
│  └───────────────────────────────────────────┘  │
│                                                 │
│  ┌───────────────────────────────────────────┐  │
│  │  Results Section (After Calculation)      │  │
│  │                                           │  │
│  │  ┌────────┐ ┌────────┐ ┌──────────────┐   │  │
│  │  │ Total  │ │ Total  │ │ Total Denoms │   │  │
│  │  │ Notes  │ │ Coins  │ │              │   │  │
│  │  └────────┘ └────────┘ └──────────────┘   │  │
│  │                                           │  │
│  │  Breakdown Table                          │  │
│  │  Denomination | Type | Count | Value      │  │
│  │                                           │  │
│  │  [Copy] [Export CSV]                      │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

Required Elements

1. Amount Input Field

Type: number or text (validated)
Validation: Positive numbers only, max 15 digits
Placeholder: "Enter amount..."
Auto-focus: Yes (on page load)
Clear button: Yes
Format: Allow comma separators (e.g., 1,000,000)

2. Currency Dropdown

Options: INR, USD, EUR, GBP
Default: INR
Display: {code} - {name} (e.g., "INR - Indian Rupee")
Icons: Currency symbols (₹, $, €, £)

3. Optimization Mode Dropdown

Options: greedy, balanced, minimize_large, minimize_small
Default: greedy
Display: Capitalized with description
Tooltips: Explanation of each mode

4. Calculate Button

Style: Primary blue, full-width
States: Normal, Hover, Disabled, Loading
Loading: Show spinner when calculating
Keyboard: Enter key triggers calculation

5. Results Display (Conditional)

Show only after successful calculation
Animate entrance (fade in)
Summary cards with icons
Sortable breakdown table
Copy/Export buttons

Color Scheme

/* Light Mode */
--bg-primary: #ffffff
--bg-secondary: #f9fafb
--text-primary: #111827
--text-secondary: #6b7280
--border: #e5e7eb
--button-primary: #2563eb
--success: #10b981
--error: #ef4444

/* Dark Mode */
--bg-primary: #1f2937
--bg-secondary: #111827
--text-primary: #f9fafb
--text-secondary: #9ca3af
--border: #374151
--button-primary: #3b82f6
--success: #34d399
--error: #f87171

Responsive Breakpoints

Mobile: < 640px (single column)
Tablet: 640px - 1024px (2 columns)
Desktop: > 1024px (3 columns)

5.1.2 Input Validation Rules

Amount Field Validation

interface ValidationRules {
  required: true;
  min: 0.01;
  max: 999999999999999; // 15 digits
  pattern: /^\d+(\.\d{1,2})?$/; // Optional 2 decimal places
  errorMessages: {
    required: "Amount is required";
    min: "Amount must be greater than 0";
    max: "Amount too large (max 15 digits)";
    pattern: "Invalid amount format";
  }
}

Real-time Validation

Validate on blur
Show error message below input
Disable calculate button if invalid
Clear error on valid input

Edge Cases Handling

Input	Expected	Message
"0"	error	Amount must be > 0
"-100"	error	Negative not allowed
"abc"	error	Not a number
"1.234"	error	Max 2 decimals
"1,000"	valid	Value: 1000
"0.01"	valid	Minimum valid amount

5.1.3 User Interaction Flow

Happy Path:

User lands on Calculator page
Amount field auto-focused
User types amount: "50000"
User selects currency: "INR" (default selected)
User selects mode: "greedy" (default selected)
User clicks "Calculate" button OR presses Enter
Button shows loading state (spinner)
API request sent
Results appear with animation (< 100ms)
Summary cards + breakdown table displayed
User can copy or export results
User can modify inputs and recalculate

Error Path:

User enters invalid amount: "abc"
Error message appears: "Invalid amount format"
Calculate button disabled
User corrects input: "5000"
Error clears, button enabled
User clicks Calculate
API returns error (e.g., server down)
Error notification shown
Results section remains hidden
User can retry

5.1.4 Accessibility Requirements

MUST HAVE:

✓ ARIA labels on all form inputs
✓ Keyboard navigation (Tab, Shift+Tab, Enter)
✓ Focus indicators (visible outline)
✓ Screen reader announcements for results
✓ Error messages associated with inputs (aria-describedby)
✓ Sufficient color contrast (WCAG AA minimum)
✓ Focus trap in modals (if any)

Example Accessible Markup

<input
  type="text"
  id="amount"
  aria-label="Enter amount to calculate"
  aria-required="true"
  aria-invalid={hasError}
  aria-describedby={hasError ? "amount-error" : undefined}
/>
{hasError && (
  <div id="amount-error" role="alert">
    {errorMessage}
  </div>
)}

5.2 History Page

5.2.1 Layout Specification

Component: packages/desktop-app/src/components/HistoryPage.tsx

Layout:

┌────────────────────────────────────────────────┐
│  ┌─────────┐  ┌──────────────────────────────┐ │
│  │ Quick   │  │ Full History                 │ │
│  │ Access  │  │                              │ │
│  │(Sidebar)│  │ Filter Bar                   │ │
│  │         │  │ Currency | Date Range        │ │
│  │ Last 10 │  │                              │ │
│  │ Calcs   │  │ History Table                │ │
│  │         │  │ ID | Date | Amount | Cur...  │ │
│  │ 1.50000 │  │ ... paginated rows ...       │ │
│  │   INR   │  │                              │ │
│  │   Today │  │                              │ │
│  │         │  │ Pagination                   │ │
│  │ 2. 1000 │  │ << < 1 2 3 > >>              │ │
│  │   USD   │  │                              │ │
│  │   Today │  │                              │ │
│  │         │  │                              │ │
│  │ ...     │  │                              │ │
│  └─────────┘  └──────────────────────────────┘ │
└────────────────────────────────────────────────┘

Required Features

1. Quick Access Sidebar

Show last 10 calculations
Display: Amount, Currency, Date (relative)
Click: Load full details in main area
Scroll: Fixed position
Update: Real-time when new calc made

2. Filter Bar

Currency filter (All, INR, USD, EUR, GBP)
Date range picker
Clear filters button
Active filter count badge

3. History Table

Columns: ID, Date, Amount, Currency, Mode, Total Denoms, Actions
Sortable: By Date (default desc), Amount
Searchable: By amount
Selectable: Checkbox for batch delete
Actions: View, Delete

4. Pagination

Items per page: 50 (default), 100, 200
Page controls: First, Previous, Numbers, Next, Last
Total count displayed
URL param sync (optional)

5.2.2 Data Loading & Caching

Strategy: React Query with caching

const { data, isLoading, error, refetch } = useQuery({
  queryKey: ['history', page, filters],
  queryFn: () => api.getHistory(page, filters),
  staleTime: 5 * 60 * 1000, // 5 minutes
  cacheTime: 10 * 60 * 1000, // 10 minutes
  keepPreviousData: true, // Smooth pagination
});

Loading States

Initial load: Full skeleton loader
Pagination: Show previous data + loading spinner
Refetch: Subtle loading indicator
Empty state: "No calculations yet" message

Error States

Network error: Retry button
Server error: Contact support message
Empty results: "No matches" with clear filters button

5.3 Bulk Upload Page

5.3.1 Complete UI Specification

File: packages/desktop-app/src/components/BulkUploadPage.tsx (695 lines)

Phase 1: Upload (Idle)

┌──────────────────────────────────────────────┐
│ Bulk Upload & Processing                    │
│                                              │
│ ┌──────────────────────────────────────────┐ │
│ │ [Download CSV Template]                  │ │
│ └──────────────────────────────────────────┘ │
│                                              │
│ ┌──────────────────────────────────────────┐ │
│ │   Drag & Drop Area                       │ │
│ │                                          │ │
│ │  📁 Drag & drop your file here          │ │
│ │     or click to browse                   │ │
│ │                                          │ │
│ │  [Choose File]                           │ │
│ └──────────────────────────────────────────┘ │
│                                              │
│ Supported: CSV, PDF, Word, Images            │
│                                              │
│ ☑ Save to history                           │
│ [Upload & Process] (disabled)                │
└──────────────────────────────────────────────┘

Phase 2: File Selected

┌──────────────────────────────────────────────┐
│ ┌──────────────────────────────────────────┐ │
│ │   Selected File:                         │ │
│ │   📄 test_bulk_upload.csv                │ │
│ │  Format: CSV • Size: 1.25 KB             │ │
│ │  [Remove File]                           │ │
│ └──────────────────────────────────────────┘ │
│                                              │
│ ☑ Save to history                           │
│ [Upload & Process] (enabled, blue)           │
└──────────────────────────────────────────────┘

Phase 3: Processing

┌──────────────────────────────────────────────┐
│ ┌──────────────────────────────────────────┐ │
│ │   Processing Data...                     │ │
│ │                                          │ │
│ │   📄 test_bulk_upload.csv                │ │
│ │  CSV • 1.25 KB                           │ │
│ │                                          │ │
│ │  [Spinner Animation]                     │ │
│ │  Extracting and calculating...           │ │
│ └──────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘

Phase 4: Results

┌──────────────────────────────────────────────┐
│ ┌──────────────────────────────────────────┐ │
│ │ Processed File:                          │ │
│ │  📄 test_bulk_upload.csv                 │ │
│ │ Format: CSV • Size: 1.25 KB              │ │
│ │ Processed: Nov 25, 2025 10:30 AM         │ │
│ └──────────────────────────────────────────┘ │
│                                              │
│ ┌──────┐ ┌───────┐ ┌──────┐ ┌──────────┐   │
│ │Total │ │Success│ │Failed│ │  Time    │   │
│ │  10  │ │   9   │ │  1   │ │ 0.12s    │   │
│ └──────┘ └───────┘ └──────┘ └──────────┘   │
│                                              │
│ [Upload Another] [Export CSV] [Export JSON]  │
│                                              │
│ ┌──────────────────────────────────────────┐ │
│ │ Results Table                            │ │
│ │ Row | Status | Amount | Currency | ...   │ │
│ │  1  │   ✓    │ 1000   │   INR    │       │ │
│ │  2  │   ✓    │ 2500   │   USD    │       │ │
│ │  3  │   ✗    │        │          │ Err   │ │
│ └──────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘

5.4 Settings Page

5.4.1 Layout Sections

1. Appearance

┌───────────────────────────────────┐
│ Appearance                        │
│                                   │
│ Theme                             │
│  ◉ Light  ○ Dark  ○ System        │
│                                   │
│ [Save Settings]                   │
└───────────────────────────────────┘

2. Language & Region

┌───────────────────────────────────┐
│ Language & Region                 │
│                                   │
│ Language                          │
│ [English ▼]                       │
│   - English                       │
│   - हिंदी (Hindi)                │
│   - Español (Spanish)             │
│   - Français (French)             │
│   - Deutsch (German)              │
│                                   │
│ [Save Settings]                   │
└───────────────────────────────────┘

3. Default Preferences

┌───────────────────────────────────┐
│ Default Preferences               │
│                                   │
│ Default Currency                  │
│ [INR ▼]                           │
│                                   │
│ Default Optimization Mode         │
│ [Greedy ▼]                        │
│                                   │
│ ☑ Auto-save to history            │
│                                   │
│ [Save Settings] [Reset]           │
└───────────────────────────────────┘

4. Data Management

┌───────────────────────────────────┐
│ Data Management                   │
│                                   │
│ History                           │
│ Total calculations: 1,234         │
│ Database size: 5.2 MB             │
│                                   │
│ [Export All History]              │
│ [Clear All History] (red)         │
│                                   │
│ [Reset All Settings]              │
└───────────────────────────────────┘

5.4.2 Confirmation Dialogs

Clear All History?

This will permanently delete all 1,234 calculations from your history. This action cannot be undone.

[Cancel] [Delete All History]

Reset All Settings?

This will restore all settings to their default values:

Theme: Light
Language: English
Currency: INR
Mode: Greedy
Auto-save: Enabled

Your calculation history will NOT be affected.

[Cancel] [Reset Settings]

5.7 Responsive Design Rules

5.7.1 Breakpoint System

const breakpoints = {
  sm: '640px',   // Mobile landscape, small tablets
  md: '768px',   // Tablets
  lg: '1024px',  // Laptops
  xl: '1280px',  // Desktops
  '2xl': '1536px' // Large desktops
};

5.7.2 Mobile Behavior (< 640px)

MUST:

Single column layout
Full-width buttons
Stacked form fields
Collapsible navigation (hamburger menu)
Touch-friendly tap targets (min 44px)
Simplified tables (responsive cards)

Example Responsive Classes

<!-- Desktop: 3 columns, Mobile: 1 column -->
<div className="grid grid-cols-1 md:grid-cols-3 gap-4">

<!-- Desktop: Row, Mobile: Column -->
<div className="flex flex-col md:flex-row gap-4">

<!-- Hide on mobile -->
<div className="hidden md:block">

<!-- Show only on mobile -->
<div className="block md:hidden">

✓ Section Complete

This section covers all UI/UX requirements for Calculator, History, Bulk Upload, and Settings pages including layouts, validation, accessibility, and responsive design.