# Product Requirements Document

## Validation Checklist

- [x] All required sections are complete
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Problem statement is specific and measurable
- [x] Problem is validated by evidence (not assumptions)
- [x] Context → Problem → Solution flow makes sense
- [x] Every persona has at least one user journey
- [x] All MoSCoW categories addressed (Must/Should/Could/Won't)
- [x] Every feature has testable acceptance criteria
- [x] Every metric has corresponding tracking events
- [x] No feature redundancy (check for duplicates)
- [x] No contradictions between sections
- [x] No technical implementation details included
- [x] A new team member could understand this PRD

---

## Product Overview

### Vision
Create a space-efficient admin navigation experience where the sidebar stays out of the way until needed, giving users more room to focus on their actual work.

### Problem Statement
The current 250px fixed admin sidebar permanently consumes ~20% of screen width on typical 1280px displays. This reduces the usable content area for data-heavy admin pages like Reports, Daybook, and Floor Plan Designer. Users on smaller screens (laptops, tablets) are particularly impacted, often needing to scroll horizontally or work with cramped tables and charts.

**Evidence:**
- Admin pages contain 14 main sections with 50+ sub-items
- Most users navigate to a section, then work within that page for extended periods
- Current sidebar is always visible but only actively used for ~5% of session time
- Competitive admin panels (Shopify, Stripe, HubSpot) all use collapsible sidebars

### Value Proposition
By collapsing the sidebar to icon-only by default and expanding on hover, users gain 190px of additional horizontal space for content. This improves data visibility on dashboard tables, chart readability, and reduces horizontal scrolling on constrained screens—without losing quick access to navigation.

## User Personas

### Primary Persona: Store Manager (Maria)
- **Demographics:** 28-45, manages 1-3 stores, moderate technical expertise
- **Goals:** Review daily reports, manage team schedules, process customer issues quickly
- **Pain Points:** Feels cramped on her 13" laptop, frequently switches between sections but spends most time reading data

### Secondary Persona: Store Owner (David)
- **Demographics:** 40-60, oversees multiple locations, lower technical expertise
- **Goals:** Quick overview of store performance, rarely digs into settings
- **Pain Points:** Overwhelmed by number of menu options, wants faster access to key reports

### Secondary Persona: Super Admin (Engineering/Support)
- **Demographics:** Technical staff, uses multiple browser windows
- **Goals:** Quick navigation between stores and admin sections
- **Pain Points:** Needs to see full menu labels, switches rapidly between sections

## User Journey Maps

### Primary User Journey: Daily Report Review (Maria)
1. **Awareness:** Opens admin panel to start day
2. **Consideration:** Scans sidebar for Reports section
3. **Adoption:** Clicks to expand, selects "Daily Close Reports"
4. **Usage:** Spends 15-30 minutes reviewing data, sidebar no longer needed
5. **Retention:** Appreciates extra space for report tables, returns daily

### Secondary User Journey: Quick Store Check (David)
1. **Awareness:** Receives text about store issue
2. **Consideration:** Opens admin, needs Dashboard quickly
3. **Adoption:** Hovers sidebar to see options, recognizes Dashboard icon
4. **Usage:** Views dashboard metrics, done in 2 minutes
5. **Retention:** Likes that sidebar didn't obstruct his limited screen space

### Secondary User Journey: Multi-Store Administration (Super Admin)
1. **Awareness:** Supporting multiple stores simultaneously
2. **Consideration:** Needs store picker and section access
3. **Adoption:** Prefers expanded state, uses pin to keep sidebar open
4. **Usage:** Rapidly switches between stores and sections
5. **Retention:** Appreciates option to keep sidebar expanded when needed

## Feature Requirements

### Must Have Features

#### Feature 1: Collapsed Default State
- **User Story:** As a store manager, I want the sidebar collapsed by default so that I have maximum space for content
- **Acceptance Criteria:**
  - [ ] Sidebar displays at 64px width when collapsed (icon + padding)
  - [ ] Only icons are visible in collapsed state
  - [ ] Store logo/picker area shows abbreviated store ID only
  - [ ] MetisMenu submenu arrows hidden in collapsed state
  - [ ] Active menu item has visible indicator in collapsed state

#### Feature 2: Hover-to-Expand
- **User Story:** As a user, I want the sidebar to expand when I hover over it so that I can see full labels and navigate
- **Acceptance Criteria:**
  - [ ] Sidebar expands to 250px on mouse enter
  - [ ] Expansion includes slight delay (150-200ms) to prevent accidental triggers
  - [ ] Full text labels appear alongside icons
  - [ ] Store picker shows full store name and city
  - [ ] Submenu functionality (MetisMenu) works normally when expanded
  - [ ] Sidebar collapses when mouse leaves (after 200ms delay)

#### Feature 3: Smooth Animation
- **User Story:** As a user, I want the expand/collapse to feel smooth and polished
- **Acceptance Criteria:**
  - [ ] Width transition uses easing curve (ease-out), 200-250ms duration
  - [ ] Text labels fade in during expansion (opacity transition)
  - [ ] No layout shifts or jumps in main content area
  - [ ] Animation performs at 60fps on modern browsers

#### Feature 4: Tooltips for Collapsed Icons
- **User Story:** As a new user, I want to see what each icon means when hovering in collapsed state
- **Acceptance Criteria:**
  - [ ] Hovering over collapsed icon shows tooltip with section name
  - [ ] Tooltip appears to the right of the sidebar
  - [ ] Tooltip has slight delay (300ms) before appearing
  - [ ] Tooltip disappears immediately on mouse leave or sidebar expand

### Should Have Features

#### Feature 5: Pin/Lock Expanded State
- **User Story:** As a power user, I want to pin the sidebar open so it stays expanded while I navigate
- **Acceptance Criteria:**
  - [ ] Pin icon appears in expanded sidebar header
  - [ ] Clicking pin locks sidebar in expanded state
  - [ ] Pinned state persists across page navigation (session)
  - [ ] Un-pinning returns to hover behavior
  - [ ] Visual indicator shows when sidebar is pinned

#### Feature 6: User Preference Persistence
- **User Story:** As a returning user, I want my sidebar preference remembered
- **Acceptance Criteria:**
  - [ ] Pin state saved to localStorage
  - [ ] Preference restored on next visit
  - [ ] Works across browser sessions

### Could Have Features

#### Feature 7: Keyboard Navigation
- **User Story:** As a keyboard user, I want to expand/collapse the sidebar with a shortcut
- **Acceptance Criteria:**
  - [ ] Keyboard shortcut (e.g., Cmd/Ctrl + \) toggles sidebar
  - [ ] Focus states visible for keyboard navigation
  - [ ] Screen reader announces state changes

#### Feature 8: Touch Device Support
- **User Story:** As a tablet user, I want sidebar to work without hover
- **Acceptance Criteria:**
  - [ ] Tap on collapsed sidebar expands it
  - [ ] Tap outside collapses (like mobile currently works)
  - [ ] No double-tap needed

### Won't Have (This Phase)

- **Resizable sidebar** - Users cannot drag to custom width
- **Per-section collapse memory** - Which submenus were open not persisted
- **Different collapsed widths** - Single 64px collapsed width only
- **Mini-map/preview on hover** - No peek at submenu without expanding
- **Programmatic collapse** - No API to control via JavaScript initially

## Detailed Feature Specifications

### Feature: Hover-to-Expand Behavior

**Description:** The sidebar responds to mouse presence with intelligent timing to expand/collapse smoothly without accidental triggers.

**User Flow:**
1. User moves cursor toward left side of screen
2. Cursor enters collapsed sidebar area (64px)
3. System waits 150ms to confirm intent (not just passing through)
4. Sidebar animates to 250px width over 200ms
5. User navigates menu, possibly clicking to expand submenus
6. User moves cursor to main content area
7. System waits 200ms then collapses sidebar
8. User continues working with full content width

**Business Rules:**
- Rule 1: If cursor moves from collapsed sidebar directly to expanded menu area, no collapse delay applies (continuous interaction)
- Rule 2: If page navigation occurs while expanded, sidebar remains expanded until mouse leaves after new page loads
- Rule 3: If sidebar is pinned, hover behavior is disabled and sidebar stays expanded
- Rule 4: On mobile/touch devices, hover is replaced with tap-to-toggle

**Edge Cases:**
- Scenario 1: User rapidly moves cursor in/out → Delays prevent jittery expand/collapse
- Scenario 2: Dropdown menu extends beyond sidebar → Menu items remain clickable, sidebar doesn't collapse while dropdown is open
- Scenario 3: User clicks submenu item during collapse animation → Click registered, navigation proceeds
- Scenario 4: Page loads with cursor already over sidebar area → Expand immediately (no delay on initial load)

## Success Metrics

### Key Performance Indicators

- **Adoption:** 90% of admin page views use collapsed sidebar (not pinned)
- **Engagement:** Average sidebar interaction time decreases by 30% (faster navigation)
- **Quality:** Zero user-reported issues with accidental expand/collapse
- **Business Impact:** Support tickets about "small screen" or "cramped tables" decrease 50%

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| `sidebar_expand` | `trigger: hover/pin/keyboard`, `duration_ms` | Track how users trigger expansion |
| `sidebar_collapse` | `trigger: mouseout/unpin/keyboard`, `duration_ms` | Track collapse patterns |
| `sidebar_pin` | `action: pin/unpin`, `session_id` | Track power user behavior |
| `sidebar_nav_click` | `section`, `subsection`, `collapsed_state` | Track navigation from each state |

---

## Constraints and Assumptions

### Constraints
- Must work with existing MetisMenu jQuery plugin
- Must not break mobile overlay behavior (already has its own collapse)
- CSS changes must go through design system build process
- Must support all current browsers (Chrome, Safari, Firefox, Edge latest 2 versions)

### Assumptions
- Users prefer more content space over always-visible navigation
- 64px provides enough width for recognizable Font Awesome icons
- 150-200ms delays feel natural and not sluggish
- Store picker can be abbreviated to typeNum only in collapsed state

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Users confused by collapsed icons | Medium | Low | Tooltips + consistent FA icons already learned |
| Accidental triggers frustrate users | High | Medium | Tuned delays, extensive testing |
| Animation jank on older devices | Medium | Low | CSS transitions (hardware accelerated), test on target devices |
| Breaking existing MetisMenu behavior | High | Low | Thorough testing of all submenu states |
| Touch devices have poor hover experience | Medium | Medium | Detect touch, use tap-to-toggle |

## Open Questions

- [x] Which sidebar to target? → Admin Sidebar (confirmed)
- [x] Should collapsed state persist across sessions? → Yes, via localStorage
- [x] What about existing mobile behavior? → Keep separate, mobile uses overlay
- [ ] Should different user roles have different defaults? → Start same for all, gather feedback

---

## Supporting Research

### Competitive Analysis

| Product | Sidebar Behavior | Collapsed Width | Expansion Trigger |
|---------|-----------------|-----------------|-------------------|
| Shopify Admin | Collapsible, icon-only | 56px | Hover + Pin option |
| Stripe Dashboard | Collapsible | 64px | Hover, auto-collapse |
| HubSpot | Collapsible | 60px | Click to toggle, hover sub-items |
| Salesforce | Collapsible | 52px | Click to toggle |
| Linear | Collapsible | 48px | Hover, very fast |

**Key Insight:** All major SaaS admin panels now use collapsible sidebars. Hover-to-expand is the dominant pattern, with pin options for power users.

### User Research

Based on observation:
- Store managers primarily work within 1-2 sections per session
- Navigation happens at start of tasks, then users focus on content
- Complaints about cramped interfaces come from laptop users
- Mobile users already have collapsed experience (overlay)

### Market Data

- Average laptop screen: 1366x768 to 1920x1080
- 250px sidebar = 18-32% of screen width
- 64px sidebar = 3-5% of screen width (6x improvement)

**UX Best Practices Sources:**
- [Best UX Practices for Sidebar Menu Design in 2025](https://uiuxdesigntrends.com/best-ux-practices-for-sidebar-menu-in-2025/)
- [Best UX Practices for Designing a Sidebar - UX Planet](https://uxplanet.org/best-ux-practices-for-designing-a-sidebar-9174ee0ecaa2)
- [Expandable/Collapsible Sidebar Menus Pros and Cons](https://groovymenu.grooni.com/expandable-collapsible-sidebar-menus-on-website-pros-and-cons/)