SuperCharged-Claude-Code-Upgrade/docs/plans/2025-01-19-landing-page-workflow-design.md

Landing Page Workflow Design

Date: 2025-01-19 Status: Approved Author: Claude (with user collaboration)

Overview

Enhance the /claude/ landing page to provide a streamlined "Create New Project" or "Load Existing Project" workflow with improved UX while maintaining fast navigation to the IDE.

Design Philosophy: Speed and simplicity - minimize friction for developers who want to get from idea → code as quickly as possible.

Architecture

Component Structure

SessionsPage
├── SessionsGrid (main container)
│   └── SessionCard (enhanced with metadata)
├── QuickStartGrid
│   ├── TemplateCard (React, Node.js, etc.)
│   └── BlankProjectCard (with inline name input)
└── NavigationManager (handles transitions)

Data Flow

Page Load → Fetch sessions → Cache locally → Render grid
                ↓
User clicks card → Show loading overlay → Navigate to /claude/ide

State Management

{
  sessions: Map<sessionId, sessionData>,
  loading: boolean,
  error: string | null,
  isNavigating: boolean
}

UI/UX Design

Enhanced Session Cards

Layout:

• Left: Icon (💬 active, 📁 historical)
• Middle:
  • Project name (bold, 20px) - inline editable
  • Working directory (monospace, 13px, gray)
  • Last message preview (14px, truncated to 100 chars)
  • File count badge (📄 N files)
  • Relative time ("5 min ago")
• Right:
  • Continue button (primary CTA)
  • ⋮ menu (Duplicate, Delete)

Interactions:

• Hover: Lift effect (translateY: -4px), border highlight
• Click project name → inline edit mode
• Click Continue → loading overlay → navigate to IDE

Inline Name Editing

• Click name → transforms to input field
• Save on blur or Enter
• Revert on Escape
• Show spinner while saving
• Validation: Max 50 chars, no special characters

Blank Project Card

• Shows input field instead of static text
• Placeholder: "Enter project name..."
• Start button active when name entered
• Creates session with metadata.project = name

Loading States

• Full-page overlay with spinner
• Message: "Opening workspace..." or "Creating project..."
• Duration: 300-800ms minimum for smooth UX

Quick Actions (Card Menu)

• Continue: Navigate to IDE chat with this session
• Duplicate: Create new session with same dir/metadata
• Delete: Remove session with confirmation

API Endpoints

Existing (to be enhanced)

GET /claude/api/claude/sessions

• Enhancement: Include lastMessage and fileCount in response
• Calculate from outputBuffer server-side

POST /claude/api/claude/sessions

• Enhancement: Accept metadata.project for custom naming

New Endpoints

PATCH /claude/api/claude/sessions/:id

• Update session metadata
• Body: { metadata: { project: "New Name" } }
• Returns: Updated session object

POST /claude/api/claude/sessions/:id/duplicate

• Create new session with same working directory and metadata
• Returns: { success: true, session: { id, ... } }

DELETE /claude/api/claude/sessions/:id

• Delete session file from disk
• Returns: { success: true }

Data Handling

File Count Calculation

function getFileCount(session) {
  const writeTags = session.outputBuffer.filter(entry =>
    entry.content.includes('<dyad-write')
  );
  return writeTags.length;
}

Relative Time Format

function getRelativeTime(date) {
  const seconds = Math.floor((new Date() - date) / 1000);
  if (seconds < 60) return 'just now';
  if (seconds < 3600) return `${Math.floor(seconds/60)} min ago`;
  if (seconds < 86400) return `${Math.floor(seconds/3600)} hours ago`;
  return `${Math.floor(seconds/86400)} days ago`;
}

Session Cache

• Use Map for O(1) lookups
• Invalidate on explicit refresh or error
• Serve stale data with error banner on fetch failure

Error Handling

Network Failures

1. Session fetch fails

   • Show: "Failed to load sessions. 🔄 Retry"
   • Keep stale data if cached
   • Auto-retry after 30s (exponential backoff)

2. Session creation fails

   • Hide loading overlay
   • Toast: "Failed to create project: [error]"
   • Stay on landing page

3. Name update fails

   • Revert to original name
   • Toast: "Failed to save name"

Empty States

No sessions:

📁 No projects yet

Create your first project to start building with AI
[Templates below...]

No active sessions:

• Show: "No active projects"
• CTA: "Create New Project"
• Still show historical sessions

Validation Rules

• Project name: Max 50 chars, no / \ < > : " | ? *
• Trim whitespace
• Show character count: "23/50"

Race Conditions

• Rapid clicking: isNavigating flag, disable clicks during navigation
• Edit while deleted: On save failure, refresh list, show "Session no longer exists"

Implementation Plan

Phase 1: Backend Enhancements (1-2 hours)

• Add PATCH /sessions/:id endpoint
• Add POST /sessions/:id/duplicate endpoint
• Add DELETE /sessions/:id endpoint
• Enhance session list with lastMessage and fileCount

Phase 2: Frontend Components (2-3 hours)

• Refactor sessions-landing.js with state management
• Create SessionCard class/component
• Implement inline name editing
• Add loading overlays

Phase 3: Quick Start Enhancement (1 hour)

• Add project name input to blank project card
• Pass name to API on creation

Phase 4: Polish (1 hour)

• Relative time formatting
• Card hover effects
• Error toasts and retry
• End-to-end testing

Total Estimate: 5-7 hours

Testing Checklist

• Create blank project with custom name
• Create project from template
• Edit project name inline
• Continue to IDE chat
• Duplicate session
• Delete session
• View empty session
• View session with files
• Network failure handling
• Empty state display
• Rapid clicking (race conditions)
• Historical vs active display
• Mobile responsive

Browsers: Chrome, Firefox, Safari Screen Sizes: Desktop (1920px), Tablet (768px), Mobile (375px)

Success Criteria

1. ✅ Users can create/load projects in 1-2 clicks
2. ✅ Navigation to IDE takes < 1 second perceived time
3. ✅ All error states handled gracefully
4. ✅ Project names are editable and persist
5. ✅ Mobile-responsive design
6. ✅ No data loss on network failures