# Unified UX PRD - Swimlane Social Hub

> **Version**: 2.0  
> **Date**: 2026-02-16  
> **Status**: UPDATED - Complete Design Specification  
> **Supersedes**: Previous versions, bb-u6f.7

## Implementation Status

> **Last Updated: 2026-02-16**

### Phase 0: Design Foundation
- ✅ **bb-ui2.1** (codex-3fn) - Design Tokens Update - COMPLETED
  - Added complete earthy-dark token system in globals.css
  - Legacy Aero Chrome classes preserved for backward compatibility (gradual migration)
- ⏳ **bb-ui2.2** (codex-1ky) - Semantic Rename - READY (blocked by tokens - unblocked)
- ⏳ **bb-ui2.3** (codex-5vm) - Base Card Component - READY (blocked by tokens - unblocked)

### Phase 1-3: Not Started
- Planning complete, implementation pending Phase 0 completion


---

## Executive Summary

### Problem
BeadBoard has 4 fragmented pages with no shared navigation, no shared state, and inconsistent design language. The current Aero Chrome glass-morphism visual style has been rejected by users. Users want ONE cohesive experience for supervising multi-agent teams and managing tasks.

### Solution
Single unified shell at `/` with 4 switchable views (Social Feed, Swimlanes, Graph, Timeline), new earthy-dark design system, agent-prominent UX, and thoughtful interaction patterns throughout.

---

## Key Decisions (Immutable)

| # | Decision | Choice | Rationale |
|---|----------|--------|-----------|
| 1 | Routing | Single page + client tabs at / | Preserves selection state, panels never unmount |
| 2 | State Source | URL is Single Source of Truth | Prevents race conditions |
| 3 | Activity Feed | Context-aware (filters to selection) | Most useful for supervision workflow |
| 4 | Mobile | Hamburger left + slide-over right + bottom tabs | Standard pattern |
| 5 | Build Order | Tokens → Shell → Views (tracer bullet) | Real dependency chain |
| 6 | Card Interaction | Selection + detail strip below grid (desktop) | Grid stays uniform, split-view for conversation |
| 7 | Mobile Detail | Full-screen overlay (not split) | Keyboard takes 40% of screen |
| 8 | Visual Style | Earthy-dark design system (NOT Aero Chrome) | User provided full token spec |
| 9 | Agent Presence | Prominent - agents are the star | Avatars on every card, role-colored borders |
| 10 | Left Panel | Minimal with counts, nested epic tree | Status dots, hover tooltips |
| 11 | Card View-Jump | Small icons at card bottom | Jump to views with task pre-selected |
| 12 | Units | rem-based | Accessibility |

---

## Design Token Specification

### Color Palette

**Backgrounds:**
```css
--color-bg-base: #2D2D2D      /* primary background */
--color-bg-card: #363636      /* cards, elevated surfaces */
--color-bg-input: #404040     /* inputs, hover states */
```

**Accents:**
```css
--color-accent-green: #7CB97A   /* primary CTA, success, in-progress */
--color-accent-amber: #D4A574   /* warning, blocked */
--color-accent-teal: #5BA8A0    /* secondary, open/ready */
```

**Text:**
```css
--color-text-primary: #FFFFFF
--color-text-secondary: #B8B8B8
--color-text-muted: #888888
--color-text-on-primary: #1A1A1A
```

**Borders:**
```css
--color-border-default: #4A4A4A
--color-border-subtle: #3A3A3A
```

**Status Mapping:**
- open/ready → teal `#5BA8A0`
- in_progress → green `#7CB97A`
- blocked → amber `#D4A574`
- closed → muted `#888888`

**Agent Role Colors:**
- ui → `#6B9BD2` (steel blue)
- graph → `#7CB97A` (green)
- orchestrator → `#B08ED6` (soft purple)
- agent → `#B8B8B8` (neutral)
- researcher → `#D4A574` (amber)

**Liveness Colors:**
- active → `#7CB97A` (green, pulsing)
- stale → `#D4A574` (amber)
- evicted → `#C97A7A` (muted rose)
- idle → `#888888` (muted)

### Radii
```css
--radius-sm: 0.375rem      /* 6px */
--radius-card: 0.625rem    /* 10px */
--radius-modal: 1rem       /* 16px */
--radius-pill: 9999px
```

