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