initial commit for beadboard

2026-02-16 21:45:27 -08:00 · 2026-02-16 21:45:27 -08:00 · 54729c72f6
commit 54729c72f6
parent 93f3c50d4b
14 changed files with 1472 additions and 2108 deletions
--- a/docs/plans/2026-02-15-unified-ux-prd.md
+++ b/docs/plans/2026-02-15-unified-ux-prd.md
@ -1,26 +1,34 @@
 # Unified UX PRD - Swimlane Social Hub

-> **Version**: 1.1  
+> **Version**: 2.0  
 > **Date**: 2026-02-16  
-> **Status**: Updated - Activity View + Thread Drawer added
-> **Supersedes**: bb-u6f.7 (Unified Cross-Surface Navigation)
+> **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 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
+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 3 views:
- **Social** - Task activity feed with blocks/unlocks
- **Graph** - Dependency visualization
- **Swarm** - Team health dashboard
+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.

 ---

@ -28,230 +36,339 @@ Single unified shell at `/` with 3 views:

 | # | Decision | Choice | Rationale |
 |---|----------|--------|-----------|
-| 1 | Routing | Single page at `/` with client tabs | Preserves selection state |
-| 2 | Views | 4 tabs: Social, Graph, Swarm, Activity | Activity replaces old /timeline |
-| 3 | Right Panel | Activity Feed + Agent roster (top 30%) | Persistent sidebar, always shows timeline |
-| 4 | Thread Drawer | Opens when clicking a card | Slides from right edge of middle area |
-| 5 | Detail pattern | Right sidebar (desktop), drawer (mobile) | Best use of screens |
-| 6 | Visual style | shadcn/ui + earthy-dark tokens | Replace Aero Chrome |
-| 7 | Tailwind | Stay on v3, use shadcn/ui patterns | v4 has migration risks |
-| 8 | Old pages | Copy page.tsx to page-old.tsx | Safe rollback |
-| 9 | Card pattern | Same base for Social and Swarm | Reusable components |
-| 10 | Threads | In thread drawer, not right panel | Separates conversation from activity |
-| 11 | Agent presence | Embedded in swarm cards + right panel top | Supervisors can see all agents |
-| 12 | Swarm sorting | Health (default), Activity, Progress | Auto-surface attention |
-| 13 | Mobile nav | 4 bottom tabs (Social, Graph, Swarm, Activity) | Matches desktop view selector |
+| 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 |

 ---

-## Skills Required (Non-Negotiable)
+## Design Token Specification

-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
+### 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

 ---

-## Design System Specification
+## Component Anatomy

-### Color Palette (Earthy-Dark)
+### Social Feed Card

-Backgrounds:
- --color-bg-base: #2D2D2D
- --color-bg-card: #363636
- --color-bg-input: #404040
+```
+┌─────────────────────────────────────┐
+│ [⊕]                           (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
+└─────────────────────────────────────┘
+```

-Accents:
- --color-accent-green: #7CB97A (primary CTA)
- --color-accent-amber: #D4A574 (warning)
- --color-accent-teal: #5BA8A0 (secondary)
+**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%)