### Shadows
```css
--shadow-sm: 0 1px 2px rgba(0,0,0,0.1)
--shadow-md: 0 4px 12px rgba(0,0,0,0.15)
```

### Typography
- Font: system sans-serif (Inter if available)
- H1: 2rem/700, H2: 1.5rem/600, H3: 1.125rem/600
- Body: 0.875rem/400, Small: 0.75rem/400, Tiny: 0.6875rem/500
- Line-height: headings 1.2, body 1.5

### Spacing
- Base: 0.25rem (4px)
- Card padding: 1rem-1.25rem
- Gaps: 1rem
- Section gaps: 2rem-2.5rem

### Icons & Transitions
- Icons: Lucide React, 1.5-2px stroke, 1rem-1.5rem size
- Transitions: 150-200ms ease-out for all hover/focus

---

## Component Anatomy

### Social Feed Card

```
┌─────────────────────────────────────┐
│ [⊕]                           (top-R)│  expand icon
│                                     │
│ bb-buff.1.1                         │  task ID (tiny, teal)
│ Fix login bug on mobile             │  title (bold, white)
│                                     │
│ UNLOCKS:                            │  blocked-by (ROSE tint)
│  ● #123 Blocker task                │
│                                     │
│ BLOCKS:                             │  downstream (AMBER tint)
│  ● #234 Dependent task              │
│                                     │
│ "Found the issue in the auth..."    │  latest message (muted)
│                                     │
│ [●a-1] [●a-2]                       │  agent avatars (PROMINENT)
│                          [≡] [◊] [≋]│  view-jump icons
└─────────────────────────────────────┘
```

