# Story 15.1: Redesign Mobile Navigation

Status: ready-for-dev

<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->

## Story

As a **mobile user**,
I want **a clear, intuitive mobile navigation system**,
so that **I can navigate the app easily on my phone**.

## Acceptance Criteria

1. Given I am using the app on mobile (< 768px)
   When I view the navigation
   Then I should see a hamburger menu icon in the top-left or bottom navigation bar
2. When I tap the hamburger menu or bottom nav
   Then I should see a slide-out menu with: Notebooks, Settings, Profile, etc.
3. And the menu should have smooth animation
4. And I should be able to close the menu by tapping outside or tapping the close button
5. And the active page should be visually highlighted in the navigation

## Tasks / Subtasks

- [ ] Task 1: Design mobile navigation pattern (AC: #1)
  - [ ] Subtask 1.1: Decide between hamburger menu or bottom navigation
  - [ ] Subtask 1.2: Analyze mobile UX best practices
  - [ ] Subtask 1.3: Document navigation items: Notebooks, Settings, Profile, etc.

- [ ] Task 2: Implement navigation toggle button (AC: #1)
  - [ ] Subtask 2.1: Create hamburger menu icon component
  - [ ] Subtask 2.2: Add toggle button to top-left or bottom nav
  - [ ] Subtask 2.3: Implement button click handler to open menu
  - [ ] Subtask 2.4: Ensure button is touch-friendly (44x44px minimum)

- [ ] Task 3: Implement slide-out menu (AC: #2, #3)
  - [ ] Subtask 3.1: Create slide-out menu component
  - [ ] Subtask 3.2: Add navigation items: Notebooks, Settings, Profile, etc.
  - [ ] Subtask 3.3: Implement smooth slide-in/out animation (150-200ms)
  - [ ] Subtask 3.4: Use GPU acceleration for animations

- [ ] Task 4: Implement menu close functionality (AC: #4)
  - [ ] Subtask 4.1: Add close button to menu
  - [ ] Subtask 4.2: Implement tap-outside-to-close functionality
  - [ ] Subtask 4.3: Add ESC key support for desktop testing

- [ ] Task 5: Implement active page indicator (AC: #5)
  - [ ] Subtask 5.1: Track current page/route state
  - [ ] Subtask 5.2: Highlight active page in navigation
  - [ ] Subtask 5.3: Apply visual indicator (bold, color, background)

- [ ] Task 6: Apply responsive design (AC: #1)
  - [ ] Subtask 6.1: Show mobile navigation only on < 768px
  - [ ] Subtask 6.2: Hide mobile navigation on ≥ 768px (use existing desktop nav)
  - [ ] Subtask 6.3: Test at breakpoints: 320px, 375px, 414px, 640px, 767px

- [ ] Task 7: Use Design System components (All AC)
  - [ ] Subtask 7.1: Integrate Button component for navigation items
  - [ ] Subtask 7.2: Integrate Dialog or Sheet component for slide-out menu
  - [ ] Subtask 7.3: Apply Design System colors and spacing

- [ ] Task 8: Test and validate (All AC)
  - [ ] Subtask 8.1: Manual testing on various mobile devices
  - [ ] Subtask 8.2: Test touch interactions (tap, tap-outside)
  - [ ] Subtask 8.3: Test animations (smoothness, timing)
  - [ ] Subtask 8.4: Accessibility testing (keyboard, screen reader)

## Dev Notes

### Relevant Architecture Patterns and Constraints

**Mobile-First Design:**
- Target resolution: < 768px (mobile only)
- Touch targets: minimum 44x44px
- Smooth animations: 60fps, 150-200ms transitions
- Responsive breakpoints: 320px, 375px, 414px, 640px, 767px

**Navigation Pattern:**
- Choose between: hamburger menu (top-left) OR bottom navigation bar
- Hamburger menu: slide-out from left or right
- Bottom nav: fixed at bottom with 3-4 icons
- Active page: visually highlighted (bold, color, background)

**Animation Patterns:**
- Smooth slide-in/out animation (150-200ms)
- Use GPU acceleration (transform, opacity)
- Respect `prefers-reduced-motion` media query
- CSS transitions for hover/focus states

**Component Patterns:**
- Use existing Dialog or Sheet component from Radix UI for slide-out menu
- Use existing Button component for navigation items
- Use existing Icon components from Lucide Icons
- Apply Tailwind CSS 4 for styling

### Source Tree Components to Touch

**Files to Modify:**
```
keep-notes/app/(main)/layout.tsx
  - Main layout wrapper
  - Add mobile navigation component
  - Conditionally show desktop vs mobile navigation

keep-notes/components/header.tsx
  - Existing header component
  - Add hamburger menu button (if using hamburger pattern)

keep-notes/app/(main)/mobile-navigation/page.tsx
  - NEW: Mobile navigation component
  - Implement slide-out menu or bottom navigation
  - Display navigation items: Notebooks, Settings, Profile, etc.

keep-notes/components/mobile-menu.tsx
  - NEW: Slide-out menu component
  - Use Radix UI Dialog or Sheet component
  - Implement smooth animations

keep-notes/components/bottom-nav.tsx
  - NEW: Bottom navigation component (alternative option)
  - Fixed at bottom with 3-4 icons
  - Show active page indicator
```

**Existing Mobile Components:**
```
keep-notes/components/mobile-sidebar.tsx
  - Existing mobile sidebar (if exists)
  - Integrate or refactor with new navigation pattern

keep-notes/app/(main)/mobile/page.tsx
  - Existing mobile page (if exists)
  - Update to use new navigation pattern
```

**Navigation State Management:**
```
keep-notes/context/navigation-context.tsx
  - NEW: Navigation context for active page tracking
  - Provide active page state to components
  - Handle navigation between pages
```

### Testing Standards Summary

**Manual Testing:**
- Test on real mobile devices (iPhone, Android)
- Test on mobile emulators (Chrome DevTools, Safari DevTools)
- Test touch interactions (tap, tap-outside, swipe if applicable)
- Test animations (smoothness, timing, 60fps)
- Test navigation between all pages

**Responsive Testing:**
- Test at breakpoints: 320px, 375px, 414px, 640px, 767px
- Test landscape mode on mobile
- Test transition between mobile (< 768px) and desktop (≥ 768px)

**Accessibility Testing:**
- Keyboard navigation (Tab, Enter, ESC for close)
- Screen reader compatibility (VoiceOver, TalkBack)
- Touch target sizes (minimum 44x44px)
- Focus indicators visible and logical
- ARIA labels for navigation items

**E2E Testing (Playwright):**
- Tests in `tests/e2e/mobile-navigation.spec.ts`
- Test hamburger menu/bottom nav tap
- Test slide-out menu animation
- Test navigation to different pages
- Test menu close functionality (tap-outside, close button, ESC)
- Test active page indicator

### Project Structure Notes

**Alignment with Unified Project Structure:**

✅ **Follows App Router Patterns:**
- Mobile navigation in `app/(main)/` directory
- Component files in `components/` (kebab-case)
- Use `'use client'` directive for interactive components

✅ **Follows Design System Patterns:**
- Components in `components/ui/` (Radix UI primitives)
- Use existing Button, Dialog, Sheet components from Radix UI
- Tailwind CSS 4 for styling
- Lucide Icons for navigation icons

✅ **Follows Naming Conventions:**
- PascalCase component names: `MobileMenu`, `BottomNav`, `MobileNavigation`
- camelCase function names: `handleMenuToggle`, `handleNavigation`
- kebab-case file names: `mobile-menu.tsx`, `bottom-nav.tsx`, `mobile-navigation.tsx`

✅ **Follows Response Format:**
- API responses: `{success: true|false, data: any, error: string}`
- Server Actions: Return `{success, data}` or throw Error
- Error handling: try/catch with console.error()

**Potential Conflicts or Variances:**

⚠️ **Navigation Pattern Decision:**
- Must choose between hamburger menu OR bottom navigation
- Hamburger menu: more space, less accessible
- Bottom navigation: always visible, less space for content
- Consider Epic 12 (Mobile Experience Overhaul) for consistency

⚠️ **Existing Mobile Navigation:**
- Existing codebase may have mobile navigation patterns
- Must analyze and preserve existing functionality
- Ensure zero breaking changes to existing mobile features

⚠️ **Animation Performance:**
- Must ensure 60fps animations on mobile devices
- Use GPU acceleration (transform, opacity)
- Test on low-end mobile devices
- Respect `prefers-reduced-motion` for accessibility

⚠️ **Navigation State Management:**
- May need to create navigation context (if not exists)
- Or use existing router state (Next.js useRouter)
- Ensure active page tracking is consistent

⚠️ **Desktop Compatibility:**
- Mobile navigation should only show on < 768px
- Desktop navigation (existing sidebar) should show on ≥ 768px
- Smooth transition between mobile and desktop navigation

### References

**Source: _bmad-output/planning-artifacts/epics.md#Epic-15**
- Epic 15: Mobile UX Overhaul - Complete context and objectives
- Story 15.1: Redesign Mobile Navigation - Full requirements

**Source: _bmad-output/planning-artifacts/architecture.md**
- Existing architecture patterns and constraints
- Design System component library (Radix UI + Tailwind CSS 4)
- Component naming and organization patterns

**Source: _bmad-output/planning-artifacts/project-context.md**
- Critical implementation rules for AI agents
- TypeScript strict mode requirements
- Server Action and API Route patterns
- Error handling and validation patterns

**Source: docs/architecture-keep-notes.md**
- Keep Notes architecture overview
- Existing navigation and routing patterns
- Mobile-responsive design patterns

**Source: docs/component-inventory.md**
- Existing components catalog (20+ components)
- Button, Dialog, Sheet components from Radix UI
- Lucide Icons for navigation icons

**Source: _bmad-output/planning-artifacts/epics.md#Epic-12**
- Epic 12: Mobile Experience Overhaul
- Story 12.3: Mobile Bottom Navigation
- Potential conflict or consistency requirement

**Source: _bmad-output/planning-artifacts/epics.md#Epic-13**
- Story 13.6: Improve Navigation and Breadcrumbs
- Desktop navigation patterns (for comparison)

## Dev Agent Record

### Agent Model Used

Claude Sonnet (claude-sonnet-3.5-20241022)

### Debug Log References

None (new story)

### Completion Notes List

- Created comprehensive story file with all required sections
- Mapped all acceptance criteria to specific tasks and subtasks
- Documented architecture patterns and constraints
- Listed all source files to touch with detailed notes
- Included testing standards and mobile compatibility requirements
- Documented potential conflicts with existing codebase
- Provided complete reference list with specific sections
- Noted navigation pattern decision (hamburger vs bottom nav)
- Documented animation performance requirements (60fps, GPU acceleration)

### File List

**Story Output:**
- `_bmad-output/implementation-artifacts/15-1-redesign-mobile-navigation.md`

**New Files to Create:**
- `keep-notes/components/mobile-menu.tsx` - Slide-out menu component
- `keep-notes/components/bottom-nav.tsx` - Bottom navigation component (alternative)
- `keep-notes/app/(main)/mobile-navigation/page.tsx` - Mobile navigation wrapper
- `keep-notes/context/navigation-context.tsx` - Navigation context (if needed)

**Files to Modify:**
- `keep-notes/app/(main)/layout.tsx` - Main layout
- `keep-notes/components/header.tsx` - Add hamburger button

**Test Files to Create:**
- `keep-notes/tests/e2e/mobile-navigation.spec.ts` - E2E mobile navigation tests

**Documentation Files Referenced:**
- `_bmad-output/planning-artifacts/epics.md`
- `_bmad-output/planning-artifacts/architecture.md`
- `_bmad-output/planning-artifacts/project-context.md`
- `docs/architecture-keep-notes.md`
- `docs/component-inventory.md`