Keep/15-1-redesign-mobile-navigation.md at 8f9031f07664d1eb4bd0c98ef3eb8a93837be717

sepehr ddb67ba9e5 fix: unify theme system - fix theme switching persistence

- 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

2026-01-18 22:33:41 +01:00

11 KiB

Raw Blame History

Status: ready-for-dev

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

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
When I tap the hamburger menu or bottom nav Then I should see a slide-out menu with: Notebooks, Settings, Profile, etc.
And the menu should have smooth animation
And I should be able to close the menu by tapping outside or tapping the close button
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)