viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
beadboard/docs/plans/2026-02-15-unified-ux-prd.md
zenchantlive 812b6cf8c5 docs: add planning documents for buff epic and unified UX 
STORY:
Major epics require upfront planning documentation. These docs capture
the design decisions, architecture, and rollout maps for the
Agent System Overhaul (bb-buff) and Unified UX (bb-ui2) epics.

COLLABORATION:
- 2026-02-14-operative-protocol-design.md: ZFC state machine design
- 2026-02-14-super-agent-buff-roadmap.md: buff epic architecture
- 2026-02-15-unified-ux-prd.md: UI epic product requirements
- docs/protocols/: protocol specifications

These documents serve as the source of truth for implementation decisions
and help future contributors understand the design rationale.
2026-02-15 21:19:14 -08:00

5.2 KiB
Raw Blame History

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