@leanspec/ui 0.2.7-dev.20251128020042 → 0.2.8

package/.next/standalone/packages/ui/dist/standalone/specs/068-live-specs-ux-enhancements/README.md

@@ -0,0 +1,357 @@
+---
+status: complete
+created: '2025-11-12'
+tags:
+  - web
+  - ux
+  - enhancement
+  - v0.3.0-launch
+priority: high
+created_at: '2025-11-12T21:49:12.069Z'
+depends_on:
+  - '035'
+related:
+  - 035-live-specs-showcase
+updated_at: '2025-11-13T08:55:52.705Z'
+transitions:
+  - status: in-progress
+    at: '2025-11-13T08:55:35.931Z'
+  - status: complete
+    at: '2025-11-13T08:55:52.705Z'
+completed_at: '2025-11-13T08:55:52.705Z'
+completed: '2025-11-13'
+---
+
+# LeanSpec Web: UX/UI Enhancements Phase 2
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-12 · **Tags**: web, ux, enhancement, v0.3.0-launch
+
+**Project**: lean-spec  
+**Team**: Core Development  
+**Related**: Spec 035 (live-specs-showcase)
+
+## Overview
+
+This spec captures the remaining UX/UI enhancements and missing features for the LeanSpec Web platform that were identified during Phase 1 development (spec 035) but deferred as out-of-scope for the MVP. These enhancements will significantly improve the user experience and complete the professional polish of the application.
+
+**Dependency**: This spec **depends on** spec 035 Phase 1 MVP completion (~80% done). Work cannot start until foundational UI/UX is stable.
+
+**Why now?**
+- Phase 1 MVP (spec 035) is nearly complete with critical fixes applied
+- Users need these features for a complete, professional experience
+- Several items are blockers for broader adoption (quick search, proper navigation)
+- Must be completed before official v0.3.0 launch
+- Can run in parallel with spec 035 Phase 2 (GitHub integration)
+
+**What's included?**
+- Stats page completion
+- Spec detail page redesign (sidebar, sticky elements, better metadata display)
+- Sub-spec navigation improvements
+- Quick search functionality (Cmd+K)
+- Loading states and skeletons
+- Enhanced empty states
+- Toast notifications
+- Logo and favicon
+- Accessibility improvements
+
+## Design
+
+See **[DESIGN.md](./DESIGN.md)** for comprehensive UI/UX design system specifications, component patterns, and implementation details.
+
+### 1. Stats Page Completion
+
+**Current State**: Basic stats cards exist but many sections are incomplete or missing.
+
+**Required Enhancements:**
+- Full statistics dashboard with all metrics from API
+- Trend charts/sparklines showing progress over time
+- Filtering by date range, status, priority
+- Export functionality (CSV, PDF)
+- Responsive grid layout with proper empty states
+- Interactive tooltips on hover
+
+**Technical Approach:**
+- Use recharts or similar charting library for visualizations
+- Implement date range picker component
+- Add CSV/PDF export utilities
+- Ensure mobile responsiveness
+
+### 2. Spec Detail Page Redesign
+
+**Current Issues:**
+- No sidebar for quick navigation between specs
+- Metadata area is not sticky
+- Header doesn't stick on scroll
+- Frontmatter display is poorly formatted
+
+**Required Changes:**
+
+**a) Sidebar Navigation**
+- Left sidebar (collapsible) showing list of all specs
+- Quick navigation to any spec without going back to list
+- Search/filter within sidebar
+- Current spec highlighted
+- Sticky positioning
+
+**b) Sticky Left Info Panel**
+- Metadata area (timeline, status, priority, tags) should stick on scroll
+- Keep important info visible as user reads long spec
+- Right side content scrolls normally
+
+**c) Sticky Header**
+- Spec title and key actions stay visible on scroll
+- Breadcrumb navigation sticky
+- Theme toggle always accessible
+
+**d) Improved Frontmatter Display**
+- Better visual hierarchy for metadata
+- Icons for each field (already implemented for some)
+- Cleaner layout using cards/sections
+- Better spacing and typography
+
+### 3. Sub-Spec Navigation Improvements
+
+**Current Issues:**
+- Tab design doesn't clearly indicate sub-spec structure
+- No clear visual hierarchy
+- Confusing to understand relationship between main spec and sub-specs
+
+**Required Changes:**
+- Redesign tab navigation to show clear hierarchy
+- Add visual indicators for sub-spec types (icons, colors)
+- Show overview tab that lists all sub-specs with descriptions
+- Breadcrumb showing current sub-spec location
+- Side navigation option as alternative to tabs
+- Better mobile experience for sub-spec switching
+
+### 4. Quick Search Modal (Cmd+K)
+
+**Feature**: Global keyboard-triggered search
+
+**Requirements:**
+- Keyboard shortcut: `Cmd+K` (Mac) / `Ctrl+K` (Windows/Linux)
+- Fuzzy search across all specs (title, content, tags)
+- Recent searches stored locally
+- Navigate results with arrow keys
+- Preview snippet in results
+- Filter by status, priority, tags
+- Responsive design
+
+**Technical Approach:**
+- Use Radix UI Dialog component
+- Implement fuzzy search with fuse.js or similar
+- Store recent searches in localStorage
+- Debounce search input for performance
+- Server-side search endpoint for full-text search
+
+### 5. Loading States & Skeletons
+
+**Current State**: No loading indicators for async content
+
+**Required:**
+- Skeleton loaders for all pages during data fetch
+- Suspense boundaries at route level
+- Loading spinners for actions (create, update, delete)
+- Skeleton components for:
+  - Spec list/table
+  - Spec detail page
+  - Stats cards
+  - Kanban board
+- Smooth transitions between loading and loaded states
+
+**Technical Approach:**
+- Create reusable skeleton components
+- Use React Suspense with Server Components
+- Add loading.tsx files for Next.js route segments
+- Implement progressive loading for large lists
+
+### 6. Enhanced Empty States
+
+**Current State**: Basic empty messages
+
+**Required:**
+- More helpful messaging with context
+- Actionable next steps (CTAs)
+- Icons/illustrations for visual interest
+- Different empty states for:
+  - No specs yet (with "Create first spec" CTA)
+  - No results found (with "Clear filters" CTA)
+  - No archived specs (with helpful message)
+  - Empty kanban columns (with status explanation)
+- Consistent design across all empty states
+
+### 7. Toast Notifications
+
+**Feature**: User feedback system for actions
+
+**Requirements:**
+- Toast notifications for:
+  - Successful actions (create, update, delete)
+  - Error messages
+  - Warning messages
+  - Info messages
+- Auto-dismiss after configurable timeout
+- Manual dismiss option
+- Stack multiple toasts
+- Position: top-right or bottom-right
+- Accessible (screen reader support)
+
+**Technical Approach:**
+- Use sonner or react-hot-toast library
+- Consistent styling with design system
+- Different variants (success, error, warning, info)
+- Action buttons within toasts when needed
+
+### 8. Logo & Favicon
+
+**Current State**: No logo or favicon
+
+**Required:**
+- Logo design for LeanSpec brand
+- Multiple sizes for different uses:
+  - Header logo (with and without text)
+  - Favicon (16x16, 32x32, 192x192, 512x512)
+  - Apple touch icon
+  - Social media preview image (og:image)
+- SVG format for scalability
+- Dark/light mode variants if needed
+
+**Technical Approach:**
+- Work with designer or use AI tools to generate logo
+- Export in all required formats
+- Add to Next.js public directory
+- Update metadata in layout.tsx
+- Test across browsers and devices
+
+### 9. Accessibility Improvements
+
+**Requirements:**
+- WCAG 2.1 AA compliance
+- Keyboard navigation for all interactive elements
+- Focus indicators visible and clear
+- Screen reader support (ARIA labels, roles)
+- Skip links for main content
+- Proper heading hierarchy
+- Color contrast validation (all text meets AA standard)
+- Form accessibility (labels, error messages)
+
+**Technical Approach:**
+- Run Lighthouse accessibility audit
+- Use axe DevTools for testing
+- Test with keyboard only
+- Test with screen reader (VoiceOver, NVDA)
+- Fix all critical and high priority issues
+
+## Plan
+
+### Phase 2A: Core UX Improvements (Week 1-2)
+
+**Week 1: Navigation & Search**
+- [ ] Implement quick search modal (Cmd+K)
+- [ ] Add sidebar navigation to spec detail page
+- [ ] Make header sticky on scroll
+- [ ] Improve breadcrumb navigation
+- [ ] Test keyboard navigation flow
+
+**Week 2: Spec Detail Enhancements**
+- [ ] Redesign frontmatter display with better layout
+- [ ] Make left info panel sticky
+- [ ] Improve sub-spec navigation design
+- [ ] Add sub-spec overview tab
+- [ ] Test on mobile devices
+
+### Phase 2B: Polish & Feedback (Week 3)
+
+**Week 3: Loading & Empty States**
+- [ ] Create skeleton loader components
+- [ ] Add Suspense boundaries to all routes
+- [ ] Implement enhanced empty states
+- [ ] Add toast notification system
+- [ ] Test loading states with slow network
+
+### Phase 2C: Stats & Branding (Week 4)
+
+**Week 4: Completion**
+- [ ] Complete stats page with charts
+- [ ] Add logo and favicon
+- [ ] Run accessibility audit
+- [ ] Fix accessibility issues
+- [ ] Polish responsive design
+- [ ] Final QA testing
+
+## Test
+
+### Functional Testing
+- [ ] Quick search (Cmd+K) works across all pages
+- [ ] Search results are accurate and relevant
+- [ ] Sidebar navigation shows all specs and highlights current
+- [ ] Sticky header stays visible on scroll
+- [ ] Sticky info panel works on spec detail page
+- [ ] Sub-spec navigation is clear and functional
+- [ ] Loading skeletons appear during data fetch
+- [ ] Empty states show appropriate messages and CTAs
+- [ ] Toast notifications appear for all actions
+- [ ] Logo and favicon display correctly
+
+### Accessibility Testing
+- [ ] All interactive elements keyboard accessible
+- [ ] Focus indicators visible on all elements
+- [ ] Screen reader announces all important content
+- [ ] ARIA labels present where needed
+- [ ] Color contrast meets WCAG AA standard
+- [ ] Skip links work correctly
+- [ ] Forms have proper labels and error messages
+
+### Browser Testing
+- [ ] Chrome/Edge (latest)
+- [ ] Firefox (latest)
+- [ ] Safari (latest)
+- [ ] Mobile Safari (iOS)
+- [ ] Mobile Chrome (Android)
+
+### Performance Testing
+- [ ] Page load times remain under 2s
+- [ ] Search responds instantly (<100ms)
+- [ ] Smooth animations (60fps)
+- [ ] No layout shift during loading
+- [ ] Lighthouse score >90 for all metrics
+
+## Notes
+
+### Dependencies
+- Related to spec 035 (live-specs-showcase)
+- Requires completion of Phase 1 MVP
+- Some features may require design input/review
+
+### Design Decisions
+
+**Why Cmd+K for search?**
+- Industry standard (GitHub, Linear, Notion, etc.)
+- Discoverable and easy to remember
+- Doesn't conflict with browser shortcuts
+
+**Why toast notifications?**
+- Non-intrusive
+- Auto-dismiss reduces clutter
+- Standard pattern users expect
+- Better than modal dialogs for simple feedback
+
+**Why skeleton loaders?**
+- Research shows skeletons reduce perceived wait time
+- Better UX than spinners alone
+- Makes loading feel faster
+- Indicates layout structure
+
+### Open Questions
+- [ ] Should logo be designed in-house or contracted?
+- [ ] Do we need a design review for sub-spec navigation redesign?
+- [ ] Should stats page support custom date ranges or predefined only?
+- [ ] What's the budget for professional logo design?
+
+### Future Enhancements (Post Phase 2)
+- Collaborative features (comments, annotations)
+- Version history visualization
+- Advanced search with filters
+- Saved search queries
+- Keyboard shortcuts panel (showing all shortcuts)
+- Dark mode improvements (better colors, more contrast options)