docs+skills: add main UI/UX visual-truth PRD and skill links

docs/plans/2026-02-18-main-ui-ux-visual-truth-prd.md

@@ -0,0 +1,240 @@
+# Main UI/UX Visual-Truth PRD
+
+## Document Control
+- Date: 2026-02-18
+- Owner: Product + UI Engineering
+- Status: Approved for implementation
+- Primary route: `src/app/page.tsx`
+- Design truth references:
+  - Reference A: Command Grid shell (blocked/new-task top actions)
+  - Reference B: Open Thread center takeover (conversation detail state)
+
+## 1. Product Intent
+Deliver a full redesign of the main BeadBoard experience so the live application visually and behaviorally matches the approved references while preserving existing backend workflows.
+
+This is not a cosmetic patch. The shell, state model, and interaction hierarchy are being redefined.
+
+## 2. Goals
+1. Replace current green-card Social presentation with the new command-grid visual language.
+2. Add Open Thread as a center takeover state (not right drawer-first).
+3. Keep backend behavior, URL deep links, and mutation endpoints working.
+4. Unify Social, Graph, and Swarm under one shell and token system.
+5. Make both sidebars independently collapsible with persistent state.
+
+## 3. Non-Goals
+1. No backend schema migrations.
+2. No changes to core issue/dependency semantics.
+3. No new authentication or role systems.
+4. No `/sessions` redesign (route is deprecated and redirected).
+
+## 4. Users and Jobs-to-be-Done
+### Primary User
+- Technical operator managing active work and blockers in real time.
+
+### Core Jobs
+1. See blocked/high-priority work immediately.
+2. Open a task and communicate/update status without leaving context.
+3. Navigate between Social, Graph, and Swarm quickly.
+4. Collapse side rails to focus when needed.
+
+## 5. Experience Principles
+1. Action first: top chrome should drive action, not telemetry overload.
+2. Visual hierarchy over density: each region has one clear job.
+3. State clarity: user always knows whether they are in Grid or Thread mode.
+4. Consistent symbols: one icon system for view switching + card jump actions.
+5. Fast and keyboard reachable: primary actions should be obvious and accessible.
+
+## 6. Information Architecture
+### Global Layout (Desktop)
+- Left Sidebar: view switch icons + workstream tree + global scope controls.
+- Center: either Command Grid or Open Thread takeover.
+- Right Sidebar: agent pool + telemetry/activity context.
+- Top Bar: minimal, action-first.
+
+### Mobile Layout
+- Dedicated mobile composition (not scaled desktop).
+- Bottom nav for view switching.
+- Open Thread is full-screen takeover with safe-area padding.
+
+## 7. State Model
+### Primary States
+1. `command_grid`
+- Shows top-level task stream/cards.
+- Shows summary counts in center header.
+
+2. `open_thread`
+- Center takeover with task summary + conversation timeline + message input.
+- Right sidebar may collapse/minimize depending on viewport.
+
+### URL Contract
+Maintain existing params and add sidebar params:
+- Existing: `view`, `task`, `swarm`, `drawer`, `graphTab`, `panel`, `epic`
+- New: `left=open|closed`, `right=open|closed`
+
+Persistence precedence:
+1. URL (source of truth)
+2. Local storage fallback (when URL missing)
+3. Default layout values
+
+## 8. Surface Requirements
+
+### 8.1 Top Bar (Action-First)
+Required content:
+1. Brand/scope label.
+2. `Blocked Items` action.
+3. `New Task` action.
+
+Not in top bar:
+1. Agent pool status blocks.
+2. Large telemetry stat tiles.
+3. Secondary controls that can live in sidebars.
+
+Behavior:
+1. `Blocked Items` toggles blocked-focused filtering in center and URL.
+2. `New Task` opens create flow using existing beads mutation path.
+
+### 8.2 Left Sidebar
+Required:
+1. View switcher icons at top (`Social`, `Graph`, `Swarm`).
+2. Workstream/epic navigation below.
+3. Collapse toggle.
+
+Rules:
+1. Icons match card jump icon language.
+2. Keyboard focus visible and logical tab order.
+3. Collapsed mode keeps view switch accessible.
+
+### 8.3 Center: Command Grid
+Required:
+1. Header with title/subtitle and summary counts.
+2. Grid/list of task cards with strong status hierarchy.
+3. Strong visibility for blocked and in-progress items.
+
+Card actions:
+1. Jump to graph for task context.
+2. Jump to activity/timeline context.
+3. Open thread (enters takeover state).
+
+### 8.4 Center: Open Thread Takeover
+Required regions:
+1. Task identity/status header.
+2. Task summary + assignee + due date metadata.
+3. Chronological conversation timeline.
+4. Composer row with message input + send action.
+
+Behavior:
+1. Escape/close returns to prior command-grid selection context.
+2. Existing edit/comment/status update flows continue to use current APIs.
+3. Unsaved edits require warning before destructive navigation.
+
+### 8.5 Right Sidebar
+Required:
+1. Agent pool monitor list.
+2. Activity/telemetry feed.
+3. Collapse toggle.
+
+Rules:
+1. Right sidebar is context rail, not primary action area.
+2. In thread takeover on smaller screens, it may minimize/collapse.
+
+### 8.6 Graph and Swarm Views
+Required:
+1. Full visual reskin using same token system and shell language.
+2. Keep existing graph/swarm behavior and deep links.
+3. Keep consistent icon/action vocabulary.
+
+## 9. Design Token Contract (Locked)
+All main-route UI must use tokenized values. No ad-hoc one-off hex values in component files.
+
+### Required Tokens
+- Background: `--ui-bg-app`, `--ui-bg-shell`, `--ui-bg-panel`, `--ui-bg-card`
+- Border/Text: `--ui-border-soft`, `--ui-border-strong`, `--ui-text-primary`, `--ui-text-muted`
+- Status/Action: `--ui-accent-ready`, `--ui-accent-blocked`, `--ui-accent-warning`, `--ui-accent-info`, `--ui-accent-action-green`, `--ui-accent-action-red`
+- Typography: `--ui-font-sans`, `--ui-font-mono`, `--ui-tracking-tight`, `--ui-numeric-tabular`
+
+Color policy:
+- Match reference palette closely.
+- Permit small WCAG contrast adjustments where needed.
+
+## 10. Copy and Label Rules
+Use plain operational language.
+
+Approved examples:
+- `Blocked Items`
+- `New Task`
+- `Open Thread`
+- `No activity yet`
+
+Avoid marketing-style labels and ambiguous verbs.
+
+## 11. Accessibility Requirements (Must Pass)
+1. Icon-only buttons include `aria-label`.
+2. No clickable `div/span` for action controls.
+3. All interactive controls have visible `:focus-visible` state.
+4. Form controls have labels and sensible autocomplete behavior.
+5. Async updates use polite live regions when applicable.
+6. Keyboard support for sidebar toggles, view switching, composer actions.
+7. Preserve semantic headings and logical region order.
+
+## 12. Performance Requirements
+1. No layout-thrashing reads in render.
+2. Avoid `transition: all`; transition only explicit properties.
+3. Keep card rendering cheap; memoize derived lists where needed.
+4. Keep thread rendering stable under high event volume.
+5. Preserve responsive behavior without JS measurement hacks.
+
+## 13. Route Policy
+- `/sessions` is deprecated.
+- Required behavior: hard redirect `/sessions` to `/?view=social`.
+- Remove active nav entry points to `/sessions`.
+
+## 14. Acceptance Criteria
+Design acceptance:
+1. Desktop and mobile visually match references by region and hierarchy.
+2. Command Grid and Open Thread states are both implemented.
+3. Sidebars independently collapse and persist state.
+
+Behavior acceptance:
+1. URL state round-trip works for selection/view/layout state.
+2. `Blocked Items` and `New Task` are functional.
+3. Graph/Swarm remain behaviorally correct after reskin.
+4. Existing mutation paths still work.
+
+Quality gates:
+1. `npm run typecheck`
+2. `npm run lint`
+3. `npm run test`
+4. Vercel guideline audit output per phase (`file:line`, terse findings)
+
+## 15. Verification Matrix
+### Screenshot checkpoints
+- `1920x1080`
+- `1440x1024`
+- `390x844`
+
+### Flow checks
+1. Open grid -> filter blocked -> open thread -> send message -> close thread -> restore context.
+2. Switch Social/Graph/Swarm from left icon rail.
+3. Collapse/expand each sidebar independently.
+4. Reload with URL params and verify exact state restoration.
+
+## 16. Risks and Mitigations
+1. Risk: token updates leak to unrelated routes.
+- Mitigation: scope tokens/class application to main shell first, then promote intentionally.
+
+2. Risk: URL state regressions break deep links.
+- Mitigation: add targeted URL parsing/building tests before refactor.
+
+3. Risk: visual drift during incremental implementation.
+- Mitigation: enforce screenshot checkpoints each phase.
+
+4. Risk: stale runtime lock artifacts pollute git status.
+- Mitigation: keep runtime lock files ignored and untracked.
+
+## 17. Delivery Phases
+1. Shell V2 + collapsible sidebars + URL state foundation.
+2. Command Grid visual truth implementation.
+3. Open Thread center takeover implementation.
+4. Graph/Swarm full reskin.
+5. `/sessions` hard redirect.
+6. Final gates + audit and handoff.