sepehr/Keep
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Keep/_bmad-output/implementation-artifacts/13-1-refactor-notebook-main-page-layout.md
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

304 lines
10 KiB
Markdown
Raw Blame History

# 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`
Reference in New Issue View Git Blame Copy Permalink