design_guidelines.md

# InSono Design Guidelines

## Design Approach
**Selected Framework:** Material Design Medical Variant
**Rationale:** Medical research applications require clarity, trust, and efficiency. Material Design's elevation system and structured layouts provide excellent information hierarchy while maintaining professional credibility.

## Layout Architecture

**Spacing System:** Tailwind units of 4, 6, 8, 12, and 16 for consistent rhythm
- Component padding: p-6 to p-8
- Section spacing: py-12 to py-16
- Card margins: gap-6 to gap-8

**Container Strategy:**
- Primary workspace: max-w-7xl mx-auto px-6
- Metadata panels: max-w-sm for optimal readability
- Image viewers: Flexible width within constraints

## Typography Hierarchy

**Font Family:** 
- Primary: 'Inter' (Google Fonts) - exceptional readability for medical data
- Mono: 'JetBrains Mono' - metadata and technical values

**Scale:**
- App Title: text-3xl font-bold
- Section Headers: text-xl font-semibold
- Subsections: text-lg font-medium
- Body Text: text-base
- Metadata Labels: text-sm font-medium uppercase tracking-wide
- Metadata Values: text-sm font-mono

## Component Architecture

### Navigation Header
Fixed top bar with elevation (shadow-md):
- Logo + "InSono" branding on left
- Navigation links center-right: "Process Images", "About", "Documentation"
- Compact height (h-16)
- Research disclaimer badge (small, subtle)

### Upload Zone (Homepage Primary)
Full-width card with dashed border and centered content:
- Large upload icon (w-16 h-16)
- "Drag & Drop Ultrasound Images" headline
- Supported formats listed below: "PNG, JPG, DICOM (.dcm)"
- "Browse Files" secondary button
- File size limit indicator: "Max 50MB per file"
- Minimum height: min-h-96 for generous target area

### Processing Controls Panel
Horizontal card with segmented controls:
- Gaussian Blur slider (0-10 range) with live value display
- CLAHE toggle + intensity slider
- "Apply Processing" primary action button
- "Reset to Original" text button
- All controls inline for quick access

### Image Comparison Viewer
Side-by-side layout with equal-width columns (grid-cols-2):
- Column headers: "Original Image" | "Processed Image"
- Synchronized zoom/pan controls
- Image containers with aspect-ratio preservation
- Border between images for clear separation
- Pan/zoom indicators overlay bottom-right

### Metadata Display Panel
Vertical card (sticky positioning on scroll):
- Grouped sections with clear dividers
- **File Information**: Dimensions, file size, format
- **DICOM Tags** (when applicable): Modality, Study Date, Series Description
- **Processing Log**: Applied filters with parameters
- Each metadata item: Label (uppercase, muted) + Value (prominent, mono font)

### Privacy Controls
Floating action card above image viewer:
- "Pseudonymize Patient Info" toggle button
- When active: Semi-transparent black overlay (top-left 200x100px)
- Visual indicator showing protected region
- Warning text: "Protected area applied to export"

### Footer Disclaimer
Full-width, elevated section:
- Large warning icon
- Bold text: "RESEARCH USE ONLY - Not for Clinical Diagnosis"
- Secondary text explaining intended research use
- Links to documentation and compliance information
- Padding: py-8

## Interaction Patterns

**Drag & Drop States:**
- Default: Dashed border, neutral state
- Drag Over: Solid border, subtle scale transform
- Processing: Progress indicator overlay
- Error: Red border pulse animation

**Button Hierarchy:**
- Primary actions: Filled buttons with shadow
- Secondary actions: Outlined buttons
- Tertiary actions: Text-only buttons
- All buttons: Rounded corners (rounded-lg)

**Loading States:**
- Skeleton screens for image placeholders
- Linear progress bar for processing operations
- Spinner for metadata loading

## Visual Principles

**Medical Professionalism:**
- High contrast for readability
- Clear visual hierarchy
- Minimal decorative elements
- Focus on functionality and data clarity

**Trust Indicators:**
- Consistent elevation system (shadow-sm, shadow-md, shadow-lg)
- Professional typography
- Clear error messages and validation
- Visible privacy controls

**Information Density:**
- Comfortable spacing between elements
- Grouped related information
- Scannable metadata labels
- Clear visual separation between sections

## Images

**No large hero image** - This is a utility tool requiring immediate functionality access. All visual focus goes to uploaded ultrasound images within the processing interface.

## Responsive Behavior

**Desktop (lg+):** Side-by-side comparison, metadata sidebar
**Tablet (md):** Stacked comparison, metadata below
**Mobile:** Single column, collapsible metadata panel