-Text:
- --color-text-primary: #FFFFFF
- --color-text-secondary: #B8B8B8
- --color-text-muted: #888888
+**Blocks/Unlocks Pattern (reuse from task-card-grid.tsx):**
+```tsx
+// Container
+rounded-lg p-2 border border-white/5

-Status:
- ready: teal #5BA8A0
- in_progress: green #7CB97A
- blocked: amber #D4A574
- closed: muted #888888
+// "Unlocks" header (rose tint)
+text-[9px] font-bold uppercase tracking-widest text-rose-400/80
+bg-rose-500/10  // background tint

-Liveness:
- active: #7CB97A
- stale: #D4A574
- stuck: #E57373
- dead: #9E4244
+// "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: 3rem fixed
- LEFT: 13rem (channel tree)
- MIDDLE: flex-1 (card grid)
- RIGHT: 17rem (Activity Feed + Agent roster)
- THREAD DRAWER: 24rem (slides from right edge of middle area, appears on card selection)
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ 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 Panel | Middle | Right Panel (Activity) | Thread Drawer |
-|------|------------|--------|----------------------|---------------|
-| Desktop (≥1024px) | 13rem fixed | flex-1 | 17rem fixed, always visible | 24rem slides in |
-| Tablet (768-1024px) | Collapsed, toggle | flex-1 | Slide-over, toggle | Slide-over drawer |
-| Mobile (<768px) | Hidden | flex-1 | Bottom tab | Full-screen bottom sheet |

-### Mobile Navigation (Bottom Tabs)
- Tab 1: Social
- Tab 2: Graph
- Tab 3: Swarm
- Tab 4: Activity (shows timeline/agent view)
-
-### URL State
- view: social | graph | swarm | activity
- task: selected task ID
- swarm: selected swarm ID
- agent: selected agent ID (for activity panel filtering)
- panel: open | closed (right panel)
- drawer: open | closed (thread drawer)
+| 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 |

 ---

-## View Specifications
+## Anti-Patterns (Forbidden)

-### 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
-
-### Activity View
-Replaces /timeline. Shows:
- Top 30%: Agent roster with status (active/stale/stuck/dead)
- Bottom: Chronological activity feed (status changes, comments, events)
- Real-time updates via SSE
-
-**Deep Linking from Cards:**
- Click agent icon on any card → Activity panel filters to that agent
- URL: `/?view=activity&agent=bb-xyz` shows agent's activity
- Click graph icon on card → `/?view=graph&task=bb-xyz`
- Click kanban icon on card → `/?view=social&task=bb-xyz`
-
-**Right Panel Behavior:**
- No selection: Shows ALL active agents + ALL activity
- Agent selected: Shows that agent's roster + their specific activity
- Easy "show all" button to clear agent filter
-
-### Thread Drawer
-When clicking a card (Social or Swarm), opens drawer showing:
- Task/Swarm header with ID and title
- Full thread of comments and events
- Compose area for adding comments
- Close button (X)
+- 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)

 ---

-## Dependency Graph (Bead Flow)
+## Recommended Bead Structure

-PHASE 0: Design Foundation
-[0.1] Token System
-[0.2] shadcn/ui Setup
-[0.3] Base Primitives
+### Phase 0: Design Foundation
+**Goal:** Tokens + Primitives only. No views.

-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]
-[1.7] Resizable Panels <- [1.2-1.6]
+**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

-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]
+**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)

-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]
+**bb-ui2.3a** - Agent Avatar Primitive  
+- Avatar with role-colored ring
+- ZFC state indicator (dot/pulse/glow)
+- Size variants (sm, md, lg)

-PHASE 4: Activity View (NEW)
-[4.1] Activity Data Builder <- [0.3]
-[4.2] ActivityPanel Component <- [1.5][4.1]
-[4.3] Agent Deep Linking <- [4.2][2.2][3.2]
-[4.4] Thread Drawer <- [2.4]
-[4.5] Mobile Nav 4-tabs <- [1.6][4.2]
+**bb-ui2.4a** - Status Utilities Update  
+- Rewrite status-utils.tsx for new tokens
+- Status badge component with pill + dot
+- Liveness indicator component

-PHASE 5: Graph Migration
-[5.1] Graph Component Extraction
-[5.2] Graph Tab Integration <- [1.2][5.1]
-[5.3] fitView Fix <- [5.2]
+### Phase 1: Layout Polish
+**Goal:** Fix current layout issues, preserve structure

-PHASE 6: Polish
-[6.1] Deep Link Verification <- [all above]
-[6.2] Mobile Responsive Polish
-[6.3] Screenshot Evidence
-[6.4] Final Quality Gates
+**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 Gates (Required)
+## Verification Strategy

-Every bead MUST pass before closing:
- npm run typecheck
- npm run lint
- npm run test
- Screenshots for UI changes
+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

 ---

-## 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*
+*End of PRD v2.0 - Ready for Implementation*
--- a/docs/plans/2026-02-16-social-view-redesign-plan.md
+++ b/docs/plans/2026-02-16-social-view-redesign-plan.md
@ -0,0 +1,287 @@
+# Implementation Plan: Social View Redesign Phase 1
+
+## Overview
+
+Complete redesign of the Social View in BeadBoard to create a modern card-based interface inspired by Asana + Facebook + Slack. This phase focuses on the Social view only, implementing a responsive grid layout with full blocks/unlocks display and a detail strip that slides up from below the cards on desktop.
+
+## Implementation Status
+
+> **Updated: 2026-02-16**
+> 
+> **Phase 0 (Design Foundation) Status:**
+> - ✅ bb-ui2.1 (Design Tokens) - COMPLETED
+>   - Added complete earthy-dark token system in globals.css
+>   - Added legacy compatibility tokens for backward compatibility with existing Aero Chrome components
+> - ⏳ bb-ui2.2 (Semantic Rename) - PENDING (blocked by tokens)
+> - ⏳ bb-ui2.3 (Base Card Component) - PENDING (blocked by tokens)
+
+**Note:** The legacy Aero Chrome classes (.workflow-card, .glass-panel, .ui-field, etc.) are preserved in globals.css for backward compatibility with existing components that haven't been refactored yet. New components should use the earthy-dark design tokens. This is intentional - gradual migration rather than big-bang rewrite.
+
+## Scope
+
+- **Phase 1 only**: Social View redesign
+- **Not included**: Swarm view, Graph view, Timeline (future phases)
+- **Target**: 4-column responsive grid (desktop), detail strip positioning, full card content
+
+## Types
+
+### Data Types (No changes needed - already exists)
+
+```typescript
+// Already in src/lib/types.ts
+type BeadStatus = 'open' | 'in_progress' | 'blocked' | 'deferred' | 'closed' | 'tombstone' | 'pinned' | 'hooked';
+type BeadDependencyType = 'blocks' | 'parent' | 'relates_to' | 'duplicates' | 'supersedes' | 'replies_to';
+```
+
+### New/Modified Types
+
+```typescript
+// In src/lib/social-cards.ts - rename fields for semantic clarity
+interface SocialCard {
+  id: string;
+  title: string;
+  status: SocialCardStatus;
+  blocks: string[];        // renamed from 'unlocks' - tasks THIS task blocks (amber)
+  unblocks: string[];      // renamed from 'blocks' - tasks blocking THIS task (rose)
+  agents: AgentInfo[];
+  lastActivity: Date;
+  priority: SocialCardPriority;
+}
+```
+
+### Component Props
+
+```typescript
+// SocialCardProps - enhanced with full blocks/unlocks display
+interface SocialCardProps {
+  data: SocialCard;
+  className?: string;
+  selected?: boolean;
+  onClick?: () => void;
+  onJumpToGraph?: (id: string) => void;
+  onJumpToKanban?: (id: string) => void;
+}
+
+// SocialPageProps - already adequate, no changes needed
+interface SocialPageProps {
+  issues: BeadIssue[];
+  selectedId?: string;
+  onSelect: (id: string) => void;
+}
+```
+
+## Files
+
+### Files to Modify
+
+| File | Changes |
+|------|---------|
+| `src/app/globals.css` | Add complete earthy-dark token system from PRD |
+| `src/lib/social-cards.ts` | Rename `unlocks`→`blocks`, `blocks`→`unblocks`, add full detail data |
+| `src/components/social/social-card.tsx` | Complete redesign with full blocks/unlocks display |
+| `src/components/social/social-page.tsx` | Responsive grid (4→2→1), detail strip integration |
+| `src/components/shared/base-card.tsx` | Status borders, 10px radius |
+| `src/components/shared/agent-avatar.tsx` | Role-colored borders, ZFC state indicators |
+| `src/components/shared/unified-shell.tsx` | Detail strip positioning (below cards on desktop) |
+
+### Files to Create
+
+| File | Purpose |
+|------|---------|
+| `src/components/social/detail-strip.tsx` | New component for conversation/detail panel |
+
+### Reference Files (Read Only)
+
+| File | Purpose |
+|------|---------|
+| `src/components/graph/task-card-grid.tsx` | Blocks/unlocks display pattern (lines 227-330) |
+| `src/components/shared/thread-drawer.tsx` | Current drawer implementation to replace |
+
+## Functions
+
+### Modified Functions
+
+| Function | File | Changes |
+|----------|------|---------|
+| `buildSocialCards()` | `src/lib/social-cards.ts` | Swap `unlocks`/`blocks` field names, populate full detail |
+| `SocialCard` component | `src/components/social/social-card.tsx` | Complete redesign with blocks/unlocks sections |
+| `SocialPage` component | `src/components/social/social-page.tsx` | Responsive grid, detail strip positioning |
+| `BaseCard` component | `src/components/shared/base-card.tsx` | Status-colored borders, radius |
+| `AgentAvatar` component | `src/components/shared/agent-avatar.tsx` | Role-colored ring, ZFC states |
+
+### New Functions
+
+| Function | File | Purpose |
+|----------|------|---------|
+| `DetailStrip` component | `src/components/social/detail-strip.tsx` | Conversation panel that slides up |
+
+## Classes
+
+### No new classes required
+
+Using functional React components with hooks.
+
+## Dependencies
+
+### Existing Dependencies (Already in project)
+
+- `react`, `react-dom` - UI framework
+- `@radix-ui/react-avatar` - Avatar primitive
+- `lucide-react` - Icons
+- `clsx`, `tailwind-merge` - Class utilities
+- `tailwindcss-animate` - Animations
+
+### No new dependencies needed
+
+All functionality achievable with existing dependencies.
+
+## Testing
+
+### Test Strategy
+
+1. **Visual regression**: Compare screenshots before/after
+2. **Responsive testing**: Verify 4→2→1 column layout
+3. **Interaction testing**: Card selection, detail strip behavior
+4. **Type safety**: Ensure TypeScript compiles without errors
+
+### Test Files to Check
+
+```bash
+npm run typecheck
+npm run lint  
+npm run test
+```
+
+## Implementation Order
+
+### Step 1: Design Tokens (bb-ui2.1)
+- Update `globals.css` with complete earthy-dark token system
+- Add missing: agent role colors, liveness colors, radii, shadows
+- Verify tokens match PRD exactly
+
+### Step 2: Semantic Rename (bb-ui2.2)
+- Rename fields in `social-cards.ts`: `unlocks`→`blocks`, `blocks`→`unblocks`
+- Update all consumers of these fields
+- Run typecheck to verify
+
+### Step 3: Base Card Component (bb-ui2.3)
+- Modify `BaseCard` with:
+  - Status-colored 1px borders
+  - 10px radius (`--radius-card: 0.625rem`)
+  - #363636 background
+
+### Step 4: Agent Avatar Enhancement (bb-ui2.4)
+- Add role-colored left border ring
+- Implement ZFC state indicators:
+  - working: pulsing green glow
+  - stuck: attention amber dot
+  - dead: warning red
+
+### Step 5: SocialCard Redesign (bb-ui2.5)
+- Full card anatomy:
+  - Task ID (teal, tiny)
+  - Title (bold, white)
+  - BLOCKS section (rose tint): tasks blocking ME
+  - UNBLOCKS section (amber tint): tasks I block
+  - Agent avatars (prominent, role-colored)
+  - Last message preview
+  - View-jump icons
+- Reuse blocks/unlocks pattern from task-card-grid.tsx
+
+### Step 6: Responsive Grid Layout (bb-ui2.6)
+- Update `SocialPage` grid:
+  - Desktop (≥1024px): 4 columns
+  - Tablet (768-1023px): 2 columns
+  - Mobile (<768px): 1 column
+- Use CSS Grid with `minmax()` for responsiveness
+
+### Step 7: Detail Strip Positioning (bb-ui2.7)
+- Create new `DetailStrip` component
+- Desktop: Slides UP from below the card grid (not bottom of page)
+- Mobile: Full-screen overlay
+- Connect to URL state for selected task
+
+### Step 8: Verification (bb-ui2.8)
+- Run typecheck, lint, test
+- Capture screenshots at all breakpoints
+- Verify visual improvements match PRD
+
+## Bead Structure
+
+```
+bb-ui2.1  → Design Tokens Update
+bb-ui2.2  → Semantic Rename (unlocks↔blocks)
+bb-ui2.3  → Base Card Component
+bb-ui2.4  → Agent Avatar Enhancement
+bb-ui2.5  → SocialCard Redesign
+bb-ui2.6  → Responsive Grid Layout
+bb-ui2.7  → Detail Strip Positioning
+bb-ui2.8  → Verification + Screenshots
+```
+
+## Dependencies Between Beads
+
+```
+bb-ui2.1 (tokens)
+    ↓
+bb-ui2.2 (semantic rename) → bb-ui2.1
+    ↓
+bb-ui2.3 (base card) → bb-ui2.1
+    ↓
+bb-ui2.4 (avatar) → bb-ui2.3
+    ↓
+bb-ui2.5 (card redesign) → bb-ui2.2, bb-ui2.3, bb-ui2.4
+    ↓
+bb-ui2.6 (grid) → bb-ui2.5
+    ↓
+bb-ui2.7 (detail strip) → bb-ui2.5, bb-ui2.6
+    ↓
+bb-ui2.8 (verification) → bb-ui2.6, bb-ui2.7
+```
+
+## Key Design Details from PRD
+
+### Blocks/Unlocks Color Mapping
+
+| Relationship | Color | Tailwind |
+|--------------|-------|----------|
+| Tasks blocking ME (unblocks) | Rose tint | bg-rose-500/10, text-rose-400/80 |
+| Tasks I block (blocks) | Amber tint | bg-amber-500/10, text-amber-400/80 |
+
+### Status Colors
+
+| Status | Color | Tailwind |
+|--------|-------|----------|
+| open/ready | Teal | #5BA8A0 |
+| in_progress | Green | #7CB97A |
+| blocked | Amber | #D4A574 |
+| closed | Muted | #888888 |
+
+### Agent Role Colors
+
+| Role | Color |
+|------|-------|
+| ui | #6B9BD2 (steel blue) |
+| graph | #7CB97A (green) |
+| orchestrator | #B08ED6 (soft purple) |
+| agent | #B8B8B8 (neutral) |
+| researcher | #D4A574 (amber) |
+
+### Card Specs
+
+- Background: #363636
+- Border: 1px status-colored
+- Border-radius: 10px
+- Padding: 1rem-1.25rem
+
+### ZFC State Visuals
+
+| State | Visual |
+|-------|--------|
+| idle | #888888 static dot |
+| spawning | #5BA8A0 pulsing dot |
+| running | #7CB97A animated dot |
+| working | #7CB97A pulsing glow |
+| stuck | #D4A574 attention dot |
+| done | #7CB97A check |
+| dead | #C97A7A warning |