ColaFlow/docs/designs/STORY_UX_UI_DESIGN.md

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
2. User Personas & Scenarios
3. Information Architecture
4. Story Detail Page Design
5. Kanban Board Story Creation Flow
6. Component Specifications
7. User Flow Diagrams
8. Interaction Specifications
9. Responsive Design
10. 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:

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:

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:

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:

.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:

acceptanceCriteria: z.array(
  z.object({
    text: z.string(),
    completed: z.boolean().default(false)
  })
).optional()

2. Add Assignee Selector:

assigneeId: z.string().uuid().optional()

3. Add Tags/Labels:

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:

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:

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

Event Types:

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:

.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:

.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

/* 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:

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

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

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

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

// When dialog opens
dialogElement.focus();
trapFocus(dialogElement);

// When dialog closes
returnFocusTo(triggerElement);

Story Navigation:

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

---

Design Tokens

Colors (ColaFlow Design System)

: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

/* 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

/* 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

/* 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

/* 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