@leanspec/ui 0.2.7-dev.20251126090633 → 0.2.7

package/.next/standalone/packages/ui/dist/standalone/specs/081-web-app-ux-redesign/README.md

@@ -0,0 +1,825 @@
+---
+status: complete
+created: '2025-11-14'
+tags:
+  - web
+  - ux
+  - design
+  - enhancement
+priority: high
+created_at: '2025-11-14T03:21:43.076Z'
+depends_on:
+  - 068
+  - 082-web-realtime-sync-architecture
+related:
+  - 052-branding-assets
+  - 068-live-specs-ux-enhancements
+  - 094-ai-chatbot-web-integration
+updated_at: '2025-11-17T06:32:59.774Z'
+transitions:
+  - status: in-progress
+    at: '2025-11-14T04:08:03.555Z'
+  - status: complete
+    at: '2025-11-17T01:14:24.924Z'
+completed_at: '2025-11-17T01:14:24.924Z'
+completed: '2025-11-17'
+---
+
+# Web App UX/UI Comprehensive Redesign
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-14 · **Tags**: web, ux, design, enhancement
+
+**Project**: lean-spec  
+**Team**: Core Development  
+**Dependencies**: Spec 068 (live-specs-ux-enhancements), **Spec 082 (web-realtime-sync-architecture) - CRITICAL BLOCKER**  
+**Related**: Spec 052 (branding-assets)
+
+## Overview
+
+Comprehensive UX/UI redesign for the LeanSpec Web application (`@leanspec/web`) addressing critical layout, navigation, branding, and usability issues. This spec consolidates feedback from initial user testing and aims to create a professional, intuitive interface that aligns with LeanSpec's core principles.
+
+**⚠️ CRITICAL BLOCKER IDENTIFIED**: This spec is **blocked** by spec 082 (web-realtime-sync-architecture). The current database-seeding architecture has a fundamental flaw - no realtime updates from filesystem. Spec 082 proposes removing the database entirely and using direct filesystem reads with smart caching. **This must be resolved before continuing with UX redesign** to avoid building on unstable foundations.
+
+**Why now?**
+- Current implementation (spec 068) completed foundational features but has UX issues
+- User testing revealed navigation confusion and layout inefficiencies
+- Missing branding integration (logo/favicon from spec 052)
+- Need to align UI with LeanSpec first principles (Context Economy, Signal-to-Noise)
+- Critical for broader adoption and professional appearance
+
+**What's the problem?**
+1. **Layout inefficiency**: Top navbar wastes horizontal space, metadata sidebar redundant with header
+2. **Navigation confusion**: Breadcrumbs in wrong location, sub-specs as tabs instead of tree structure
+3. **Missing branding**: No logo/favicon integration despite spec 052 completion
+4. **Content constraints**: Artificial max-width limits readability on wide screens
+5. **UX inconsistencies**: Board and List pages feel disconnected, sorting/filtering incomplete
+
+**What's the solution?**
+Complete redesign with:
+- **Three-section navigation**: Home (dashboard) / Specs (unified list+board) / Stats
+- **GitHub link** moved to top navbar as icon (declutters sidebar)
+- **Compact top navbar** with logo, breadcrumbs, search, theme toggle, and GitHub link
+- **Main sidebar** for primary navigation (3 items: Home, Specs, Stats)
+- **Specs nav sidebar** on detail pages only (specs tree with sub-specs)
+- **Full-width content** without artificial constraints
+- **Integrated metadata** in spec header (no separate sidebar)
+- **Vertical timeline** design with better visual hierarchy
+
+## Design
+
+### 1. Branding Integration
+
+**Current State**: No logo or favicon, uses placeholder text only
+
+**Changes Required:**
+- Import logo assets from spec 052 (`specs/052-branding-assets/`)
+- Use `logo-with-bg.svg` (theme-safe) for navbar light mode
+- Use `logo-dark-bg.svg` (cyan on dark) for navbar dark mode
+- Add favicon files: `favicon.ico`, `icon.svg`, `apple-touch-icon.png`
+- Update `src/app/layout.tsx` metadata for icons
+- Ensure logo scales properly at navbar size (32px height)
+
+**Technical Approach:**
+```tsx
+// packages/web/src/components/navigation.tsx
+<Link href="/" className="flex items-center space-x-2">
+  <img 
+    src="/logo-with-bg.svg" 
+    alt="LeanSpec" 
+    className="h-8 w-8 dark:hidden" 
+  />
+  <img 
+    src="/logo-dark-bg.svg" 
+    alt="LeanSpec" 
+    className="h-8 w-8 hidden dark:block" 
+  />
+  <span className="font-bold text-xl">LeanSpec</span>
+</Link>
+```
+
+**Files:**
+- Copy from: `docs-site/static/img/logo-*.svg` and `docs-site/static/*.{ico,png}`
+- Copy to: `packages/web/public/`
+
+### 2. Global Layout Restructure
+
+**Current State**: Top navbar with horizontal menu, no global sidebar
+
+**New Layout Architecture:**
+
+**Global Pages (Home, Specs, Stats):**
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Top Navbar (sticky, h-14)                                  │
+│ [Logo] [Breadcrumb...] [Search] [Theme] [GitHub Icon]      │
+├──────────┬──────────────────────────────────────────────────┤
+│          │                                                  │
+│ Main     │ Main Content Area                                │
+│ Sidebar  │ (full width, no max constraints)                 │
+│ (sticky) │                                                  │
+│          │                                                  │
+│ • Home   │ Home: Dashboard with project overview,           │
+│ • Specs  │       recent activity, key metrics               │
+│ • Stats  │                                                  │
+│          │ Specs: Unified list/board view with switcher     │
+│          │                                                  │
+│          │ Stats: Project analytics and insights            │
+│          │                                                  │
+│          │                                                  │
+└──────────┴──────────────────────────────────────────────────┘
+```
+
+**Spec Detail Page (Two Sidebars):**
+```
+┌──────────────────────────────────────────────────────────────┐
+│ Top Navbar (sticky, h-14)                                   │
+│ [Logo] [Breadcrumb...] [Search] [Theme] [GitHub Icon]       │
+├──────────┬──────────┬────────────────────────────────────────┤
+│          │          │                                        │
+│ Main     │ Specs    │ Main Content Area                      │
+│ Sidebar  │ Nav      │ (full width, no max constraints)       │
+│ (sticky) │ Sidebar  │                                        │
+│          │ (sticky) │                                        │
+│ • Home   │ ▼ 080-x  │                                        │
+│ • Specs  │   • Over │                                        │
+│ • Stats  │   • IMPL │                                        │
+│          │ ▼ 079-y  │                                        │
+│          │   • Over │                                        │
+│          │ ...      │                                        │
+│          │          │                                        │
+└──────────┴──────────┴────────────────────────────────────────┘
+```
+
+**Implementation Details:**
+
+**Top Navbar Changes:**
+- Remove horizontal nav items (moved to sidebar)
+- Add GitHub icon link at right edge (between theme toggle and nothing)
+- Move breadcrumb from spec detail page to navbar (always visible)
+- Keep search and theme toggle at right edge
+- Logo on left, breadcrumb next to it
+- Layout: `[Logo] [Breadcrumb] ... [Search] [Theme] [GitHub Icon]`
+- Height: 56px (h-14)
+
+**Main Sidebar (New - Always Visible):**
+- Width: 240px, collapsible to 60px
+- Sticky positioning (top: 56px, height: calc(100vh - 56px))
+- Contains ONLY 3 primary sections:
+  1. **Home** (/) - Dashboard with overview, recent activity, key metrics
+  2. **Specs** (/specs) - Unified list/board view with layout switcher
+  3. **Stats** (/stats) - Project analytics and insights
+- Current page highlighted
+- Simple, clean, focused navigation
+- GitHub moved to top navbar (no longer in sidebar)
+
+**Specs Nav Sidebar (New - Spec Detail Page Only):**
+- Width: 280px, collapsible
+- Sticky positioning (top: 56px, height: calc(100vh - 56px))
+- Positioned to the right of Main Sidebar
+- Contains:
+  1. **All Specs Tree** (with expand/collapse)
+  2. **Sub-specs** (indented under parent)
+- Specs sorted by ID descending (newest first)
+- Current spec and sub-spec highlighted
+- Only visible on spec detail pages
+
+**Component Structure:**
+```tsx
+// New: src/components/main-sidebar.tsx
+export function MainSidebar({ currentPath }: Props) {
+  return (
+    <aside className="sticky top-14 h-[calc(100vh-3.5rem)] w-[240px] border-r">
+      {/* Main Navigation - 3 Primary Sections */}
+      <nav className="p-4 space-y-1">
+        <SidebarLink href="/" icon={Home}>
+          Home
+          <span className="text-xs text-muted-foreground">Dashboard</span>
+        </SidebarLink>
+        <SidebarLink href="/specs" icon={FileText}>
+          Specs
+          <span className="text-xs text-muted-foreground">All Specifications</span>
+        </SidebarLink>
+        <SidebarLink href="/stats" icon={BarChart3}>
+          Stats
+          <span className="text-xs text-muted-foreground">Analytics</span>
+        </SidebarLink>
+      </nav>
+    </aside>
+  );
+}
+
+// Updated: src/components/navbar.tsx (add GitHub icon)
+export function Navbar({ breadcrumb }: Props) {
+  return (
+    <header className="sticky top-0 z-50 h-14 border-b bg-background">
+      <div className="flex items-center justify-between h-full px-4">
+        {/* Left: Logo + Breadcrumb */}
+        <div className="flex items-center gap-4">
+          <Logo />
+          <Breadcrumb items={breadcrumb} />
+        </div>
+        
+        {/* Right: Search + Theme + GitHub */}
+        <div className="flex items-center gap-2">
+          <SearchButton />
+          <ThemeToggle />
+          <Button variant="ghost" size="icon" asChild>
+            <a href="https://github.com/codervisor/lean-spec" target="_blank">
+              <Github className="h-5 w-5" />
+            </a>
+          </Button>
+        </div>
+      </div>
+    </header>
+  );
+}
+
+// New: src/components/specs-nav-sidebar.tsx
+export function SpecsNavSidebar({ specs, currentPath, currentSpec }: Props) {
+  return (
+    <aside className="sticky top-14 h-[calc(100vh-3.5rem)] w-[280px] border-r">
+      {/* Specs Tree with Sub-specs */}
+      <div className="p-4">
+        <h3 className="text-sm font-semibold mb-2">Specifications</h3>
+        <SpecsTree 
+          specs={specs} 
+          currentPath={currentPath}
+          currentSpec={currentSpec}
+        />
+      </div>
+    </aside>
+  );
+}
+```
+
+### 3. Home Page Dashboard Redesign
+
+**Current State**: Home page (`/`) = Spec List with filters and sorting
+
+**New Purpose**: Comprehensive operational dashboard for daily work
+
+**Dashboard Layout:**
+
+```
+┌────────────────────────────────────────────────────────┐
+│ Home Dashboard                                         │
+├────────────────────────────────────────────────────────┤
+│                                                        │
+│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────┐ │
+│ │ In Progress (5) │ │ Recently Added │ │ Stats    │ │
+│ │                 │ │                 │ │          │ │
+│ │ • 081 Web UX    │ │ • 081 Web UX    │ │ 82 Total │ │
+│ │ • 080 MCP Mod   │ │ • 080 MCP Mod   │ │ 5 Active │ │
+│ │ • ...           │ │ • ...           │ │ 68 Done  │ │
+│ └─────────────────┘ └─────────────────┘ └──────────┘ │
+│                                                        │
+│ ┌──────────────────────────────────────────────────┐  │
+│ │ Activity Timeline                                │  │
+│ │                                                  │  │
+│ │ • 081 marked in-progress (2 hours ago)           │  │
+│ │ • 080 created (yesterday)                        │  │
+│ │ • 079 completed (2 days ago)                     │  │
+│ └──────────────────────────────────────────────────┘  │
+│                                                        │
+│ ┌──────────────────────────────────────────────────┐  │
+│ │ Quick Actions                                    │  │
+│ │ [+ Create Spec] [View All Specs] [Board View]    │  │
+│ └──────────────────────────────────────────────────┘  │
+└────────────────────────────────────────────────────────┘
+```
+
+**Dashboard Components:**
+
+1. **Status Overview Cards** (top row, 3-4 cards)
+   - In Progress count + list
+   - Planned count + list
+   - Recently Added (last 5)
+   - Quick stats (total, active, completed)
+
+2. **Activity Timeline** (middle)
+   - Recent status changes
+   - Spec creations
+   - Completions
+   - Time-based (last 7 days)
+
+3. **Quick Actions** (bottom)
+   - Create new spec button
+   - View all specs (→ /specs)
+   - Board view (→ /specs?view=board)
+
+**Purpose**: Give users immediate context on project health and recent activity without needing to navigate to other pages.
+
+### 4. Specs Page (Unified List/Board)
+
+**Current State**: 
+- `/` = Spec List (cards with filters)
+- `/board` = Board view (kanban columns)
+
+**New Structure**:
+- Route: `/specs` (primary specs page)
+- Layout switcher: List view (default) or Board view
+- URL param: `?view=list` or `?view=board`
+
+**This is the full spec collection page** - replaces both old Home and Board pages.
+
+### 5. Spec Detail Page Redesign
+
+**Current Issues:**
+- Metadata sidebar duplicates info from header
+- Content has max-width constraint (artificially narrow on wide screens)
+- Timeline is horizontal (poor use of space)
+- Title area and info box separated
+- "Back to Specs" button redundant (sidebar navigation exists)
+
+**New Design (Two Sidebars):**
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ Top Navbar with Breadcrumb                               │
+├──────────┬──────────┬────────────────────────────────────────┤
+│ Main     │ Specs    │ Spec Header (sticky, compact)      │
+│ Sidebar  │ Nav      │ ┌────────────────────────────────┐ │
+│          │ Sidebar  │ │ #080 Title                     │ │
+│ • Home   │          │ │ [Status] [Priority] [Tags...]  │ │
+│ • Specs  │ ▼ 080-x  │ │ Created: X | Updated: Y        │ │
+│ • Stats  │   • Over │ └────────────────────────────────┘ │
+│          │   • IMPL │                                    │
+│          │   • TEST │ Content (full-width, no max)       │
+│          │ ▼ 079-y  │ ┌────────────────────────────────┐ │
+│          │   • Over │ │                                │ │
+│          │ ...      │ │  Markdown content with         │ │
+│          │          │ │  timeline embedded             │ │
+│          │          │ │                                │ │
+│          │          │ │  ◉ Created (date)              │ │
+│          │          │ │  │                              │ │
+│          │          │ │  ◉ In Progress (date)          │ │
+│          │          │ │  │                              │ │
+│          │          │ │  ○ Complete                     │ │
+│          │          │ │                                │ │
+│          │          │ └────────────────────────────────┘ │
+└──────────┴──────────┴────────────────────────────────────────┘
+```
+
+**Key Changes:**
+
+**Spec Header (Compact):**
+- Line 1: Spec number + Title
+- Line 2: Status badge, Priority badge, Tags, Actions dropdown
+- Line 3: Small metadata row: `Created: X · Updated: Y · Name: spec-name`
+- Remove separate info box sidebar completely
+- Sticky position: below navbar
+
+**Content Layout:**
+- Remove `max-w-6xl` constraint - use full available width
+- Remove left sidebar (metadata) entirely
+- Single column layout for content
+- Timeline embedded in markdown at appropriate section (not sidebar)
+
+**Sub-Spec Navigation:**
+- Move from horizontal tabs to left sidebar tree
+- Indent sub-specs under parent spec
+- Icons for sub-spec types (DESIGN.md, IMPLEMENTATION.md, etc.)
+- Active sub-spec highlighted
+- "Overview" = `README.md` (merge, don't duplicate)
+
+**Example Sidebar Tree:**
+```
+▼ 080 MCP Server Modular Architecture
+  • Overview (README.md) ← selected
+  • Design
+  • Implementation
+  • Testing
+▼ 079 CLI Alphabetical Organization
+  • Overview
+```
+
+### 4. Timeline Redesign (Vertical)
+
+**Current**: Horizontal timeline with circles and lines
+
+**New**: Vertical timeline with better visual hierarchy
+
+```tsx
+<div className="space-y-4 border-l-2 border-muted pl-4 py-2">
+  <TimelineEvent 
+    icon={<CheckCircle />} 
+    title="Created" 
+    date="2025-11-01"
+    active
+  />
+  <TimelineEvent 
+    icon={<PlayCircle />} 
+    title="In Progress" 
+    date="2025-11-05"
+    active
+  />
+  <TimelineEvent 
+    icon={<Circle />} 
+    title="Complete" 
+    date={null}
+    active={false}
+  />
+</div>
+```
+
+**Visual Design:**
+- Left border line connecting all events
+- Icon + title + date for each event
+- Active events: solid icon, bold text
+- Future events: outline icon, muted text
+- Compact spacing, embedded in content flow
+
+### 6. Specs Page - List View Improvements
+
+**Current Issues:**
+- No sorting controls (only filters)
+- Specs not sorted by ID descending
+- Cards are visually heavy
+
+**Changes:**
+
+**Sorting Controls:**
+```tsx
+<Select value={sortBy} onValueChange={setSortBy}>
+  <SelectItem value="id-desc">Newest First (ID ↓)</SelectItem>
+  <SelectItem value="id-asc">Oldest First (ID ↑)</SelectItem>
+  <SelectItem value="updated-desc">Recently Updated</SelectItem>
+  <SelectItem value="title-asc">Title (A-Z)</SelectItem>
+</Select>
+```
+
+**Default Sort**: ID descending (newest specs at top)
+
+**Table View Option:**
+- Add toggle: List view (cards) vs Table view (compact)
+- Table columns: ID, Title, Status, Priority, Tags, Updated
+- Clickable rows navigate to spec detail
+
+### 7. Board and List Layout Switcher
+
+**Integration**: List and Board are now unified on `/specs` page
+
+**Layout Switcher:**
+```tsx
+// Add to /specs page
+<div className="flex items-center gap-2 mb-4">
+  <span className="text-sm text-muted-foreground">View:</span>
+  <ToggleGroup type="single" value={layout} onValueChange={setLayout}>
+    <ToggleGroupItem value="list" aria-label="List view">
+      <List className="h-4 w-4" />
+      <span className="ml-2">List</span>
+    </ToggleGroupItem>
+    <ToggleGroupItem value="board" aria-label="Board view">
+      <LayoutGrid className="h-4 w-4" />
+      <span className="ml-2">Board</span>
+    </ToggleGroupItem>
+  </ToggleGroup>
+</div>
+```
+
+**Implementation:**
+- Single route: `/specs`
+- URL param: `?view=list` (default) or `?view=board`
+- Switcher persists choice in localStorage
+- Board view = kanban columns by status
+- List view = cards/table sorted/filtered
+- Same spec card component, different container layouts
+
+**Navigation:**
+- `/` = Home dashboard (new)
+- `/specs` = Specs with list/board switcher
+- `/specs/[id]` = Spec detail page
+- Breadcrumb: Home → Specs (List View) or Home → Specs (Board View)
+- Consistent behavior: click spec → detail page
+- Back button/sidebar returns to same view mode
+
+### 8. Display `title` vs `name`
+
+**Current Implementation**: 
+- `title` field in frontmatter (optional, can be null)
+- `name` field = spec folder name (always present)
+- H1 heading = first `# Heading` in markdown (always present per validation)
+
+**Clarification Needed**:
+- Which field is the "title"? The frontmatter `title` or the H1 heading?
+- Current code: `const displayTitle = spec.title || spec.specName`
+- This suggests frontmatter `title` is primary, fallback to `name`
+
+**Recommended Approach**:
+1. **H1 heading is the canonical title** (always present, validated)
+2. **Frontmatter `title`** can be different (for metadata/SEO)
+3. **Display logic**:
+   - **Primary heading**: Use H1 from markdown content
+   - **Metadata**: Show `name` (folder name) in small text
+   - **Card/List**: Use H1 title (parse from content)
+4. **Fallback**: If H1 parsing fails → use frontmatter `title` → use `name`
+
+**Why H1 over frontmatter title?**
+- H1 is required by validation (spec 018)
+- H1 is what users see in markdown
+- H1 is the "true" document title
+- Frontmatter `title` can be stale/inconsistent
+
+### 9. Sub-Spec Icons
+
+**Generic Icons** (default for unknown types):
+- 📄 Generic document icon (lucide-react `FileText`)
+
+**Pre-defined Icon Mappings:**
+```tsx
+const SUB_SPEC_ICONS: Record<string, { icon: LucideIcon, color: string }> = {
+  'README.md': { icon: FileText, color: 'text-blue-600' },
+  'DESIGN.md': { icon: Palette, color: 'text-purple-600' },
+  'IMPLEMENTATION.md': { icon: Code, color: 'text-green-600' },
+  'TESTING.md': { icon: TestTube, color: 'text-orange-600' },
+  'PLAN.md': { icon: CheckSquare, color: 'text-cyan-600' },
+  'TECHNICAL.md': { icon: Wrench, color: 'text-gray-600' },
+  'ROADMAP.md': { icon: Map, color: 'text-indigo-600' },
+  'MIGRATION.md': { icon: GitBranch, color: 'text-yellow-600' },
+  'DOCUMENTATION.md': { icon: BookOpen, color: 'text-pink-600' },
+  // ... extend as needed
+};
+```
+
+**Usage in Sidebar:**
+```tsx
+<SpecTreeItem icon={Palette} color="text-purple-600">
+  Design
+</SpecTreeItem>
+```
+
+## Plan
+
+### Phase 1: Branding & Layout Foundation (Week 1)
+
+**Day 1-2: Branding Integration**
+- [x] Copy logo assets from spec 052 to `packages/web/public/`
+- [x] Update favicon references in `layout.tsx`
+- [x] Implement theme-aware logo switching in navbar
+- [x] Test logo rendering in light/dark modes
+
+**Day 3-5: Sidebar Implementation**
+- [x] Create `MainSidebar` component (3 items: Home/Specs/Stats)
+- [x] Create `SpecsNavSidebar` component (specs tree with sub-specs)
+- [x] Build collapsible specs tree with expand/collapse
+- [x] Add search/filter within specs nav sidebar
+- [x] Integrate both sidebars into layouts (main sidebar always, specs nav on detail pages only)
+- [x] Test two-sidebar layout on spec detail pages
+
+**Day 6-7: Top Navbar Redesign**
+- [x] Remove horizontal nav items from navbar
+- [x] Move breadcrumb to navbar (next to logo)
+- [x] Add GitHub icon link at right edge of navbar
+- [x] Reposition: Logo → Breadcrumb ... Search → Theme → GitHub
+- [x] Test responsive behavior (mobile collapse)
+
+### Phase 2: Home Dashboard & Spec Detail (Week 2)
+
+**Day 8-9: Home Dashboard Implementation**
+- [x] Design dashboard layout (status cards + activity timeline + quick actions)
+- [x] Implement status overview cards (In Progress, Planned, Recently Added, Stats)
+- [x] Build activity timeline component (recent status changes, creations, completions)
+- [x] Add quick actions section (Create Spec, View All Specs, Board View)
+- [x] Test dashboard with real data
+- [x] Ensure dashboard loads quickly (<1s)
+
+**Day 10-11: Compact Spec Header**
+- [x] Redesign spec header with integrated metadata
+- [x] Remove "Back to Specs" button
+- [x] Add small metadata row (created, updated, name)
+- [x] Make header sticky with proper z-index
+- [x] Display `title` prominently, `name` as metadata
+
+**Day 10-11: Content Layout**
+- [x] Remove max-width constraint on content
+- [x] Remove left metadata sidebar entirely
+- [x] Implement full-width single-column layout
+- [x] Ensure proper responsive behavior
+
+**Day 12-13: Sub-Spec Integration**
+- [x] Move sub-specs from tabs to specs nav sidebar tree
+- [x] Implement sub-spec icon mapping system
+- [x] Add expand/collapse for specs with sub-specs
+- [x] Merge "Overview" and "README.md" (no duplication)
+- [x] Fix sub-spec navigation routing
+- [x] Ensure specs nav sidebar only appears on spec detail pages
+
+**Day 14: Timeline Redesign**
+- [x] Implement vertical timeline component
+- [x] Embed timeline in content area (not sidebar)
+- [x] Add proper icons and visual states
+- [x] Test with different status transitions
+
+### Phase 3: Specs Page Unification (Week 3)
+
+**Day 15-16: Specs Page Route Changes**
+- [x] Move spec list from `/` to `/specs`
+- [x] Implement routing: `/` = dashboard, `/specs` = specs page
+- [x] Update all internal links to point to `/specs`
+- [x] Add sorting controls (ID desc, ID asc, updated, title)
+- [x] Set default sort to ID descending
+- [ ] Implement table view option (toggle with card view)
+
+**Day 17-18: Board/List Layout Switcher**
+- [x] Add layout switcher component (List/Board toggle) to `/specs`
+- [x] Implement URL param handling (?view=list|board)
+- [x] Add localStorage persistence for layout preference
+- [x] Share spec card component between layouts
+- [x] Update breadcrumbs: Home → Specs (List/Board View)
+- [x] Remove old `/board` route (redirect to `/specs?view=board`)
+- [x] Test navigation flow consistency
+
+**Day 19-21: Polish & Testing**
+- [x] Fix any navigation routing issues
+- [x] Ensure all links work correctly
+- [ ] Test responsive behavior on mobile/tablet
+- [ ] Accessibility audit (keyboard navigation, ARIA labels)
+- [ ] Performance testing (ensure no regressions)
+
+### Phase 4: Documentation & Deployment
+
+**Day 22-23: Documentation**
+- [ ] Update component documentation
+- [ ] Document new navigation patterns
+- [ ] Create migration notes for any breaking changes
+- [ ] Update README with new screenshots
+
+**Day 24-25: QA & Deployment**
+- [ ] Full regression testing (all pages)
+- [ ] Cross-browser testing (Chrome, Firefox, Safari)
+- [ ] Mobile testing (iOS Safari, Android Chrome)
+- [ ] Deploy to staging
+- [ ] User acceptance testing
+- [ ] Deploy to production
+
+## Test
+
+### Functional Testing
+
+**Branding:**
+- [x] Logo displays correctly in navbar (light mode)
+- [x] Logo switches to dark variant in dark mode
+- [x] Favicon appears in browser tabs
+- [x] All icon sizes render correctly
+
+**Layout:**
+- [x] Main sidebar appears on all pages with 3 items (Home, Specs, Stats)
+- [x] Specs nav sidebar appears only on spec detail pages
+- [x] Both sidebars are sticky and don't scroll with content
+- [x] Both sidebars collapsible function works
+- [x] Top navbar has GitHub icon at right edge
+- [x] Top navbar breadcrumb updates correctly on navigation
+- [x] Search and theme toggle positioned correctly
+- [x] Two-sidebar layout doesn't feel cramped on spec detail pages
+
+**Spec Detail:**
+- [x] Spec header shows all metadata in compact format
+- [x] Title displays correctly (`title` field, not `name`)
+- [x] Name field shown in metadata row
+- [x] Content uses full width (no artificial constraints)
+- [x] Timeline renders vertically with correct states
+- [x] Sub-specs appear in sidebar tree (not tabs)
+- [x] Sub-spec navigation works (no 404 errors)
+- [x] Overview and README.md merged (no duplication)
+
+**Home Dashboard:**
+- [x] Dashboard loads quickly (<1s)
+- [x] Status overview cards display correct counts
+- [x] In Progress and Planned lists show relevant specs
+- [x] Recently Added shows last 5 specs
+- [x] Activity timeline shows recent changes
+- [x] Quick actions navigate correctly
+- [x] Dashboard responsive on all screen sizes
+
+**Specs Page:**
+- [x] Route `/specs` works correctly
+- [x] Specs sorted by ID descending by default
+- [x] Sort controls change order correctly
+- [ ] Table view displays properly
+- [x] Filters work in conjunction with sorting
+
+**Board/List Switcher:**
+- [x] Layout switcher appears on `/specs` page
+- [x] Switching between List and Board views works
+- [x] Layout preference persists via localStorage
+- [x] URL param reflects current view (?view=list|board)
+- [x] Card click navigates to spec detail from both views
+- [x] Breadcrumb shows: Home → Specs (List View) or (Board View)
+- [x] Navigation back to `/specs` returns to same view mode
+- [x] Old `/board` route redirects to `/specs?view=board`
+
+### Visual Testing
+
+- [ ] Layout consistent across pages
+- [ ] Spacing and alignment proper
+- [ ] Icons render with correct colors
+- [ ] Hover states work on all interactive elements
+- [ ] Dark mode styling consistent
+
+### Responsive Testing
+
+- [ ] Mobile: Sidebar collapses to hamburger menu
+- [ ] Tablet: Layout adapts appropriately
+- [ ] Desktop: Full layout displays correctly
+- [ ] Ultra-wide: Content scales properly
+
+### Performance Testing
+
+- [ ] Page load time <2s
+- [ ] No layout shift during hydration
+- [ ] Smooth animations (60fps)
+- [ ] Lighthouse score >90
+
+### Accessibility Testing
+
+- [ ] Keyboard navigation works for all interactive elements
+- [ ] Focus indicators visible
+- [ ] Screen reader announces navigation changes
+- [ ] ARIA labels present where needed
+- [ ] Color contrast meets WCAG AA
+
+## Notes
+
+### Design Decisions
+
+**Why three-section navigation (Home/Specs/Stats)?**
+- **Clear purpose**: Each section has a distinct role
+  - Home = Daily operational dashboard
+  - Specs = Full spec collection (list/board)
+  - Stats = Project analytics
+- **Avoids redundancy**: Old design had Home (list) and Board (also list), confusing
+- **GitHub in navbar**: External link, doesn't need sidebar prominence
+
+**Why move GitHub to navbar?**
+- **External link**: Doesn't belong in primary navigation
+- **Less prominent**: Not a primary workflow destination
+- **Space efficiency**: Navbar has room, sidebar is cleaner with 3 items
+- **Standard pattern**: Many apps put external links in top-right (GitHub, Twitter, etc.)
+
+**Why two sidebars on spec detail pages?**
+- **Separation of concerns**: Main nav (Home/Specs/Stats) vs Specs navigation
+- **Context preservation**: Main sidebar always visible for quick navigation
+- **Spec focus**: Specs nav sidebar only when needed (detail page)
+- **Scalability**: Specs tree sidebar scales better as spec count grows (80+ specs)
+- **Standard pattern**: Matches tools like VS Code (activity bar + file explorer)
+
+**Why remove metadata sidebar on spec detail?**
+- **Signal-to-Noise**: Metadata in sidebar duplicates info from header (violates principle)
+- **Context Economy**: Reduces cognitive load by integrating metadata into header
+- **Space efficiency**: Frees up horizontal space for content (more important)
+
+**Why vertical timeline?**
+- **Visual hierarchy**: Vertical flow matches natural reading pattern
+- **Space efficiency**: Uses vertical space better (screens are wider than tall)
+- **Scalability**: Easier to add more events as specs evolve
+
+**Why merge Overview and README.md?**
+- **No duplication**: They contain the same content (violates Signal-to-Noise)
+- **Simplicity**: Reduces cognitive load (fewer tabs to understand)
+- **Clarity**: "Overview" is more intuitive than "README.md" for users
+
+### Technical Considerations
+
+**Sidebar State Persistence:**
+- Use `localStorage` to remember collapse state
+- Remember expanded specs in tree
+- Sync state across tabs (optional, via localStorage events)
+
+**Routing:**
+- Sub-spec routes: `/specs/[id]?subspec=DESIGN.md`
+- Preserve query params when navigating
+- Update breadcrumb based on current sub-spec
+
+**Performance:**
+- Virtualize specs tree if count exceeds 100
+- Lazy load sub-spec content on demand
+- Memoize expensive tree rendering
+
+**Mobile Strategy:**
+- Sidebar becomes slide-out drawer (overlay)
+- Hamburger menu in navbar triggers drawer
+- Breadcrumb remains visible on mobile
+
+### Open Questions
+
+- [ ] Should sidebars be resizable (drag to adjust width)?
+- [ ] Do we need keyboard shortcuts for navigation (j/k for next/prev spec)?
+- [ ] Should we add "recently viewed" section in specs nav sidebar or Home dashboard?
+- [ ] Do we need a "favorites" system for frequently accessed specs?
+- [ ] **Title field**: Should we use H1 heading (always present) or frontmatter `title` (can be null)? Recommend H1 as canonical source.
+- [ ] **Home dashboard**: What other widgets would be useful? (Blocked specs, overdue specs, contributor activity, etc.)
+- [ ] **Home dashboard**: Should it be customizable (user can add/remove/rearrange widgets)?
+
+### Related Work
+
+- **Spec 052**: Provides branding assets (logo, favicon)
+- **Spec 068**: Completed initial UX implementation (foundation for this redesign)
+
+### Future Enhancements (Post v1)
+
+- Collaborative features (real-time presence indicators in sidebar)
+- Spec bookmarks/favorites
+- Drag-and-drop spec reordering
+- Customizable sidebar sections
+- Keyboard shortcuts panel (Cmd+K → show shortcuts)
+- Multi-column layout option for ultra-wide screens