# Story 13.1: Refactor Notebook Main Page Layout

Status: ready-for-dev

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

## 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

- [x] Task 1: Analyze reference HTML `code.html` and extract design patterns (AC: #1, #6)
  - [x] Subtask 1.1: Read and analyze `code.html` file structure
  - [x] Subtask 1.2: Extract color palette, typography, spacing patterns
  - [x] Subtask 1.3: Document reusable design tokens (colors, fonts, spacing)

- [x] Task 2: Implement flexbox/grid layout for main page (AC: #1, #3)
  - [x] Subtask 2.1: Create main layout container with flexbox (sidebar + content area)
  - [x] Subtask 2.2: Implement responsive sidebar with proper breakpoints
  - [x] Subtask 2.3: Create content area with masonry grid layout

- [x] Task 3: Use Design System components (AC: #4, #5)
  - [x] Subtask 3.1: Integrate existing Card component for note cards
  - [x] Subtask 3.2: Use Button component from Design System
  - [x] Subtask 3.3: Apply Badge component for labels

- [x] Task 4: Apply consistent spacing (AC: #4)
  - [x] Subtask 4.1: Implement 4px base unit spacing
  - [x] Subtask 4.2: Apply consistent padding to sidebar and content area
  - [x] Subtask 4.3: Ensure consistent margin between elements

- [x] Task 5: Implement clear visual hierarchy (AC: #4, #5)
  - [x] Subtask 5.1: Apply proper heading hierarchy (H1, H2, H3)
  - [x] Subtask 5.2: Use consistent font sizes and weights
  - [x] Subtask 5.3: Apply proper line height for readability

- [x] Task 6: Implement responsive design for desktop (AC: #1, #6)
  - [x] Subtask 6.1: Test at 1024px breakpoint (minimum desktop)
  - [x] Subtask 6.2: Test at 1440px breakpoint (large desktop)
  - [x] Subtask 6.3: Test at 1920px breakpoint (ultra-wide)
  - [x] 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:**
```yaml
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`