**Card Specs:**
- Background: `#363636`
- Border: 1px status-colored (teal/green/amber/muted)
- Border-radius: 10px
- Status dot on card matches status mapping
- Agent avatars have **role-colored left border**
- Blocks/unlocks have tinted backgrounds (rose #E57373/10%, amber #D4A574/10%)

**Blocks/Unlocks Pattern (reuse from task-card-grid.tsx):**
```tsx
// Container
rounded-lg p-2 border border-white/5

// "Unlocks" header (rose tint)
text-[9px] font-bold uppercase tracking-widest text-rose-400/80
bg-rose-500/10  // background tint

// "Blocks" header (amber tint)
text-[9px] font-bold uppercase tracking-widest text-amber-400/80
bg-amber-500/10  // background tint

// Individual item
rounded border border-white/5 bg-white/5 px-2.5 py-2
hover:border-sky-400/30 hover:bg-white/10 transition-colors
```

### ZFC Agent State Visuals

| State | Visual |
|-------|--------|
| idle | `#888888` static dot |
| spawning | `#5BA8A0` pulsing dot |
| running | `#7CB97A` animated dot |
| working | `#7CB97A` pulsing glow |
| stuck | `#D4A574` attention dot (needs help!) |
| done | `#7CB97A` check |
| stopped | `#888888` no animation |
| dead | `#C97A7A` warning |

### Agent Card (Right Panel)

```
┌──────────────────────┐
│ [●avatar] agent-1    │  role-colored left border
│ role: ui             │  role label
│ ● working · 2m ago   │  ZFC state dot + age
│ Task: buff.1.1       │  current task
│ [≡] [◊] [≋] [💬]      │  view-jump + message
└──────────────────────┘
```

### Swimlane Header
- Swarm name + computed counts: "3/8 done · 2 active · 1 ready · 1 blocked"
- Agent roster with ZFC state labels
- Collapsible

---

## Layout Architecture

### Shell Structure (CSS Grid)

```
┌──────────────────────────────────────────────────────────────────┐
│ TOP BAR (fixed, 3rem)                                            │
│ ≡  [Swimlanes|Graph|Timeline|Social]                      ◢     │
├──────────┬──────────────────────────────────┬────────────────────┤
│ LEFT     │ MIDDLE                           │ RIGHT              │
│ 13.75rem │ flex-1                           │ 17.5rem            │
│          │                                  │                    │
│ Channel  │ View content (swaps on tab)      │ Agents (~40%)      │
│ tree     │                                  │ ────────────────── │
│          │                                  │ Activity (~60%)    │
└──────────┴──────────────────────────────────┴────────────────────┘
```

**Grid:** `grid-template-columns: 13.75rem 1fr 17.5rem`

### Detail Strip Behavior

**Desktop (≥1024px):**
- Grid splits: cards (~45%) | detail strip (~55%)
- Strip slides in below grid when card selected
- Cards remain visible above

**Mobile (<768px):**
- Full-screen overlay (z-index above bottom tabs)
- Required: virtual keyboard takes 40% of screen
- Split view would leave 0px for conversation

### Responsive Behavior

| Size | Left | Middle | Right | Detail Strip |
|------|------|--------|-------|--------------|
| Desktop (≥1024px) | 13.75rem fixed | flex-1 | 17.5rem fixed | Below grid |
| Tablet (768-1024px) | Overlay | flex-1 | Overlay | Slide-over |
| Mobile (<768px) | Overlay | flex-1 | Hidden | Full-screen |

---

## Anti-Patterns (Forbidden)

- NO glass-morphism / backdrop-blur effects
- NO arbitrary Tailwind color values (use tokens)
- NO agent-unaware cards (every card shows agents)
- NO page-per-view routing (use client tabs)
- NO localStorage for view state (use URL)
- NO direct JSONL writes (use bd CLI)

---

## Recommended Bead Structure

### Phase 0: Design Foundation
**Goal:** Tokens + Primitives only. No views.

**bb-ui2.1a** - Token System Update  
- Update tokens.css with complete spec above
- Ensure all status/liveness/role colors defined
- Migrate away from Aero Chrome gradients

**bb-ui2.2a** - Card Primitive with Blocks/Unlocks  
- Build reusable Card component
- Implement blocks/unlocks section pattern (reuse task-card-grid.tsx logic)
- Status-colored borders
- Soft gradient backgrounds (amber/teal tints, not harsh Aero Chrome)

**bb-ui2.3a** - Agent Avatar Primitive  
- Avatar with role-colored ring
- ZFC state indicator (dot/pulse/glow)
- Size variants (sm, md, lg)

**bb-ui2.4a** - Status Utilities Update  
- Rewrite status-utils.tsx for new tokens
- Status badge component with pill + dot
- Liveness indicator component

### Phase 1: Layout Polish
**Goal:** Fix current layout issues, preserve structure

**bb-ui2.22** - Detail Strip Positioning Fix  
- Move from side drawer to below-grid (desktop)
- Full-screen overlay (mobile)
- Preserve URL state behavior
- Thread content actually shows selected bead data

**bb-ui2.23** - Activity Panel Polish  
- Split right panel: Agents (40%) + Activity (60%)
- Agent cards with ZFC states
- Context-aware activity filtering

**bb-ui2.24** - Mobile Responsive Polish  
- Bottom tab bar
- Panel overlays
- Touch-friendly targets

### Phase 2: Card Design Implementation
**Goal:** Implement complete card anatomy

**bb-ui2.25** - Social Feed Card Redesign  
- Full card anatomy from spec
- Blocks/unlocks with rose/amber tints
- Prominent agent avatars
- View-jump icons
- Expand icon → full-page popup

**bb-ui2.26** - Swimlane Card Redesign  
- Agent-first layout
- ZFC state prominent
- Status-colored border
- Drag-drop preserved

**bb-ui2.27** - Graph Node Redesign  
- New design tokens
- Agent avatars on nodes
- Selection syncs with store

### Phase 3: Cross-Cutting Polish
**Goal:** Deep links, mobile, final gates

**bb-ui2.28** - Deep Link Verification  
- All URL patterns work
- Browser back/forward
- Shareable URLs

**bb-ui2.29** - Screenshot Evidence  
- All breakpoints
- All views
- Mobile + desktop

**bb-ui2.30** - Final Gates  
- typecheck, lint, test
- Close epic

---

## Verification Strategy

After each bead:
```bash
npm run typecheck
npm run lint
npm run test
```

Visual verification:
- Screenshots at 390px, 768px, 1440px
- Compare against design spec
- Agent avatars visible on all cards
- Blocks/unlocks sections tinted correctly

---

*End of PRD v2.0 - Ready for Implementation*