212 lines
5.2 KiB
Markdown
212 lines
5.2 KiB
Markdown
|
# Unified UX PRD - Swimlane Social Hub
|
||
|
|
|
||
|
|
> **Version**: 1.0
|
||
|
|
> **Date**: 2026-02-15
|
||
|
|
> **Status**: Planning Complete - Ready for Bead Creation
|
||
|
|
> **Supersedes**: bb-u6f.7 (Unified Cross-Surface Navigation)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Executive Summary
|
||
|
|
|
||
|
|
### Problem
|
||
|
|
BeadBoard has 4 fragmented pages with:
|
||
|
|
- No shared navigation or state
|
||
|
|
- Inconsistent design language (Aero Chrome glass-morphism feels dated)
|
||
|
|
- /sessions has good tech but missed the UX mark
|
||
|
|
- Users cannot supervise multi-agent teams in one cohesive experience
|
||
|
|
|
||
|
|
### Solution
|
||
|
|
Single unified shell at `/` with 3 views:
|
||
|
|
- **Social** - Task activity feed with blocks/unlocks
|
||
|
|
- **Graph** - Dependency visualization
|
||
|
|
- **Swarm** - Team health dashboard
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Key Decisions (Immutable)
|
||
|
|
|
||
|
|
| # | Decision | Choice | Rationale |
|
||
|
|
|---|----------|--------|-----------|
|
||
|
|
| 1 | Routing | Single page at `/` with client tabs | Preserves selection state |
|
||
|
|
| 2 | Views | 3 tabs: Social, Graph, Swarm | Sessions replaced by Social |
|
||
|
|
| 3 | Detail pattern | Right sidebar (desktop), drawer (mobile) | Best use of screens |
|
||
|
|
| 4 | Visual style | shadcn/ui + earthy-dark tokens | Replace Aero Chrome |
|
||
|
|
| 5 | Tailwind | Stay on v3, use shadcn/ui patterns | v4 has migration risks |
|
||
|
|
| 6 | Old pages | Copy page.tsx to page-old.tsx | Safe rollback |
|
||
|
|
| 7 | Card pattern | Same base for Social and Swarm | Reusable components |
|
||
|
|
| 8 | Threads | In detail strip for both views | Comments + events |
|
||
|
|
| 9 | Agent presence | Embedded in swarm cards | Agents primary in Swarm |
|
||
|
|
| 10 | Swarm sorting | Health (default), Activity, Progress | Auto-surface attention |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Skills Required (Non-Negotiable)
|
||
|
|
|
||
|
|
1. **verification-before-completion** - Never claim done without proving commands
|
||
|
|
2. **test-driven-development** - Write failing tests first
|
||
|
|
3. **beadboard-driver** - Use bd commands for all bead operations
|
||
|
|
4. **linus-beads-discipline** - Single source of truth, evidence before assertion
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Design System Specification
|
||
|
|
|
||
|
|
### Color Palette (Earthy-Dark)
|
||
|
|
|
||
|
|
Backgrounds:
|
||
|
|
- --color-bg-base: #2D2D2D
|
||
|
|
- --color-bg-card: #363636
|
||
|
|
- --color-bg-input: #404040
|
||
|
|
|
||
|
|
Accents:
|
||
|
|
- --color-accent-green: #7CB97A (primary CTA)
|
||
|
|
- --color-accent-amber: #D4A574 (warning)
|
||
|
|
- --color-accent-teal: #5BA8A0 (secondary)
|
||
|
|
|
||
|
|
Text:
|
||
|
|
- --color-text-primary: #FFFFFF
|
||
|
|
- --color-text-secondary: #B8B8B8
|
||
|
|
- --color-text-muted: #888888
|
||
|
|
|
||
|
|
Status:
|
||
|
|
- ready: teal #5BA8A0
|
||
|
|
- in_progress: green #7CB97A
|
||
|
|
- blocked: amber #D4A574
|
||
|
|
- closed: muted #888888
|
||
|
|
|
||
|
|
Liveness:
|
||
|
|
- active: #7CB97A
|
||
|
|
- stale: #D4A574
|
||
|
|
- stuck: #E57373
|
||
|
|
- dead: #9E4244
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Layout Architecture
|
||
|
|
|
||
|
|
Shell Structure (CSS Grid):
|
||
|
|
- TOP BAR: 3rem fixed
|
||
|
|
- LEFT: 13rem (channel tree)
|
||
|
|
- MIDDLE: flex-1 (card grid)
|
||
|
|
- RIGHT: 17rem (detail strip)
|
||
|
|
|
||
|
|
Responsive:
|
||
|
|
- < 768px: Full width, drawer overlay
|
||
|
|
- 768-1024px: Left collapses, slide-over
|
||
|
|
- >= 1024px: Full 3-panel
|
||
|
|
|
||
|
|
URL State:
|
||
|
|
- view: social | graph | swarm
|
||
|
|
- task: selected task ID
|
||
|
|
- swarm: selected swarm ID
|
||
|
|
- panel: open | closed
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## View Specifications
|
||
|
|
|
||
|
|
### Social View
|
||
|
|
Card: Task ID (teal), Title (bold), UNLOCKS (rose), BLOCKS (amber), Agents, View-jump icons
|
||
|
|
|
||
|
|
### Graph View
|
||
|
|
Keep ReactFlow + Dagre, add fitView() on tab activation
|
||
|
|
|
||
|
|
### Swarm View
|
||
|
|
Card: Swarm ID, Epic title, AGENTS roster with status glow, ATTENTION items, Progress bar, Last activity
|
||
|
|
|
||
|
|
Sorting: Health (default), Activity, Progress, Name
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Dependency Graph (Bead Flow)
|
||
|
|
|
||
|
|
PHASE 0: Design Foundation
|
||
|
|
[0.1] Token System
|
||
|
|
[0.2] shadcn/ui Setup
|
||
|
|
[0.3] Base Primitives
|
||
|
|
|
||
|
|
PHASE 1: Shell Layout
|
||
|
|
[1.1] URL State Hook
|
||
|
|
[1.2] UnifiedShell Component <- [0.*][1.1]
|
||
|
|
[1.3] TopBar Component <- [1.2]
|
||
|
|
[1.4] LeftPanel Component <- [1.2]
|
||
|
|
[1.5] RightPanel Component <- [1.2]
|
||
|
|
[1.6] Responsive Behavior <- [1.3-1.5]
|
||
|
|
|
||
|
|
PHASE 2: Social View
|
||
|
|
[2.1] Social Card Data Builder
|
||
|
|
[2.2] SocialCard Component <- [0.3][2.1]
|
||
|
|
[2.3] Social Detail Strip <- [1.5][2.1]
|
||
|
|
[2.4] Thread View Component <- [2.3]
|
||
|
|
[2.5] Social View Integration <- [1.2][2.2-2.4]
|
||
|
|
|
||
|
|
PHASE 3: Swarm View
|
||
|
|
[3.1] Swarm Card Data Builder
|
||
|
|
[3.2] SwarmCard Component <- [0.3][3.1]
|
||
|
|
[3.3] Swarm Detail Strip <- [1.5][3.1]
|
||
|
|
[3.4] Swarm View Integration <- [1.2][3.2-3.3]
|
||
|
|
|
||
|
|
PHASE 4: Graph Migration
|
||
|
|
[4.1] Graph Component Extraction
|
||
|
|
[4.2] Graph Tab Integration <- [1.2][4.1]
|
||
|
|
[4.3] fitView Fix <- [4.2]
|
||
|
|
|
||
|
|
PHASE 5: Polish
|
||
|
|
[5.1] Deep Link Verification <- [all above]
|
||
|
|
[5.2] Mobile Responsive Polish
|
||
|
|
[5.3] Screenshot Evidence
|
||
|
|
[5.4] Final Quality Gates
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Verification Gates (Required)
|
||
|
|
|
||
|
|
Every bead MUST pass before closing:
|
||
|
|
- npm run typecheck
|
||
|
|
- npm run lint
|
||
|
|
- npm run test
|
||
|
|
- Screenshots for UI changes
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Risk Register
|
||
|
|
|
||
|
|
| Risk | Mitigation |
|
||
|
|
|------|------------|
|
||
|
|
| ReactFlow resize | Use visibility:hidden + fitView() |
|
||
|
|
| shadcn + Tailwind v3 | Follow shadcn v3 docs |
|
||
|
|
| Mobile keyboard | Full-screen drawer on mobile |
|
||
|
|
| URL race conditions | URL is single source of truth |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Migration Checklist
|
||
|
|
|
||
|
|
Pre:
|
||
|
|
- [ ] Copy page.tsx to page-old.tsx
|
||
|
|
- [ ] Verify tests pass
|
||
|
|
|
||
|
|
During:
|
||
|
|
- [ ] Install shadcn/ui
|
||
|
|
- [ ] Create globals.css with earthy-dark tokens
|
||
|
|
- [ ] Build phases in order
|
||
|
|
|
||
|
|
Post:
|
||
|
|
- [ ] All 3 views functional
|
||
|
|
- [ ] Deep links work
|
||
|
|
- [ ] Mobile verified
|
||
|
|
- [ ] Screenshots captured
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Appendix: shadcn/ui Setup
|
||
|
|
|
||
|
|
bash:
|
||
|
|
npx shadcn@latest init
|
||
|
|
npx shadcn@latest add button card badge avatar input scroll-area separator tooltip dropdown-menu
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
*End of PRD - Ready for Bead Creation*
|