# Story Management UX/UI Design Specification

**Version:** 1.0
**Date:** 2025-11-05
**Designer:** UX/UI Team
**Project:** ColaFlow - Story Management Features

---

## Table of Contents

1. [Design Overview](#design-overview)
2. [User Personas & Scenarios](#user-personas--scenarios)
3. [Information Architecture](#information-architecture)
4. [Story Detail Page Design](#story-detail-page-design)
5. [Kanban Board Story Creation Flow](#kanban-board-story-creation-flow)
6. [Component Specifications](#component-specifications)
7. [User Flow Diagrams](#user-flow-diagrams)
8. [Interaction Specifications](#interaction-specifications)
9. [Responsive Design](#responsive-design)
10. [Accessibility Guidelines](#accessibility-guidelines)

---

## Design Overview

### Design Goals

1. **Consistency**: Maintain visual and interaction consistency with existing Epic pages
2. **Efficiency**: Minimize clicks and cognitive load for common operations
3. **Clarity**: Provide clear hierarchy and relationships between Epic → Story → Task
4. **Feedback**: Instant visual feedback for all user actions
5. **Scalability**: Design supports 10-100+ stories per epic

### Design Principles (ColaFlow)

- **Flow (流畅)**: Seamless navigation between Epic → Story → Task
- **Smart (智能)**: Quick actions, keyboard shortcuts, batch operations
- **Transparent (透明)**: Clear status, visible relationships, predictable behavior
- **Collaborative (协作)**: Real-time updates, clear ownership, change history

---

## User Personas & Scenarios

### Primary Persona: Lisa (Product Manager, 30)

**Goals:**
- Break down Epics into manageable Stories
- Track Story progress and dependencies
- Assign Stories to team members
- Review Story details quickly

**Pain Points:**
- Too many clicks to create Stories
- Hard to see Story relationships
- Difficult to find specific Stories
- No quick way to update Story status

**Key User Journey:**
```
Epic List → Select Epic → View Stories → Create Story → Add Tasks → Track Progress
```

### Secondary Persona: David (Developer, 28)

**Goals:**
- View assigned Stories
- Update Story status quickly
- Add Tasks under Stories
- Check acceptance criteria

**Pain Points:**
- Status updates require multiple clicks
- Can't see all Story details at once
- Hard to navigate between related items

---

## Information Architecture

### Story Hierarchy

```
Project
  └── Epic (High-level feature grouping)
       └── Story (User-facing feature, 1-2 weeks)
            └── Task (Technical implementation, 1-3 days)
                 └── Sub-Task (Granular work item, hours)
```

### Story Attributes

**Core Fields:**
- Title (required, max 200 chars)
- Description (optional, max 2000 chars, markdown support)
- Status: Backlog → Todo → InProgress → Done
- Priority: Low | Medium | High | Critical

**Time Tracking:**
- Estimated Hours (optional, decimal)
- Actual Hours (auto-calculated from Tasks)
- % Complete (based on Task completion)

**Relationships:**
- Parent Epic (required, immutable after creation)
- Child Tasks (0-20 typical)
- Assignee (optional, single user)
- Watchers (optional, multiple users)

**Metadata:**
- Created By, Created At
- Updated By, Updated At
- Tenant ID (for multi-tenancy)

---

## Story Detail Page Design

### Page Layout Structure

```
┌────────────────────────────────────────────────────────────────┐
│ BREADCRUMB NAV                                   [Actions]     │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [←] STORY TITLE                            [Edit] [Delete]    │
│      [Status Badge] [Priority Badge]                           │
│                                                                 │
├────────────────────────────────────────────────────────────────┤
│ ┌────────────────────────────────────┐ ┌──────────────────┐  │
│ │ Story Details Card                  │ │ Metadata Sidebar │  │
│ │                                     │ │                  │  │
│ │ Description                         │ │ Status           │  │
│ │ [Rich text / Markdown]              │ │ Priority         │  │
│ │                                     │ │ Assignee         │  │
│ │ Acceptance Criteria                 │ │ Est/Actual Hours │  │
│ │ - [ ] Criterion 1                   │ │ Created          │  │
│ │ - [ ] Criterion 2                   │ │ Updated          │  │
│ │                                     │ │                  │  │
│ └────────────────────────────────────┘ │ Parent Epic      │  │
│                                         │ [Epic Card]      │  │
│ ┌────────────────────────────────────┐ └──────────────────┘  │
│ │ Tasks (8)              [+ Add Task]│                       │
│ ├────────────────────────────────────┤                       │
│ │ [ ] Task 1 - Backend API            │                       │
│ │     [Medium] [Todo] [David] [8h]    │                       │
│ │                                     │                       │
│ │ [✓] Task 2 - Frontend UI            │                       │
│ │     [High] [Done] [Lisa] [12h]      │                       │
│ │                                     │                       │
│ │ [ ] Task 3 - Testing                │                       │
│ │     [Low] [Todo] [QA Team] [4h]     │                       │
│ └────────────────────────────────────┘                       │
│                                                                 │
│ ┌────────────────────────────────────────────────────────────┐│
│ │ Activity Timeline                                          ││
│ │ ──────────────────────────────────────────────────────────││
│ │ 🔵 Lisa changed status from Todo → InProgress   2h ago    ││
│ │ 📝 David added Task "Backend API"                1d ago    ││
│ │ 💬 QA Team commented "Needs test cases"          2d ago    ││
│ └────────────────────────────────────────────────────────────┘│
└────────────────────────────────────────────────────────────────┘
```

### Detailed Component Breakdown

#### 1. Breadcrumb Navigation

**Purpose:** Help users understand context and navigate hierarchy

**Design:**
```
Projects > Project Alpha > Epics > User Authentication > Story: Login Page
   ↑           ↑            ↑              ↑                      ↑
 (link)      (link)       (link)         (link)                (current)
```

**Specs:**
- Font: 14px, Regular
- Color: Muted (--muted-foreground)
- Hover: Foreground (--foreground)
- Separator: `/` with 8px spacing
- Current page: Bold, non-clickable

**Interaction:**
- Click any level to navigate up hierarchy
- Truncate long names with ellipsis (max 40 chars)
- Show full name on hover tooltip

#### 2. Story Header

**Layout:**
```
┌─────────────────────────────────────────────────────────┐
│ [←]  Story Title (32px, Bold)         [Edit] [Delete]   │
│      [Status Badge] [Priority Badge]                    │
└─────────────────────────────────────────────────────────┘
```

**Back Button:**
- Icon: ArrowLeft (20px)
- Action: Navigate to parent Epic detail page
- Keyboard: ESC key alternative

**Title:**
- Font: 32px, Bold (--font-display)
- Max width: 80% of container
- Line clamp: 2 lines
- Editable: Click to edit inline (future enhancement)

**Status Badge:**
```css
Backlog:    bg-slate-100    text-slate-700    border-slate-300
Todo:       bg-blue-100     text-blue-700     border-blue-300
InProgress: bg-amber-100    text-amber-700    border-amber-300
Done:       bg-green-100    text-green-700    border-green-300
```

**Priority Badge:**
```css
Low:       bg-blue-100     text-blue-700
Medium:    bg-yellow-100   text-yellow-700
High:      bg-orange-100   text-orange-700
Critical:  bg-red-100      text-red-700
```

**Actions:**
- Edit: Opens Story Form dialog (same as Epic)
- Delete: Confirmation dialog with cascade warning

#### 3. Story Details Card

**Description Section:**
- Rich text display (supports markdown)
- Placeholder: "No description provided"
- Edit mode: Toggle to markdown editor
- Max length: 2000 characters
- Auto-save: Save draft every 30 seconds

**Acceptance Criteria Section:**
- Checkbox list format
- Each criterion is a separate line
- Checkboxes are interactive (only for Assignee/Owner)
- % Complete indicator based on checked items
- Example:
  ```
  Acceptance Criteria (2/3 complete)
  [✓] User can enter email and password
  [✓] Form validates inputs correctly
  [ ] Error messages display inline
  ```

#### 4. Metadata Sidebar

**Design:**
```
┌──────────────────────┐
│ Status               │
│ [Dropdown: Todo ▼]   │
│                      │
│ Priority             │
│ [Dropdown: High ▼]   │
│                      │
│ Assignee             │
│ [Avatar] David Chen  │
│ [Change]             │
│                      │
│ Time Tracking        │
│ Est: 16h / Actual: 8h│
│ [Progress: 50%]      │
│                      │
│ Dates                │
│ Created: 2d ago      │
│ Updated: 1h ago      │
│                      │
│ Parent Epic          │
│ ┌──────────────────┐│
│ │ 🎯 User Auth     ││
│ │ [High] [InProg]  ││
│ │ 12 stories       ││
│ └──────────────────┘│
│ [View Epic]          │
└──────────────────────┘
```

**Status Dropdown:**
- Visual indicator: Colored dot
- Quick transition: Drag Story to change status (Kanban)
- Keyboard: 1=Backlog, 2=Todo, 3=InProgress, 4=Done

**Assignee Selector:**
- Searchable dropdown
- Shows avatar + name
- Recent users at top
- Unassigned option available

**Parent Epic Card:**
- Compact card showing Epic info
- Click to navigate to Epic detail
- Shows Epic status and progress

#### 5. Tasks Section

**Layout:**
```
┌─────────────────────────────────────────────────────┐
│ Tasks (8)  [Filters ▼]  [Sort: Priority ▼]  [+ Add] │
├─────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────┐ │
│ │ [ ] Implement user login endpoint              │ │
│ │     [Medium] [Todo] [David] [8h] [...actions]  │ │
│ │     Backend API endpoint with JWT auth         │ │
│ └─────────────────────────────────────────────────┘ │
│                                                      │
│ ┌─────────────────────────────────────────────────┐ │
│ │ [✓] Create login form UI                       │ │
│ │     [High] [Done] [Lisa] [12h] [...actions]    │ │
│ │     React component with validation            │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
```

**Task Card Design:**
- Checkbox: Complete/Incomplete (updates status)
- Title: Bold, 16px
- Metadata row: Badges for Priority, Status, Assignee, Time
- Description: Truncated to 1 line, expand on click
- Actions menu: Edit, Delete, Duplicate, Convert to Story

**Interactions:**
- Click Task: Navigate to Task detail page (future)
- Click Checkbox: Toggle status (Todo ↔ Done)
- Drag to reorder: Change priority order
- Quick edit: Inline edit title on double-click

**Filters:**
- Status: All, Todo, InProgress, Done
- Priority: All, Low, Medium, High, Critical
- Assignee: All, Unassigned, Me, [Team members]

**Sort Options:**
- Priority (High → Low)
- Status (Todo → Done)
- Created date (Newest/Oldest)
- Assignee (A-Z)

#### 6. Activity Timeline

**Design:**
```
┌─────────────────────────────────────────────────────┐
│ Activity Timeline                [Filter: All ▼]    │
├─────────────────────────────────────────────────────┤
│ 🔵 Lisa changed status Todo → InProgress   2h ago   │
│ 📝 David added Task "Backend API"          1d ago   │
│ 💬 QA Team commented "Needs test"          2d ago   │
│ 👤 Assigned to David Chen                  3d ago   │
│ 🎨 Priority changed to High                3d ago   │
│ ✨ Story created by Lisa                   5d ago   │
│                                                      │
│ [Load More]                                          │
└─────────────────────────────────────────────────────┘
```

**Event Types:**
- Status change: Blue circle
- Task added/removed: Document icon
- Comment: Chat bubble
- Assignment: User icon
- Priority change: Flag icon
- Created: Sparkle icon

**Event Format:**
- Icon + Actor + Action + Target + Timestamp
- Clickable: Shows detailed diff/change
- Relative timestamps: "2h ago", "1d ago"
- Filter: All, Changes, Comments, Assignments

---

## Kanban Board Story Creation Flow

### Current State Analysis

**Existing Epic Kanban:**
- Creates Epics via "+ New Epic" button
- Opens dialog with Epic form
- Limited context about parent project

**Improvement Opportunities:**
- Add quick Story creation from Epic cards
- Inline Story creation in Kanban columns
- Batch Story creation from Epic

### Proposed Story Creation Flow

#### Option 1: Dialog-Based (Current Pattern)

**Flow:**
```
1. User clicks [+ New Story] button in Epic detail page
2. Story Form Dialog opens (full screen overlay)
3. User fills form:
   - Parent Epic: Pre-selected (read-only)
   - Title: Required
   - Description: Optional
   - Priority: Dropdown (default: Medium)
   - Estimated Hours: Optional
4. User clicks [Create Story]
5. Dialog closes → Story appears in list → Toast notification
```

**Pros:**
- Consistent with existing Epic creation flow
- Full form validation
- More space for rich inputs (description)

**Cons:**
- Interrupts current view
- Slower for batch creation

#### Option 2: Inline Creation (Recommended)

**Flow:**
```
1. User clicks [+ Quick Add] button at top of Stories section
2. Inline form appears at top of list:
   ┌────────────────────────────────────────────────────┐
   │ 📝 Quick Add Story                                  │
   │ ┌────────────────────────────────────────────────┐ │
   │ │ Story title...                    [Priority ▼] │ │
   │ └────────────────────────────────────────────────┘ │
   │ [Cancel] [Add Story]  [Add & Create Tasks]        │
   └────────────────────────────────────────────────────┘
3. User types title, selects priority
4. User clicks [Add Story] → Story created → Form resets
   OR clicks [Add & Create Tasks] → Story created → Task form opens
```

**Pros:**
- Faster for multiple Stories
- No context switch
- Encourages breaking down Epics

**Cons:**
- Limited space for description
- Less validation visibility

#### Option 3: Hybrid Approach (Best of Both)

**Implementation:**
- Quick Add: Inline form for title + priority only
- Full Form: "+ New Story" button opens dialog
- Keyboard shortcut: Cmd/Ctrl + N for quick add
- Default: Quick Add visible, Full Form on demand

**User Choice:**
- Quick tasks: Use inline Quick Add
- Complex Stories: Use Full Form dialog

### Story Creation from Kanban Board

**New Feature: Add Story from Epic Card**

**Current Epic Card:**
```
┌─────────────────────────┐
│ 🎯 User Authentication   │
│ [High] [InProgress]      │
│ 12 stories, 45% complete │
│ [View Epic]              │
└─────────────────────────┘
```

**Enhanced Epic Card (Hover State):**
```
┌─────────────────────────┐
│ 🎯 User Authentication   │
│ [High] [InProgress]      │
│ 12 stories, 45% complete │
│ ────────────────────────│
│ [+ Add Story] [View]     │  ← New action row
└─────────────────────────┘
```

**Interaction:**
1. Hover over Epic card → Action bar appears
2. Click [+ Add Story] → Inline Story form opens below Epic card
3. Form is contextually bound to Epic
4. Create → Story appears in Kanban under correct status

**Benefits:**
- Contextual creation
- Faster workflow
- Reduces navigation

---

## Component Specifications

### 1. Story Card Component

**File:** `components/projects/story-card.tsx`

**Props:**
```typescript
interface StoryCardProps {
  story: Story;
  variant: 'list' | 'kanban' | 'compact';
  showActions?: boolean;
  onEdit?: (story: Story) => void;
  onDelete?: (storyId: string) => void;
  onStatusChange?: (storyId: string, status: WorkItemStatus) => void;
}
```

**Visual States:**
```css
.story-card {
  /* Default */
  border: 1px solid var(--border);
  background: var(--card);

  /* Hover */
  &:hover {
    border-color: var(--primary);
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
  }

  /* Selected */
  &[data-selected="true"] {
    border-color: var(--primary);
    background: var(--primary-50);
  }

  /* Dragging */
  &[data-dragging="true"] {
    opacity: 0.5;
    transform: rotate(2deg);
  }
}
```

**Variants:**

**List View:**
- Full width
- Shows description (3 lines max)
- Shows all metadata
- Action buttons on hover

**Kanban View:**
- Fixed width (280px)
- Compact metadata
- Drag handle visible
- Quick status change

**Compact View:**
- Minimal height
- Title + status only
- Used in Epic detail sidebar

### 2. Story Form Component

**File:** `components/projects/story-form.tsx` (existing, enhancements needed)

**Current Implementation:**
- Title, Description, Priority, Estimated Hours
- Parent Epic selector
- Basic validation

**Proposed Enhancements:**

1. **Add Acceptance Criteria Field:**
```typescript
acceptanceCriteria: z.array(
  z.object({
    text: z.string(),
    completed: z.boolean().default(false)
  })
).optional()
```

2. **Add Assignee Selector:**
```typescript
assigneeId: z.string().uuid().optional()
```

3. **Add Tags/Labels:**
```typescript
tags: z.array(z.string()).max(5).optional()
```

4. **Form Variants:**
- `mode: 'create' | 'edit' | 'quick'`
- Quick mode: Title + Priority only
- Full mode: All fields

### 3. Task List Component

**File:** `components/projects/task-list.tsx` (new)

**Purpose:** Display and manage Tasks under a Story

**Features:**
- Expandable Task cards
- Inline status update (checkbox)
- Filter by status, assignee, priority
- Sort by multiple criteria
- Bulk operations (multi-select)
- Drag to reorder

**Props:**
```typescript
interface TaskListProps {
  storyId: string;
  tasks: Task[];
  readonly?: boolean;
  onTaskCreate?: () => void;
  onTaskUpdate?: (task: Task) => void;
  onTaskDelete?: (taskId: string) => void;
  onTaskReorder?: (taskId: string, newOrder: number) => void;
}
```

### 4. Activity Timeline Component

**File:** `components/shared/activity-timeline.tsx` (new)

**Purpose:** Show change history for any entity

**Props:**
```typescript
interface ActivityTimelineProps {
  entityType: 'project' | 'epic' | 'story' | 'task';
  entityId: string;
  limit?: number; // Default: 10
  filter?: 'all' | 'changes' | 'comments' | 'assignments';
}
```

**Event Types:**
```typescript
type ActivityEvent = {
  id: string;
  type: 'status_change' | 'assignment' | 'comment' | 'field_change' | 'created';
  actor: User;
  timestamp: string;
  data: {
    field?: string;
    oldValue?: any;
    newValue?: any;
    comment?: string;
  };
};
```

---

## User Flow Diagrams

### Flow 1: View Story Details

```
Epic Detail Page
     │
     ├─ User clicks Story card
     │
     ▼
Story Detail Page
     │
     ├─ View description, acceptance criteria
     ├─ See parent Epic context (sidebar)
     ├─ Review Tasks (expand/collapse)
     ├─ Check Activity Timeline
     │
     ├─ User clicks [Edit]
     │   └─ Story Form Dialog opens
     │       └─ Make changes → Save → Page updates
     │
     ├─ User clicks Task
     │   └─ Navigate to Task Detail Page (future)
     │
     └─ User clicks Parent Epic card
         └─ Navigate back to Epic Detail Page
```

### Flow 2: Create Story (Quick Add)

```
Epic Detail Page
     │
     ├─ User clicks [+ Quick Add]
     │
     ▼
Inline Story Form appears
     │
     ├─ User types title: "Implement OAuth login"
     ├─ Selects priority: High
     │
     ├─ User presses Enter OR clicks [Add Story]
     │
     ▼
Story Created
     │
     ├─ Form resets (stays open for next Story)
     ├─ New Story appears at top of list
     ├─ Toast: "Story created successfully"
     │
     └─ User continues adding more Stories
         OR closes inline form
```

### Flow 3: Create Story (Full Form)

```
Epic Detail Page
     │
     ├─ User clicks [+ New Story]
     │
     ▼
Story Form Dialog opens
     │
     ├─ Parent Epic: Pre-selected (disabled)
     ├─ User fills:
     │   - Title: "Implement OAuth login"
     │   - Description: "Support Google and GitHub OAuth..."
     │   - Priority: High
     │   - Estimated Hours: 16
     │   - Assignee: David Chen
     │
     ├─ User clicks [Create Story]
     │   OR [Create & Add Tasks]
     │
     ▼
Story Created
     │
     ├─ Dialog closes
     ├─ New Story appears in list
     ├─ Toast: "Story created successfully"
     │
     └─ If [Create & Add Tasks]:
         └─ Navigate to Story Detail Page
             └─ Task creation form auto-opens
```

### Flow 4: Update Story Status

```
Story Detail Page
     │
     ├─ User clicks Status dropdown in sidebar
     │
     ▼
Status Menu opens
     │
     ├─ Options: Backlog, Todo, InProgress, Done
     ├─ Current status highlighted
     │
     ├─ User selects "InProgress"
     │
     ▼
Status Updated
     │
     ├─ Badge updates instantly
     ├─ Activity Timeline logs change
     ├─ SignalR broadcasts update (real-time)
     ├─ Toast: "Status updated to In Progress"
     │
     └─ If Story status = Done:
         └─ Check if all Tasks are complete
             └─ If not: Show warning modal
                 └─ "2 tasks are still incomplete. Mark Story as Done anyway?"
```

### Flow 5: Add Tasks to Story

```
Story Detail Page
     │
     ├─ User clicks [+ Add Task] in Tasks section
     │
     ▼
Inline Task Form appears
     │
     ├─ User types title: "Create login API endpoint"
     ├─ Sets priority: High
     ├─ Sets assignee: David Chen
     ├─ Sets estimated hours: 8
     │
     ├─ User clicks [Add Task]
     │
     ▼
Task Created
     │
     ├─ Form resets (stays open)
     ├─ Task appears in list
     ├─ Story progress updates (% complete)
     ├─ Toast: "Task added"
     │
     └─ User continues adding Tasks
         OR clicks [Cancel] to close form
```

### Flow 6: Delete Story (with Cascade Warning)

```
Story Detail Page
     │
     ├─ User clicks [Delete] button
     │
     ▼
Confirmation Dialog opens
     │
     ├─ Title: "Delete Story?"
     ├─ Message: "This will permanently delete the Story
     │            and its 5 associated Tasks. This cannot be undone."
     ├─ Tasks list preview shown
     │
     ├─ User clicks [Cancel] → Dialog closes
     │   OR
     ├─ User clicks [Delete Story]
     │
     ▼
Story Deleted
     │
     ├─ Navigate back to Epic Detail Page
     ├─ Story removed from list
     ├─ Toast: "Story and 5 tasks deleted"
     │
     └─ Activity logged in Epic Timeline
```

---

## Interaction Specifications

### Keyboard Shortcuts

**Global:**
- `Cmd/Ctrl + N` - Quick Add Story
- `Cmd/Ctrl + E` - Edit current Story
- `Cmd/Ctrl + S` - Save changes
- `ESC` - Close dialog / Cancel edit
- `Cmd/Ctrl + Enter` - Submit form

**Story Detail Page:**
- `1` - Set status to Backlog
- `2` - Set status to Todo
- `3` - Set status to InProgress
- `4` - Set status to Done
- `P` - Change priority
- `A` - Change assignee
- `T` - Add new Task
- `← / →` - Navigate to prev/next Story

**Story List:**
- `↑ / ↓` - Navigate Stories
- `Enter` - Open selected Story
- `Space` - Quick view Story details (modal)
- `Delete` - Delete selected Story

### Drag & Drop

**Story Cards (Kanban Board):**
```
1. User hovers over Story card
2. Drag handle (⋮⋮) appears on left
3. User clicks and drags Story
4. Valid drop zones highlighted (columns)
5. Drop Story in new column
6. Status updates automatically
7. SignalR broadcasts change
8. Toast: "Status changed to InProgress"
```

**Implementation:**
- Library: `@dnd-kit/core` (already in use)
- Drop zones: Kanban columns (Backlog, Todo, InProgress, Done)
- Visual feedback: Semi-transparent clone, highlighted drop zone
- Constraints: Cannot drag between different Epics

**Task Reordering (Story Detail):**
```
1. User drags Task within list
2. Drop position indicated by blue line
3. Release → Task moves to new position
4. Order saved to backend
5. No status change
```

### Hover States

**Story Card:**
```css
.story-card:hover {
  /* Border color change */
  border-color: var(--primary);

  /* Shadow */
  box-shadow: 0 4px 12px rgba(33, 150, 243, 0.15);

  /* Action buttons appear */
  .story-card__actions {
    opacity: 1;
    transform: translateY(0);
  }
}
```

**Task Checkbox:**
```css
.task-checkbox:hover {
  /* Scale up slightly */
  transform: scale(1.1);

  /* Border color */
  border-color: var(--primary);
}
```

### Loading States

**Story Detail Page:**
```
1. Initial load: Skeleton loaders
   - Header skeleton (title, badges)
   - Card skeleton (details)
   - Task list skeleton (3 rows)

2. Partial updates: Optimistic UI
   - Update UI immediately
   - Show spinner in background
   - Revert if error
```

**Story Creation:**
```
1. User submits form
2. Button shows spinner: [○ Creating...]
3. Form disabled (prevent double-submit)
4. On success: Close form, show toast
5. On error: Show error message, re-enable form
```

### Error States

**Story Not Found:**
```
┌────────────────────────────────────┐
│         404 Story Not Found         │
│                                     │
│  The Story you're looking for       │
│  doesn't exist or you don't have    │
│  permission to view it.             │
│                                     │
│  [Go Back]  [View All Stories]     │
└────────────────────────────────────┘
```

**Story Deletion Failed:**
```
Toast (destructive variant):
❌ Failed to delete Story
   Some Tasks are locked. Please complete them first.
   [View Details]
```

**Network Error:**
```
Inline message in Story Detail:
⚠️ Connection lost. Retrying...
   Some data may be out of date.
   [Refresh]
```

### Empty States

**No Stories in Epic:**
```
┌────────────────────────────────────────────┐
│         📝 No Stories Yet                   │
│                                             │
│  Break down this Epic into user Stories     │
│  to start planning your work.               │
│                                             │
│  [+ Create Your First Story]               │
│  [Learn about Stories →]                    │
└────────────────────────────────────────────┘
```

**No Tasks in Story:**
```
┌────────────────────────────────────────────┐
│         ☑️ No Tasks Yet                     │
│                                             │
│  Add technical Tasks to implement           │
│  this Story.                                │
│                                             │
│  [+ Add Task]                              │
└────────────────────────────────────────────┘
```

---

## Responsive Design

### Breakpoints

```css
/* Mobile: < 640px */
@media (max-width: 640px) {
  .story-detail-layout {
    /* Single column */
    grid-template-columns: 1fr;
  }

  .story-metadata-sidebar {
    /* Move to top */
    order: -1;
  }
}

/* Tablet: 640px - 1024px */
@media (min-width: 640px) and (max-width: 1024px) {
  .story-detail-layout {
    /* Two columns */
    grid-template-columns: 1fr 300px;
  }
}

/* Desktop: > 1024px */
@media (min-width: 1024px) {
  .story-detail-layout {
    /* Optimal layout */
    grid-template-columns: 1fr 320px;
    gap: 24px;
  }
}
```

### Mobile Optimizations

**Story Detail Page (Mobile):**
```
┌──────────────────────┐
│ [←] Story Title      │
│ [Status] [Priority]  │
├──────────────────────┤
│ [Tabs]               │
│ Details | Tasks | Activity
├──────────────────────┤
│ (Tab content)        │
│                      │
└──────────────────────┘
```

**Changes for Mobile:**
1. Sidebar moves to tabs
2. Action buttons in floating menu (⋮)
3. Swipe gestures: Left/Right to navigate Stories
4. Bottom sheet for forms (not full-page dialogs)

**Story List (Mobile):**
- Swipe right on card: Edit
- Swipe left on card: Delete
- Long press: Multi-select mode
- Pull to refresh: Reload Stories

---

## Accessibility Guidelines

### WCAG 2.1 Level AA Compliance

**Color Contrast:**
- Text on background: Minimum 4.5:1 ratio
- Large text (18px+): Minimum 3:1 ratio
- Status badges: All pass contrast check

**Keyboard Navigation:**
- All interactive elements are keyboard accessible
- Focus indicators: 2px solid outline, --focus-ring color
- Tab order follows visual hierarchy
- Skip links available: "Skip to Stories"

**Screen Reader Support:**

**Story Card:**
```html
<article
  role="article"
  aria-labelledby="story-title-123"
  aria-describedby="story-desc-123">

  <h3 id="story-title-123">Implement OAuth login</h3>

  <div aria-label="Status: In Progress">
    <span class="sr-only">Status:</span>
    <span>In Progress</span>
  </div>

  <div aria-label="Priority: High">
    <span class="sr-only">Priority:</span>
    <span>High</span>
  </div>

  <p id="story-desc-123" class="sr-only">
    Full Story description for screen readers
  </p>
</article>
```

**Status Dropdown:**
```html
<select
  aria-label="Change Story status"
  aria-describedby="status-help">
  <option value="Backlog">Backlog</option>
  <option value="Todo">Todo</option>
  <option value="InProgress" selected>In Progress</option>
  <option value="Done">Done</option>
</select>
<span id="status-help" class="sr-only">
  Current status: In Progress. Select a new status to update.
</span>
```

**Task Checkbox:**
```html
<input
  type="checkbox"
  id="task-123"
  aria-labelledby="task-title-123"
  aria-describedby="task-meta-123" />

<label for="task-123">
  <span id="task-title-123">Create login API endpoint</span>
</label>

<div id="task-meta-123" class="sr-only">
  Priority: High, Assignee: David Chen, Estimated: 8 hours
</div>
```

**Loading Announcements:**
```html
<div role="status" aria-live="polite" aria-atomic="true">
  Loading Story details...
</div>

<div role="alert" aria-live="assertive">
  Story updated successfully
</div>
```

### Focus Management

**Dialog Open/Close:**
```typescript
// When dialog opens
dialogElement.focus();
trapFocus(dialogElement);

// When dialog closes
returnFocusTo(triggerElement);
```

**Story Navigation:**
```typescript
// When navigating to Story detail
setTimeout(() => {
  document.getElementById('story-title').focus();
}, 100);
```

---

## Design Tokens

### Colors (ColaFlow Design System)

```css
:root {
  /* Status colors */
  --status-backlog: hsl(215, 16%, 47%);
  --status-backlog-bg: hsl(215, 16%, 95%);

  --status-todo: hsl(207, 90%, 54%);
  --status-todo-bg: hsl(207, 90%, 95%);

  --status-inprogress: hsl(43, 96%, 56%);
  --status-inprogress-bg: hsl(43, 96%, 95%);

  --status-done: hsl(142, 71%, 45%);
  --status-done-bg: hsl(142, 71%, 95%);

  /* Priority colors */
  --priority-low: hsl(207, 90%, 54%);
  --priority-low-bg: hsl(207, 90%, 95%);

  --priority-medium: hsl(43, 96%, 56%);
  --priority-medium-bg: hsl(43, 96%, 95%);

  --priority-high: hsl(25, 95%, 53%);
  --priority-high-bg: hsl(25, 95%, 95%);

  --priority-critical: hsl(0, 84%, 60%);
  --priority-critical-bg: hsl(0, 84%, 95%);
}
```

### Typography

```css
/* Story Title */
.story-title {
  font-family: var(--font-display);
  font-size: 32px;
  font-weight: 700;
  line-height: 1.2;
  letter-spacing: -0.02em;
}

/* Story Description */
.story-description {
  font-family: var(--font-body);
  font-size: 16px;
  font-weight: 400;
  line-height: 1.6;
  color: var(--foreground);
}

/* Metadata labels */
.story-label {
  font-size: 14px;
  font-weight: 500;
  color: var(--muted-foreground);
}

/* Metadata values */
.story-value {
  font-size: 14px;
  font-weight: 400;
  color: var(--foreground);
}
```

### Spacing

```css
/* Story card padding */
--story-card-padding: 16px;

/* Story detail sections */
--story-section-gap: 24px;

/* Form fields */
--form-field-gap: 16px;

/* Task list item spacing */
--task-item-gap: 8px;
```

### Shadows

```css
/* Story card hover */
--shadow-story-hover: 0 4px 12px rgba(33, 150, 243, 0.15);

/* Dialog overlay */
--shadow-dialog: 0 8px 32px rgba(0, 0, 0, 0.12);

/* Dropdown menu */
--shadow-dropdown: 0 2px 8px rgba(0, 0, 0, 0.1);
```

### Animation

```css
/* Story card hover transition */
.story-card {
  transition: all 150ms cubic-bezier(0.4, 0, 0.2, 1);
}

/* Dialog open/close */
.dialog {
  animation: dialog-open 200ms cubic-bezier(0.4, 0, 0.2, 1);
}

@keyframes dialog-open {
  from {
    opacity: 0;
    transform: scale(0.95);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
}

/* Status change */
.status-badge {
  transition: background-color 150ms ease-out;
}
```

---

## Implementation Priority

### Phase 1: Core Story Detail Page (Week 1)
- [ ] Story detail page layout
- [ ] Story metadata sidebar
- [ ] Story header with actions
- [ ] Basic Task list display
- [ ] Activity timeline (read-only)

### Phase 2: Story Creation & Editing (Week 2)
- [ ] Story Form enhancements (assignee, acceptance criteria)
- [ ] Inline Quick Add Story
- [ ] Edit Story in dialog
- [ ] Delete Story with confirmation

### Phase 3: Task Management (Week 3)
- [ ] Task list with filters and sorting
- [ ] Inline Task creation
- [ ] Task status update (checkbox)
- [ ] Task reordering (drag & drop)

### Phase 4: Kanban Enhancements (Week 4)
- [ ] Story cards in Kanban
- [ ] Drag Story to change status
- [ ] Quick Add Story from Epic card
- [ ] Bulk operations

### Phase 5: Polish & Accessibility (Week 5)
- [ ] Keyboard shortcuts
- [ ] Screen reader support
- [ ] Mobile responsive design
- [ ] Loading & error states
- [ ] Animation polish

---

## Success Metrics

### Usability Metrics
- **Task Completion Rate**: > 95% (create Story, edit Story, add Task)
- **Time to Create Story**: < 30 seconds (Quick Add)
- **Navigation Efficiency**: < 3 clicks from Epic to Task
- **Error Rate**: < 5% (form validation, API errors)

### Performance Metrics
- **Page Load Time**: < 1 second (Story detail)
- **Interaction Response**: < 100ms (status update, checkbox)
- **Real-time Update Delay**: < 500ms (SignalR)

### Accessibility Metrics
- **Keyboard Navigation**: 100% coverage
- **Screen Reader Support**: All critical paths
- **WCAG 2.1 AA**: 100% compliance
- **Focus Indicators**: Visible on all interactive elements

---

## Design Assets

### Figma Files (Placeholder)
- Story Detail Page: `figma.com/colaflow/story-detail`
- Story Form: `figma.com/colaflow/story-form`
- Task List: `figma.com/colaflow/task-list`
- Kanban Board: `figma.com/colaflow/kanban-v2`

### Component Library
- Storybook: `storybook.colaflow.com`
- Story Card: `storybook.colaflow.com/story-card`
- Story Form: `storybook.colaflow.com/story-form`
- Task List: `storybook.colaflow.com/task-list`

---

## Revision History

| Version | Date       | Author     | Changes                           |
|---------|------------|------------|-----------------------------------|
| 1.0     | 2025-11-05 | UX/UI Team | Initial design specification      |

---

## Appendix: Design References

### External Inspiration
- **Jira**: Epic/Story/Task hierarchy, Kanban board
- **Linear**: Clean UI, keyboard shortcuts, quick actions
- **Asana**: Task detail page, activity timeline
- **Monday.com**: Status colors, priority badges

### ColaFlow Design Philosophy
- **Flow**: Minimize friction, optimize for speed
- **Smart**: AI-assisted, context-aware
- **Transparent**: Clear status, predictable behavior
- **Collaborative**: Real-time updates, change history

---

**End of Document**