VigilanzaTurni/design_guidelines.md

# Design Guidelines: Security Shift Management System

## Design Approach

**Selected Framework:** Material Design System
**Rationale:** Utility-focused operational software requiring efficiency, information density, and cross-platform consistency (web + mobile). Material Design provides robust patterns for data-heavy interfaces, clear visual hierarchy, and proven mobile components essential for field guards.

**Design Principles:**
- Operational clarity over aesthetic flourish
- Role-appropriate information density
- Instant status recognition through color/iconography
- Mobile-first for guard interactions, desktop-optimized for operations

---

## Core Design Elements

### A. Color Palette

**Dark Mode Primary (Default):**
- Primary: 210 100% 50% (Blue - trust, security, operational)
- Primary Variant: 210 100% 40% (darker blue for hierarchy)
- Secondary: 160 60% 45% (Teal - success, active duty)
- Background: 220 15% 12% (Dark operational background)
- Surface: 220 15% 16% (Cards, panels)
- Error: 0 70% 55% (Critical alerts, SOS)
- Warning: 35 90% 55% (Expiring certifications, delays)
- Success: 140 60% 45% (Completed, on-time)

**Light Mode:**
- Primary: 210 100% 45%
- Secondary: 160 60% 40%
- Background: 0 0% 98%
- Surface: 0 0% 100%

**Status Colors (Both Modes):**
- On Duty: 140 60% 45% (Green)
- Off Duty: 220 15% 50% (Gray)
- Late/Alert: 25 90% 55% (Orange)
- Emergency/SOS: 0 70% 55% (Red)
- Pending: 45 90% 55% (Amber)

### B. Typography

**Families:**
- Primary: Inter (system UI, operational clarity)
- Monospace: JetBrains Mono (IDs, timestamps, coordinates)

**Scale:**
- Display: 32px/40px (Dashboard titles)
- H1: 24px/32px (Section headers)
- H2: 20px/28px (Card titles, modal headers)
- H3: 16px/24px (Subsections)
- Body: 14px/20px (Standard content)
- Caption: 12px/16px (Metadata, timestamps)
- Small: 11px/14px (Dense tables, mobile labels)

**Weights:** 400 (regular), 500 (medium for emphasis), 600 (semibold for headers)

### C. Layout System

**Spacing Units:** Tailwind's 4px base - primary units: 2, 3, 4, 6, 8, 12, 16
- Component padding: p-4, p-6
- Section spacing: py-8, py-12
- Card gaps: gap-4, gap-6
- Mobile: Reduce by ~33% (p-3 instead of p-4)

**Grid System:**
- Dashboard: 12-column grid with sidebar (fixed 256px) + main content (fluid)
- Cards: 2-4 column grid on desktop (grid-cols-1 md:grid-cols-2 lg:grid-cols-3)
- Mobile: Single column stack, full-width cards

**Container Widths:**
- Operational views: max-w-full (utilize space)
- Forms/Details: max-w-4xl
- Client portal: max-w-6xl

### D. Component Library

**Navigation:**
- Sidebar (Desktop): Fixed left, collapsible, role-based menu items, active state with left border accent
- Top Bar: Role indicator, quick actions (SOS visible for guards), notifications, user menu
- Mobile: Bottom navigation (5 icons max) + hamburger for secondary

**Data Display:**
- Calendar: Week/month views, color-coded by shift type, hover shows details
- Timeline: Horizontal for daily shifts, vertical for guard history
- Tables: Sticky headers, row hover, sortable columns, row actions on right
- Cards: Elevated (shadow-md), rounded-lg, with status indicator strip on left edge
- Maps: Geofencing visualization with site pins, active guard markers, route tracking

**Forms:**
- Input fields: Outlined style (border-2), filled on dark mode (bg-surface)
- Select dropdowns: Native with custom chevron icon
- Date/Time pickers: Material-style with calendar popup
- Toggle switches: For binary states (armed/unarmed, active/inactive)
- Multi-select: Chips for selected items with remove icon

**Dashboards:**
- KPI Cards: Large number + trend indicator + sparkline
- Alert Panel: Expandable list with priority sorting, action buttons
- Live Status Grid: Card per guard/site with real-time badge updates
- Quick Actions: Floating action button (mobile) or fixed action bar (desktop)

**Mobile Specific (Guard App):**
- Large touch targets (min 44px height)
- Bottom-anchored primary actions
- Swipe gestures for quick actions (swipe right to clock in)
- Offline indicators with sync status
- GPS accuracy indicator on timeclock screen

**Client Portal:**
- Cleaner, less dense layouts than operational views
- Report cards with download buttons (PDF/Excel)
- Service status summary with visual progress indicators
- Timeline view of completed shifts with photos/notes

### E. Animations

**Essential Only:**
- Loading states: Skeleton screens (shimmer effect) for data loading
- Status changes: 200ms color fade for status badge updates
- Drawers/Modals: 250ms slide-in from right (drawers) or fade-in (modals)
- Live updates: Subtle pulse (once) on new alert/notification
- **No:** Page transitions, hover effects beyond color change, decorative animations

---

## Role-Specific Layouts

**Operations Dashboard (Admin/Coordinators):**
- Dense information grid, split-screen capable
- Left: Live status, alerts, SOS. Right: Schedule, assignments
- Quick filters always visible (site, date range, guard)

**Guard Mobile App:**
- Minimal chrome, focus on current shift
- Home: Current assignment + clock in/out (prominent)
- Bottom nav: Schedule, Sites, Reports, Profile
- Panic button: Always accessible (top-right corner, red)

**Client Portal:**
- Marketing-influenced landing (lighter touch)
- Dashboard: Service overview, recent reports
- Professional photography for site headers
- Cleaner spacing (py-16 sections vs py-8 operational)

---

## Images

**Not Applicable** - This is an operational system where images serve specific functions (guard photos, incident photos, site maps) rather than decorative purposes. Hero images not used. All imagery is functional: profile pictures (avatar), incident documentation (uploaded photos), location maps (geofencing), equipment photos (dotazioni).