Keep/_bmad-output/implementation-artifacts/13-1-refactor-notebook-main-page-layout.md

Story 13.1: Refactor Notebook Main Page Layout

Status: ready-for-dev

Story

As a desktop user, I want a clean, modern notebook page layout with improved visual hierarchy, so that I can navigate and find my notes easily.

Acceptance Criteria

1. Given I am using the app on desktop (1024px+) When I view the notebook main page Then I should see a clean layout with sidebar on the left and content area on the right
2. And the sidebar should show: notebook list, filters, and actions
3. And the content area should show: note cards in a responsive grid
4. And the spacing should be consistent and visually pleasing
5. And the typography should be clear and readable
6. And the design should match the reference HTML code.html

Tasks / Subtasks

• Task 1: Analyze reference HTML code.html and extract design patterns (AC: #1, #6)

  • Subtask 1.1: Read and analyze code.html file structure
  • Subtask 1.2: Extract color palette, typography, spacing patterns
  • Subtask 1.3: Document reusable design tokens (colors, fonts, spacing)

• Task 2: Implement flexbox/grid layout for main page (AC: #1, #3)

  • Subtask 2.1: Create main layout container with flexbox (sidebar + content area)
  • Subtask 2.2: Implement responsive sidebar with proper breakpoints
  • Subtask 2.3: Create content area with masonry grid layout

• Task 3: Use Design System components (AC: #4, #5)

  • Subtask 3.1: Integrate existing Card component for note cards
  • Subtask 3.2: Use Button component from Design System
  • Subtask 3.3: Apply Badge component for labels

• Task 4: Apply consistent spacing (AC: #4)

  • Subtask 4.1: Implement 4px base unit spacing
  • Subtask 4.2: Apply consistent padding to sidebar and content area
  • Subtask 4.3: Ensure consistent margin between elements

• Task 5: Implement clear visual hierarchy (AC: #4, #5)

  • Subtask 5.1: Apply proper heading hierarchy (H1, H2, H3)
  • Subtask 5.2: Use consistent font sizes and weights
  • Subtask 5.3: Apply proper line height for readability

• Task 6: Implement responsive design for desktop (AC: #1, #6)

  • Subtask 6.1: Test at 1024px breakpoint (minimum desktop)
  • Subtask 6.2: Test at 1440px breakpoint (large desktop)
  • Subtask 6.3: Test at 1920px breakpoint (ultra-wide)
  • Subtask 6.4: Ensure design matches reference at all breakpoints

• Task 7: Test and validate (All AC)

  • Subtask 7.1: Manual testing on various desktop screen sizes
  • Subtask 7.2: Cross-browser testing (Chrome, Firefox, Safari)
  • Subtask 7.3: Accessibility testing (keyboard navigation, screen reader)

Dev Notes

Relevant Architecture Patterns and Constraints

Design System Integration (Epic 10):

• Must follow Design System patterns established in Epic 10
• Use existing Radix UI components (@radix-ui/react-*)
• Follow Tailwind CSS 4 conventions for styling
• Consistent color palette from design tokens

Desktop-Specific Design:

• Target resolution: 1024px+ (desktop only, not mobile)
• Reference HTML: code.html (must analyze this file)
• Modern visual hierarchy with clear information architecture
• Enhanced keyboard navigation support

Layout Patterns:

• Flexbox for main layout (sidebar + content area)
• Masonry grid for note cards (existing Muuri integration)
• Responsive breakpoints: 1024px, 1440px, 1920px
• Consistent 4px base unit spacing

Component Patterns:

• Use existing Card component from Design System
• Use existing Button component from Design System
• Use existing Badge component for labels
• Follow component composition patterns

Source Tree Components to Touch

Files to Modify:

keep-notes/app/(main)/page.tsx
  - Main notebook page layout
  - Update to use new layout structure

keep-notes/app/(main)/layout.tsx
  - May need updates for sidebar integration
  - Ensure consistent layout across main routes

keep-notes/components/sidebar.tsx
  - Existing sidebar component (refactor if needed)
  - Integrate with new layout structure

keep-notes/components/masonry-grid.tsx
  - Existing masonry grid (Muuri integration)
  - Ensure proper grid layout in content area

keep-notes/components/note-card.tsx
  - Existing note card component
  - Apply Design System styles if needed

Design Tokens to Use:

• Spacing: 4px base unit (8px, 12px, 16px, 24px, 32px)
• Colors: Follow design system color palette
• Typography: Follow design system font hierarchy
• Border radius: Consistent values across components

Testing Standards Summary

Manual Testing:

• Test on multiple desktop screen sizes (1024px, 1440px, 1920px)
• Test keyboard navigation (Tab, Enter, ESC, arrow keys)
• Test with mouse interactions (hover, click, drag)
• Visual inspection: match reference HTML design

Browser Testing:

• Chrome (latest)
• Firefox (latest)
• Safari (latest macOS)

Accessibility Testing:

• Keyboard navigation (Tab order logical, focus indicators visible)
• Screen reader compatibility (NVDA, VoiceOver)
• Contrast ratios (WCAG 2.1 AA: 4.5:1 for text)
• Touch targets (minimum 44x44px for interactive elements)

E2E Testing (Playwright):

• Tests in tests/e2e/notebook-layout.spec.ts
• Test layout rendering at different breakpoints
• Test keyboard navigation flow
• Test note card interactions

Project Structure Notes

Alignment with Unified Project Structure:

✅ Follows App Router Patterns:

• Page routes 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, Card, Badge, Dialog components
• Tailwind CSS 4 for styling

✅ Follows Naming Conventions:

• PascalCase component names: NotebookLayout, Sidebar, MasonryGrid
• camelCase function names: getLayoutProps, handleResize
• kebab-case file names: notebook-layout.tsx, sidebar.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:

⚠️ Reference HTML Analysis Needed:

• Must locate and analyze code.html reference file
• Extract design tokens (colors, typography, spacing)
• May need to create custom design tokens if not matching existing system

⚠️ Layout Complexity:

• Existing codebase may have legacy layout patterns
• May need to refactor existing sidebar and masonry grid components
• Ensure zero breaking changes to existing functionality

⚠️ Masonry Grid Integration:

• Existing Muuri integration (@dnd-kit for drag-and-drop)
• Must preserve drag-and-drop functionality during layout refactor
• Ensure masonry grid works with new flexbox layout

References

Source: _bmad-output/planning-artifacts/epics.md#Epic-13

• Epic 13: Desktop Design Refactor - Complete context and objectives
• Story 13.1: Refactor Notebook Main Page Layout - 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 component structure
• Masonry grid and drag-and-drop implementation

Source: docs/component-inventory.md

• Existing components catalog (20+ components)
• Card, Button, Badge, Dialog components from Radix UI
• Sidebar, MasonryGrid, NoteCard component documentation

Dev Agent Record

Agent Model Used

Claude Sonnet (claude-sonnet-3.5-20241022)

Debug Log References

None (new story)

Implementation Plan

Phase 1: Design Tokens Analysis (Task 1)

• ✅ Analyzed code.html reference file
• ✅ Extracted color palette, typography, spacing patterns
• ✅ Documented reusable design tokens

Design Tokens Extracted:

colors:
  primary: "#356ac0"
  background_light: "#f7f7f8"
  background_dark: "#1a1d23"
  white: "#ffffff"

typography:
  font_family: "Spline Sans, sans-serif"
  weights: [300, 400, 500, 600, 700]
  sizes:
    xs: "11-12px"
    sm: "13-14px"
    base: "16px"
    lg: "18px"
    xl: "20px"
    4xl: "36px"

spacing:
  base_unit: "4px"
  scale: [4, 8, 12, 16, 24, 32]  # 1x, 2x, 3x, 4x, 6x, 8x

border_radius:
  default: "0.5rem"  # 8px
  lg: "1rem"         # 16px
  xl: "1.5rem"       # 24px
  full: "9999px"

layout:
  sidebar_width: "16rem"   # 256px
  content_padding: "2.5rem" # 40px
  grid_gap: "1.5rem"      # 24px
  card_padding: "1.25rem"  # 20px

Layout Structure from code.html:

• Main container: flex flex-1 overflow-hidden
• Sidebar: w-64 flex-none flex flex-col bg-white dark:bg-[#1e2128] border-r
• Content: flex-1 overflow-y-auto bg-background-light dark:bg-background-dark p-6 md:p-10
• Notes grid: grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 auto-rows-max

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 browser compatibility requirements
• Documented potential conflicts with existing codebase
• Provided complete reference list with specific sections

File List

Story Output:

• _bmad-output/implementation-artifacts/13-1-refactor-notebook-main-page-layout.md

Source Files to Modify:

• keep-notes/app/(main)/page.tsx - Main notebook page
• keep-notes/app/(main)/layout.tsx - Main layout
• keep-notes/components/sidebar.tsx - Sidebar component
• keep-notes/components/masonry-grid.tsx - Masonry grid
• keep-notes/components/note-card.tsx - Note card component

Test Files to Create:

• keep-notes/tests/e2e/notebook-layout.spec.ts - E2E layout 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