# Design Guidelines: Family Advocacy AI Platform

## Design Approach

**Reference-Based Approach**: Drawing inspiration from legal tech platforms (LegalZoom, Clio) and document-focused applications (Notion, Dropbox Paper) while maintaining accessibility standards from government service portals.

**Core Principle**: Create a professional, trustworthy interface that reduces cognitive load for stressed parents while maintaining legal credibility and clarity.

---

## Typography System

**Font Families**:
- Primary: Inter (headings, UI elements) - clean, professional, excellent readability
- Secondary: System UI (body text, legal content) - optimal reading performance

**Hierarchy**:
- Page Titles: text-4xl font-bold (36px)
- Section Headers: text-2xl font-semibold (24px)
- Subsections: text-xl font-medium (20px)
- Body Text: text-base (16px) - generous line-height (1.7) for legal content
- Legal Citations: text-sm font-mono (13px) for statute references
- Helper Text: text-sm opacity-70 (14px)

---

## Layout System

**Spacing Primitives**: Use Tailwind units of 3, 4, 6, 8, 12, 16 for consistent rhythm
- Component padding: p-6 to p-8
- Section spacing: space-y-8 to space-y-12
- Card gaps: gap-6
- Form field spacing: space-y-4

**Grid Structure**:
- Max container width: max-w-7xl
- Dashboard: 12-column grid with 3-column sidebar (fixed navigation) + 9-column main content
- Two-column layouts for document viewer: 5-column document preview + 7-column AI analysis
- Single column for forms: max-w-2xl centered

---

## Component Library

### Navigation
- **Sidebar Navigation** (Desktop): Fixed left sidebar with clear iconography
  - Dashboard, Upload Documents, Case Analysis, Legal Resources, State Info
  - Progress indicator showing case completion status
  - Quick access to recently analyzed documents
- **Mobile Navigation**: Bottom tab bar with 4 primary actions

### Document Management
- **Upload Zone**: Large, prominent drag-and-drop area with clear file type indicators (PDF, DOC, DOCX icons)
  - Visual feedback on hover and during drag
  - File list showing: filename, type, upload date, analysis status
  - Batch actions: analyze selected, delete, download
- **Document Viewer**: Split-pane interface
  - Left: PDF/document preview with zoom controls
  - Right: AI analysis panel with collapsible sections

### Forms & Inputs
- **State Selection**: Prominent dropdown/autocomplete at onboarding
  - Include state abbreviation + full name
  - Confirmation modal showing selected jurisdiction
- **Text Inputs**: Generous height (h-12), clear labels above, helper text below
- **File Uploads**: Button + drag-drop zone combo with progress bars
- **Search**: Persistent search bar for legal resources with instant results

### Data Display
- **Case Report Cards**: Elevated cards (shadow-md) with:
  - Header: Case ID, date, status badge
  - Summary stats: Documents analyzed, violations found, recommendations
  - Primary action button
- **Legal Citation Blocks**: Monospace background panel with statute references
  - Include copy-to-clipboard functionality
- **Timeline View**: Vertical timeline showing case progression, key dates, and required actions

### AI Analysis Output
- **Violation Alerts**: Warning-style cards with severity indicators (critical/moderate/minor)
- **Recommendation Sections**: Collapsible accordions organized by topic:
  - Visitation Rights Analysis
  - Removal Procedure Review
  - Family Reunification Strategies
  - Long-term Impact Assessment
- **Evidence Builder**: Tabbed interface showing supporting research, legal precedents, and documentation gaps

### Modals & Overlays
- **Confirmation Dialogs**: Centered modals for critical actions (delete documents, submit reports)
- **Onboarding Flow**: Multi-step modal for state selection and case setup
- **Document Preview**: Full-screen overlay with semi-transparent backdrop

---

## Interactive Patterns

### Feedback & Status
- **Upload Progress**: Linear progress bars with percentage
- **Analysis Status**: 
  - Processing: Animated pulse indicator
  - Complete: Success checkmark with timestamp
  - Error: Clear error message with retry option
- **Loading States**: Skeleton screens for AI analysis generation

### Accessibility Features
- All interactive elements minimum 44px touch target
- Form labels always visible (no placeholder-only inputs)
- Skip navigation link for keyboard users
- ARIA labels for icon-only buttons
- High contrast mode support
- Clear focus indicators (ring-2 ring-offset-2)

---

## Page-Specific Layouts

### Dashboard Home
- Welcome header with user's case summary
- 3-column card grid: Documents Uploaded, Violations Identified, Actions Required
- Recent Activity feed
- Quick action buttons: Upload Document, View Full Report, Legal Resources

### Document Analysis Page
- Breadcrumb navigation
- Document metadata header
- Split view (as described in Components)
- Floating action button for "Generate Full Report"

### Legal Resources Library
- Filterable card grid by:
  - Document type (statutes, case law, research)
  - Topic (visitation, removal, reunification)
  - State jurisdiction
- Search with autocomplete
- Bookmark functionality

### Case Report View
- Printable layout with formal structure
- Executive Summary section
- Expandable detailed findings
- Export options (PDF, Word)

---

## Images

**Hero Image**: Not applicable for this web application - focus on functional dashboard layout rather than marketing hero

**Iconography**:
- Document type icons (PDF, DOC, DOCX) in upload interface
- Status icons (processing, complete, warning, error)
- Navigation icons (dashboard, upload, analysis, resources)
- Use Heroicons library for consistent style

**Illustrations**: Consider supportive, empathetic illustrations for:
- Empty states ("No documents uploaded yet")
- Onboarding screens (welcoming, not clinical)
- Error states (reassuring, not alarming)

---

## Emotional Design Considerations

Given the sensitive nature of child protection cases:
- Avoid red/alarm colors for standard UI elements
- Use reassuring, professional tones in microcopy
- Provide clear next steps and guidance throughout
- Include helpful tooltips explaining legal terminology
- Progress indicators to show users they're making headway