1409 lines
40 KiB
Markdown
1409 lines
40 KiB
Markdown
# 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**
|