sepehr
ddb67ba9e5
- Unified localStorage key to 'theme-preference' across all components
- Fixed header.tsx using wrong localStorage key ('theme' instead of 'theme-preference')
- Added localStorage hybrid persistence for instant theme changes
- Removed router.refresh() which was causing stale data revert
- Replaced Blue theme with Sepia
- Consolidated auth() calls to prevent race conditions
- Updated UserSettingsData types to include all themes
310 lines
11 KiB
Markdown
310 lines
11 KiB
Markdown
# 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`
|