@leanspec/ui 0.2.7 → 0.2.9-dev.20251205030455

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

@@ -1,357 +0,0 @@
----
-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)