@sugar-crash-studios/vibe-forge 0.4.0

package/docs/wireframes/dashboard-mvp.md

@@ -0,0 +1,1164 @@
+# Dashboard MVP - Wireframes and UX Specification
+
+**Created by:** Pixel (UX Designer)
+**Date:** 2026-01-16
+**Version:** 1.0
+**Status:** Final
+
+---
+
+## Table of Contents
+
+1. [User Stories](#user-stories)
+2. [Design Principles](#design-principles)
+3. [Main Dashboard Wireframe](#main-dashboard-wireframe)
+4. [Component Specifications](#component-specifications)
+5. [Interaction Flows](#interaction-flows)
+6. [State Documentation](#state-documentation)
+7. [Actionable Items UX](#actionable-items-ux---the-killer-feature)
+8. [Dark Mode Specification](#dark-mode-specification)
+9. [Accessibility](#accessibility)
+10. [Responsive Design](#responsive-design)
+11. [Keyboard Shortcuts](#keyboard-shortcuts)
+
+---
+
+## User Stories
+
+### Primary User: The Developer
+
+**Morning Check-in Flow:**
+> "As a developer starting my day, I open the dashboard and within 3 seconds I know exactly what needs my attention. No cognitive overload, just clarity."
+
+**Dispatch Flow:**
+> "As a developer, I see a stale documentation warning. One click on 'Dispatch Scribe' and the task is created. I watch the agent pick it up and start working. Satisfying."
+
+**Monitor Progress Flow:**
+> "As a developer, I glance at the agents panel and see Anvil is working on my frontend task. The status updates in real-time. I feel informed without having to context-switch."
+
+---
+
+## Design Principles
+
+1. **Progressive Disclosure** - Summary first, details on demand
+2. **Immediate Feedback** - Every action confirms within 100ms
+3. **Error Prevention** - Dangerous actions require confirmation
+4. **Accessibility First** - WCAG 2.1 AA, keyboard nav, screen reader support
+5. **Mobile Responsive** - Check status from anywhere
+
+---
+
+## Main Dashboard Wireframe
+
+### Desktop Layout (1200px+)
+
+```
++-----------------------------------------------------------------------------------+
+|                                                                                   |
+|  VIBE FORGE DASHBOARD                                    [Settings]  [Dark/Light] |
+|                                                                                   |
++-----------------------------------------------------------------------------------+
+|                                                                                   |
+|  +-------------------------+  +-------------------------+  +---------------------+|
+|  |                         |  |                         |  |                     ||
+|  |  TASKS                  |  |  AGENTS                 |  |  NOTIFICATIONS      ||
+|  |                         |  |                         |  |                     ||
+|  |  [Pending] [Progress]   |  |                         |  |  Today              ||
+|  |  [Review]  [Done]       |  |  +-------------------+  |  |                     ||
+|  |                         |  |  | [*] Planning Hub  |  |  |  [!] Task completed ||
+|  |  +-------------------+  |  |  |     idle          |  |  |      TASK-042       ||
+|  |  | TASK-042          |  |  |  +-------------------+  |  |      2 min ago      ||
+|  |  | Fix login bug     |  |  |                         |  |                     ||
+|  |  | @anvil | urgent   |  |  |  +-------------------+  |  |  [i] PR merged      ||
+|  |  +-------------------+  |  |  | [*] Anvil         |  |  |      #127           ||
+|  |                         |  |  |     working       |  |  |      15 min ago     ||
+|  |  +-------------------+  |  |  |     TASK-041      |  |  |                     ||
+|  |  | TASK-041          |  |  |  +-------------------+  |  |  [!] Attention      ||
+|  |  | Dashboard UI      |  |  |                         |  |      TASK-039       ||
+|  |  | @anvil | high     |  |  |  +-------------------+  |  |      1 hour ago     ||
+|  |  +-------------------+  |  |  | [*] Furnace       |  |  |                     ||
+|  |                         |  |  |     idle          |  |  |  Yesterday          ||
+|  |  +-------------------+  |  |  +-------------------+  |  |                     ||
+|  |  | TASK-040          |  |  |                         |  |  [i] Deploy success ||
+|  |  | API endpoints     |  |  |  +-------------------+  |  |      v1.2.0         ||
+|  |  | @furnace | medium |  |  |  | [*] Crucible      |  |  |                     ||
+|  |  +-------------------+  |  |  |     idle          |  |  +---------------------+|
+|  |                         |  |  +-------------------+  |                         |
+|  +-------------------------+  +-------------------------+                         |
+|                                                                                   |
+|  +-------------------------------------------------------------------------------+|
+|  |                                                                               ||
+|  |  ISSUES (Actionable)                                               [Refresh] ||
+|  |                                                                               ||
+|  |  +-------------------------------------------------------------------------+  ||
+|  |  | [DOC] Stale Docs: README.md                                             |  ||
+|  |  |       Last updated 45 days ago                    [Dispatch Scribe >>]  |  ||
+|  |  +-------------------------------------------------------------------------+  ||
+|  |                                                                               ||
+|  |  +-------------------------------------------------------------------------+  ||
+|  |  | [TEST] Failing Test: auth.test.js                                       |  ||
+|  |  |        2 tests failing since yesterday            [Dispatch Crucible >>]|  ||
+|  |  +-------------------------------------------------------------------------+  ||
+|  |                                                                               ||
+|  |  +-------------------------------------------------------------------------+  ||
+|  |  | [SEC] Security: lodash vulnerability                                    |  ||
+|  |  |       CVE-2021-23337 (high severity)              [Dispatch Aegis >>]   |  ||
+|  |  +-------------------------------------------------------------------------+  ||
+|  |                                                                               ||
+|  |  +-------------------------------------------------------------------------+  ||
+|  |  | [COV] Low Coverage: utils.js                                            |  ||
+|  |  |       34% coverage (threshold: 80%)               [Dispatch Crucible >>]|  ||
+|  |  +-------------------------------------------------------------------------+  ||
+|  |                                                                               ||
+|  +-------------------------------------------------------------------------------+|
+|                                                                                   |
++-----------------------------------------------------------------------------------+
+|  Connected | Last updated: just now                          Vibe Forge v0.1.0   |
++-----------------------------------------------------------------------------------+
+```
+
+### Panel Proportions (Desktop)
+
+- **Header:** 60px fixed
+- **Main Content Area:** Remaining height, min-height 600px
+- **Top Row (Tasks, Agents, Notifications):** 60% of content area
+  - Tasks Panel: 40% width
+  - Agents Panel: 30% width
+  - Notifications Panel: 30% width
+- **Bottom Row (Issues):** 40% of content area, full width
+- **Footer:** 32px fixed
+
+---
+
+## Component Specifications
+
+### 1. Header Component
+
+```
++-----------------------------------------------------------------------------------+
+|                                                                                   |
+|  [Logo] VIBE FORGE DASHBOARD                             [Settings]  [Dark/Light] |
+|                                                                                   |
++-----------------------------------------------------------------------------------+
+```
+
+**Elements:**
+- **Logo:** 24x24px icon + text, clickable (refreshes dashboard)
+- **Title:** "VIBE FORGE DASHBOARD" - font-size: 18px, font-weight: 600
+- **Settings Button:** Gear icon, opens settings modal
+- **Theme Toggle:** Sun/Moon icon, instant switch with 200ms transition
+
+**Behavior:**
+- Logo click: Refresh all panels
+- Settings: Opens modal with port config, auto-refresh interval, notification preferences
+- Theme: Toggle between light and dark mode, persisted in localStorage
+
+---
+
+### 2. Tasks Panel
+
+```
++---------------------------+
+|                           |
+|  TASKS                    |
+|                           |
+|  [Pending] [Progress]     |
+|  [Review]  [Done]         |
+|                           |
+|  +---------------------+  |
+|  | [Priority] TASK-042 |  |
+|  | Fix login bug       |  |
+|  | @anvil | 2h ago     |  |
+|  +---------------------+  |
+|                           |
+|  +---------------------+  |
+|  | [Priority] TASK-041 |  |
+|  | Dashboard UI        |  |
+|  | @anvil | 5h ago     |  |
+|  +---------------------+  |
+|                           |
++---------------------------+
+```
+
+**Filter Tabs:**
+- Pending (default selected)
+- In Progress
+- In Review
+- Done (last 24h only)
+
+**Task Card Elements:**
+- Priority indicator (colored dot: red=critical, orange=high, yellow=medium, blue=low)
+- Task ID (monospace font)
+- Task title (truncate at 30 chars with ellipsis)
+- Assigned agent badge
+- Time since last update
+
+**Interactions:**
+- Click card: Expand inline to show full details + actions
+- Hover: Subtle highlight (2px elevation change)
+- Filter tab click: Filter tasks, update count badges
+
+---
+
+### 3. Agents Panel
+
+```
++-------------------------+
+|                         |
+|  AGENTS                 |
+|                         |
+|  +-------------------+  |
+|  | [Avatar] Hub      |  |
+|  | Status: idle      |  |
+|  | Ready for work    |  |
+|  +-------------------+  |
+|                         |
+|  +-------------------+  |
+|  | [Avatar] Anvil    |  |
+|  | Status: working   |  |
+|  | TASK-041          |  |
+|  | [-----=====>    ] |  |
+|  +-------------------+  |
+|                         |
+|  +-------------------+  |
+|  | [Avatar] Furnace  |  |
+|  | Status: idle      |  |
+|  | Ready for work    |  |
+|  +-------------------+  |
+|                         |
++-------------------------+
+```
+
+**Agent Status Types:**
+| Status | Color | Icon | Description |
+|--------|-------|------|-------------|
+| idle | Green | Circle | Ready for work |
+| working | Blue | Spinning | Currently on a task |
+| blocked | Yellow | Warning | Waiting on something |
+| error | Red | X | Needs attention |
+| offline | Gray | Dash | Not connected |
+
+**Agent Card Elements:**
+- Avatar: Colored circle with first letter of agent name
+- Agent name
+- Status badge with color
+- Current task (if working)
+- Progress bar (if available)
+
+**Interactions:**
+- Hover: Show full agent details in tooltip (specialty, last 3 tasks)
+- Click: Expand to show task history, assign task option
+
+---
+
+### 4. Notifications Panel
+
+```
++---------------------+
+|                     |
+|  NOTIFICATIONS      |
+|                     |
+|  Today              |
+|                     |
+|  [!] Task completed |
+|      TASK-042       |
+|      2 min ago      |
+|            [Dismiss]|
+|                     |
+|  [i] PR merged      |
+|      #127           |
+|      15 min ago     |
+|            [Dismiss]|
+|                     |
+|  [!] Attention      |
+|      TASK-039       |
+|      needs review   |
+|  [View] [Dispatch]  |
+|                     |
++---------------------+
+```
+
+**Notification Types:**
+| Type | Icon | Color | Sound |
+|------|------|-------|-------|
+| success | Checkmark | Green | Optional chime |
+| info | Info circle | Blue | None |
+| warning | Warning | Yellow | None |
+| attention | Bell | Orange | Optional ping |
+| error | X circle | Red | Alert sound |
+
+**Notification Elements:**
+- Type icon (color-coded)
+- Title
+- Description (max 2 lines)
+- Timestamp (relative: "2 min ago", "Yesterday")
+- Action buttons (contextual)
+
+**Interactions:**
+- Dismiss: Remove single notification
+- View: Navigate to related task
+- Dispatch: Open dispatch flow for actionable notifications
+
+---
+
+### 5. Issues Panel (The Killer Feature)
+
+```
++-------------------------------------------------------------------------------+
+|                                                                               |
+|  ISSUES (Actionable)                                    [Refresh] [Collapse]  |
+|                                                                               |
+|  +-------------------------------------------------------------------------+  |
+|  | [DOC]  Stale Docs: README.md                                            |  |
+|  |        Last updated 45 days ago                                         |  |
+|  |        Threshold: 30 days | Severity: Medium                            |  |
+|  |                                                      [Dispatch Scribe]  |  |
+|  +-------------------------------------------------------------------------+  |
+|                                                                               |
+|  +-------------------------------------------------------------------------+  |
+|  | [TEST] Failing Test: auth.test.js                                       |  |
+|  |        2 tests failing: testLogin, testLogout                           |  |
+|  |        First failed: yesterday 3:45 PM                                  |  |
+|  |                                                    [Dispatch Crucible]  |  |
+|  +-------------------------------------------------------------------------+  |
+|                                                                               |
++-------------------------------------------------------------------------------+
+```
+
+**Issue Types and Categories:**
+
+| Category | Icon | Color | Agent | Priority |
+|----------|------|-------|-------|----------|
+| DOC | Document | Purple | Scribe | Medium |
+| TEST | Flask | Red | Crucible | High |
+| SEC | Shield | Red | Aegis | Critical |
+| COV | Chart | Yellow | Crucible | Medium |
+| TODO | Checkbox | Blue | Varies | Low |
+| REVIEW | Eye | Orange | Sentinel | High |
+
+**Issue Card Elements:**
+- Category badge (colored icon)
+- Issue title
+- Detail line 1: Specific information
+- Detail line 2: Context/threshold
+- Severity indicator
+- Dispatch button with agent name
+
+**Interactions:**
+- Hover over issue: Show full details in expanded state
+- Click dispatch button: Open dispatch confirmation modal
+- Refresh: Re-scan for issues
+- Collapse: Minimize panel to header only
+
+---
+
+## Interaction Flows
+
+### Flow 1: Morning Check-in
+
+```
+User opens dashboard
+        |
+        v
++-------------------+
+| Dashboard loads   |
+| Shows loading     |
+| skeleton (300ms)  |
++-------------------+
+        |
+        v
++-------------------+
+| Data populated    |
+| Panels animate in |
+| (150ms stagger)   |
++-------------------+
+        |
+        v
+User sees at a glance:
+- 3 pending tasks
+- 2 agents working
+- 1 attention notification
+- 2 issues to address
+```
+
+### Flow 2: Dispatch Agent (Primary Flow)
+
+```
+User sees issue in Issues panel
+        |
+        v
++-------------------+
+| User clicks       |
+| [Dispatch Scribe] |
++-------------------+
+        |
+        v
++-------------------+
+| Confirmation      |
+| Modal appears     |
+| (200ms fade in)   |
++-------------------+
+        |
+  +-----------+
+  | User      |
+  | reviews   |
+  | details   |
+  +-----------+
+        |
+   +----+----+
+   |         |
+   v         v
+[Cancel]  [Confirm]
+   |         |
+   v         v
+Modal     +-------------------+
+closes    | POST /api/dispatch|
+          | shows spinner     |
+          +-------------------+
+                  |
+                  v
+          +-------------------+
+          | Success toast     |
+          | "Task AUTO-001    |
+          |  dispatched to    |
+          |  Scribe"          |
+          +-------------------+
+                  |
+                  v
+          +-------------------+
+          | Issue removed     |
+          | from panel        |
+          | (slide out 200ms) |
+          +-------------------+
+                  |
+                  v
+          +-------------------+
+          | Task appears in   |
+          | Tasks panel       |
+          | (slide in 200ms)  |
+          +-------------------+
+                  |
+                  v
+          +-------------------+
+          | Agent status      |
+          | updates to        |
+          | "working"         |
+          +-------------------+
+```
+
+### Flow 3: Task Card Expansion
+
+```
+User clicks task card
+        |
+        v
++-------------------+
+| Card expands      |
+| inline (200ms)    |
+| Other cards shift |
++-------------------+
+        |
+        v
+Expanded view shows:
++--------------------------------+
+| TASK-042                       |
+| Fix login bug                  |
+|                                |
+| Status: In Progress            |
+| Assigned: @anvil               |
+| Priority: High                 |
+| Created: 2h ago                |
+|                                |
+| Description:                   |
+| Users report intermittent      |
+| login failures...              |
+|                                |
+| [View File] [Reassign] [Close] |
++--------------------------------+
+```
+
+### Flow 4: Theme Toggle
+
+```
+User clicks theme toggle
+        |
+        v
++-------------------+
+| Icon rotates      |
+| (200ms)           |
++-------------------+
+        |
+        v
++-------------------+
+| CSS variables     |
+| transition        |
+| (300ms ease)      |
++-------------------+
+        |
+        v
++-------------------+
+| Preference saved  |
+| to localStorage   |
++-------------------+
+```
+
+---
+
+## State Documentation
+
+### Loading States
+
+**Initial Page Load:**
+```
++-----------------------------------------------------------------------------------+
+|                                                                                   |
+|  VIBE FORGE DASHBOARD                                    [Settings]  [Dark/Light] |
+|                                                                                   |
++-----------------------------------------------------------------------------------+
+|                                                                                   |
+|  +-------------------------+  +-------------------------+  +---------------------+|
+|  | TASKS                   |  | AGENTS                  |  | NOTIFICATIONS       ||
+|  |                         |  |                         |  |                     ||
+|  | [==================]    |  | [==================]    |  | [================]  ||
+|  | [==================]    |  | [==================]    |  | [================]  ||
+|  | [================]      |  | [==================]    |  | [================]  ||
+|  | [================]      |  | [==================]    |  |                     ||
+|  |                         |  |                         |  |                     ||
+|  +-------------------------+  +-------------------------+  +---------------------+|
+|                                                                                   |
+|  +-------------------------------------------------------------------------------+|
+|  | ISSUES (Actionable)                                                           ||
+|  | [====================================================================]        ||
+|  | [====================================================================]        ||
+|  +-------------------------------------------------------------------------------+|
+|                                                                                   |
++-----------------------------------------------------------------------------------+
+```
+
+**Skeleton Animation:**
+- Use shimmer effect (gradient animation left to right)
+- Duration: 1.5s per cycle
+- Show for minimum 300ms even if data loads faster (prevents flash)
+
+**Panel-Specific Loading:**
+```
++-------------------------+
+| TASKS           [Spin]  |
+|                         |
+| Loading tasks...        |
+|                         |
++-------------------------+
+```
+- Small spinner in panel header
+- "Loading [items]..." text
+
+---
+
+### Empty States
+
+**No Pending Tasks:**
+```
++-------------------------+
+|                         |
+|  TASKS                  |
+|                         |
+|       [Checkmark]       |
+|                         |
+|   All caught up!        |
+|   No pending tasks      |
+|                         |
+|   [Create Task]         |
+|                         |
++-------------------------+
+```
+
+**No Active Agents:**
+```
++-------------------------+
+|                         |
+|  AGENTS                 |
+|                         |
+|       [Moon icon]       |
+|                         |
+|   All agents idle       |
+|   Ready when you are    |
+|                         |
++-------------------------+
+```
+
+**No Notifications:**
+```
++---------------------+
+|                     |
+|  NOTIFICATIONS      |
+|                     |
+|      [Bell icon]    |
+|                     |
+|   Quiet day!        |
+|   No notifications  |
+|                     |
++---------------------+
+```
+
+**No Issues (Celebration State!):**
+```
++-------------------------------------------------------------------------------+
+|                                                                               |
+|  ISSUES (Actionable)                                                          |
+|                                                                               |
+|                              [Party emoji or confetti icon]                   |
+|                                                                               |
+|                         Everything looks great!                               |
+|                  No stale docs, failing tests, or security issues             |
+|                                                                               |
++-------------------------------------------------------------------------------+
+```
+
+---
+
+### Error States
+
+**Connection Lost:**
+```
++-----------------------------------------------------------------------------------+
+|                                                                                   |
+|  [!] Connection Lost                                              [Retry]        |
+|  Dashboard cannot reach the forge server. Check if the daemon is running.        |
+|                                                                                   |
++-----------------------------------------------------------------------------------+
+```
+- Full-width banner at top
+- Orange background
+- Shows retry button
+- Auto-retry every 5 seconds
+
+**API Error (Panel-specific):**
+```
++-------------------------+
+|                         |
+|  TASKS        [Retry]   |
+|                         |
+|      [Warning icon]     |
+|                         |
+|   Failed to load tasks  |
+|   Error: Timeout        |
+|                         |
+|   [Retry Now]           |
+|                         |
++-------------------------+
+```
+- Retry button in panel header
+- Error details shown
+- Other panels remain functional
+
+**Dispatch Failed:**
+```
++------------------------------------+
+|                                    |
+|  [X] Dispatch Failed               |
+|                                    |
+|  Could not create task for Scribe  |
+|                                    |
+|  Error: Agent currently offline    |
+|                                    |
+|  [Try Again]  [Cancel]             |
+|                                    |
++------------------------------------+
+```
+- Modal with error details
+- Option to retry or cancel
+
+---
+
+### Success States
+
+**Task Dispatched:**
+```
+Toast notification (bottom-right):
++--------------------------------+
+| [Checkmark]                    |
+| Task dispatched!               |
+| AUTO-047 assigned to Scribe    |
+|                                |
+| [View Task] [Dismiss]          |
++--------------------------------+
+```
+- Auto-dismiss after 5 seconds
+- Click to view task
+- Slide-in animation from right
+
+**Task Completed:**
+```
+Toast notification:
++--------------------------------+
+| [Checkmark]                    |
+| Task completed!                |
+| TASK-042 marked as done        |
+|                                |
+| [View] [Dismiss]               |
++--------------------------------+
+```
+
+---
+
+## Actionable Items UX - The Killer Feature
+
+### Issue Detection and Display
+
+Issues are automatically detected from multiple sources and displayed with clear, actionable information.
+
+**Issue Card Anatomy:**
+
+```
++-------------------------------------------------------------------------+
+| [Icon] Category Label: Specific Item                                    |
+|                                                                         |
+|        Detail line with context                                         |
+|        Additional info (threshold, severity, time)                      |
+|                                                                         |
+|                                                [Dispatch AgentName >>]  |
++-------------------------------------------------------------------------+
+```
+
+### Dispatch Button UX
+
+**Button States:**
+
+| State | Appearance | Cursor |
+|-------|------------|--------|
+| Default | Outlined, accent color | Pointer |
+| Hover | Filled, accent color | Pointer |
+| Active | Filled, darker accent | Pointer |
+| Loading | Spinner replacing text | Wait |
+| Disabled | Grayed out | Not-allowed |
+
+**Button Label Format:**
+- "Dispatch [AgentName]" with arrow icon
+- Uses agent's signature color
+- Shows agent avatar on hover
+
+### Dispatch Confirmation Modal
+
+```
++------------------------------------------------+
+|                                                |
+|  Dispatch Task to Scribe                       |
+|                                            [X] |
+|------------------------------------------------|
+|                                                |
+|  Issue: Stale documentation                    |
+|  Target: README.md                             |
+|  Reason: Last updated 45 days ago              |
+|                                                |
+|  This will create a new task:                  |
+|  +------------------------------------------+  |
+|  | AUTO-047                                 |  |
+|  | Update README.md documentation           |  |
+|  | Assigned to: Scribe                      |  |
+|  | Priority: Medium                         |  |
+|  +------------------------------------------+  |
+|                                                |
+|  [Cancel]                   [Confirm Dispatch] |
+|                                                |
++------------------------------------------------+
+```
+
+**Modal Behavior:**
+- Opens centered with overlay (0.5 opacity black)
+- Escape key or overlay click cancels
+- Tab cycles through interactive elements
+- Focus trapped inside modal
+- Auto-focus on Cancel button (safer default)
+
+### Post-Dispatch Feedback
+
+1. **Immediate** (0ms): Button shows loading spinner
+2. **Success** (typically 200-500ms):
+   - Modal closes with fade out
+   - Success toast appears
+   - Issue card slides out of Issues panel
+   - New task card slides into Tasks panel
+   - Agent status updates (if they pick it up quickly)
+3. **Failure**: Modal stays open, shows error message, allows retry
+
+---
+
+## Dark Mode Specification
+
+### Color Palette
+
+**Dark Mode (Default):**
+
+| Token | Hex | Usage |
+|-------|-----|-------|
+| `--bg-primary` | #0D1117 | Page background |
+| `--bg-secondary` | #161B22 | Panel backgrounds |
+| `--bg-tertiary` | #21262D | Card backgrounds |
+| `--bg-hover` | #30363D | Hover states |
+| `--bg-active` | #484F58 | Active/selected states |
+| `--border-default` | #30363D | Default borders |
+| `--border-muted` | #21262D | Subtle borders |
+| `--text-primary` | #F0F6FC | Primary text |
+| `--text-secondary` | #8B949E | Secondary text |
+| `--text-muted` | #6E7681 | Muted text |
+| `--text-link` | #58A6FF | Links |
+| `--accent-primary` | #238636 | Primary accent (green) |
+| `--accent-secondary` | #1F6FEB | Secondary accent (blue) |
+| `--danger` | #F85149 | Error/danger |
+| `--warning` | #D29922 | Warning |
+| `--success` | #3FB950 | Success |
+| `--info` | #58A6FF | Info |
+
+**Agent Colors (Dark Mode Optimized):**
+
+| Agent | Color | Hex |
+|-------|-------|-----|
+| Planning Hub | Purple | #A371F7 |
+| Anvil | Blue | #58A6FF |
+| Furnace | Orange | #F0883E |
+| Crucible | Green | #3FB950 |
+| Scribe | Cyan | #56D4DD |
+| Sentinel | Yellow | #D29922 |
+| Ember | Red | #F85149 |
+| Architect | Pink | #DB61A2 |
+| Aegis | Gold | #E3B341 |
+| Pixel | Magenta | #F778BA |
+
+### Light Mode Colors
+
+| Token | Hex | Usage |
+|-------|-----|-------|
+| `--bg-primary` | #FFFFFF | Page background |
+| `--bg-secondary` | #F6F8FA | Panel backgrounds |
+| `--bg-tertiary` | #FFFFFF | Card backgrounds |
+| `--bg-hover` | #F3F4F6 | Hover states |
+| `--bg-active` | #EAEEF2 | Active/selected states |
+| `--border-default` | #D0D7DE | Default borders |
+| `--border-muted` | #D8DEE4 | Subtle borders |
+| `--text-primary` | #1F2328 | Primary text |
+| `--text-secondary` | #656D76 | Secondary text |
+| `--text-muted` | #8C959F | Muted text |
+| `--text-link` | #0969DA | Links |
+| `--accent-primary` | #1A7F37 | Primary accent (green) |
+| `--accent-secondary` | #0969DA | Secondary accent (blue) |
+| `--danger` | #CF222E | Error/danger |
+| `--warning` | #9A6700 | Warning |
+| `--success` | #1A7F37 | Success |
+| `--info` | #0969DA | Info |
+
+### Contrast Ratios (WCAG AA Compliant)
+
+| Combination | Ratio | Status |
+|-------------|-------|--------|
+| text-primary on bg-secondary | 14.2:1 | Pass |
+| text-secondary on bg-secondary | 6.1:1 | Pass |
+| text-muted on bg-secondary | 4.6:1 | Pass (large text) |
+| accent-primary on bg-tertiary | 5.2:1 | Pass |
+| danger on bg-tertiary | 5.8:1 | Pass |
+
+### CSS Variable Implementation
+
+```css
+:root {
+  /* Default: Dark Mode */
+  --bg-primary: #0D1117;
+  --bg-secondary: #161B22;
+  --bg-tertiary: #21262D;
+  /* ... other tokens */
+
+  /* Animation */
+  --transition-fast: 150ms;
+  --transition-normal: 200ms;
+  --transition-slow: 300ms;
+}
+
+[data-theme="light"] {
+  --bg-primary: #FFFFFF;
+  --bg-secondary: #F6F8FA;
+  --bg-tertiary: #FFFFFF;
+  /* ... other tokens */
+}
+
+/* Theme transition */
+* {
+  transition: background-color var(--transition-normal),
+              color var(--transition-normal),
+              border-color var(--transition-normal);
+}
+```
+
+---
+
+## Accessibility
+
+### Keyboard Navigation
+
+**Global Shortcuts:**
+| Key | Action |
+|-----|--------|
+| `Tab` | Move to next interactive element |
+| `Shift+Tab` | Move to previous interactive element |
+| `Escape` | Close modal/dropdown, deselect |
+| `?` | Show keyboard shortcuts help |
+
+**Panel Navigation:**
+| Key | Action |
+|-----|--------|
+| `1` | Focus Tasks panel |
+| `2` | Focus Agents panel |
+| `3` | Focus Notifications panel |
+| `4` | Focus Issues panel |
+| `j/k` or `Arrow Down/Up` | Navigate items in focused panel |
+| `Enter` | Expand/select current item |
+| `d` | Dispatch (when on an issue) |
+
+### Focus Indicators
+
+```
++-------------------------+
+|                         |
+|  +-------------------+  |
+|  | TASK-042         *|  |  <-- Focus ring (2px solid accent color)
+|  | Fix login bug     |  |
+|  | @anvil | 2h ago   |  |
+|  +-------------------+  |
+|                         |
++-------------------------+
+
+Focus ring styles:
+- 2px solid outline
+- 2px offset (so it doesn't overlap content)
+- High contrast color (accent-secondary in dark mode)
+- No outline on mouse focus (:focus-visible)
+```
+
+### Screen Reader Announcements
+
+**ARIA Live Regions:**
+```html
+<!-- Toast notifications -->
+<div role="status" aria-live="polite" aria-atomic="true">
+  <!-- Toast content announced when added -->
+</div>
+
+<!-- Error messages -->
+<div role="alert" aria-live="assertive">
+  <!-- Errors announced immediately -->
+</div>
+
+<!-- Loading states -->
+<div aria-busy="true" aria-describedby="loading-message">
+  <span id="loading-message" class="sr-only">Loading tasks</span>
+</div>
+```
+
+**Semantic Landmarks:**
+```html
+<header role="banner">...</header>
+<main role="main">
+  <section aria-labelledby="tasks-heading">...</section>
+  <section aria-labelledby="agents-heading">...</section>
+  <section aria-labelledby="notifications-heading">...</section>
+  <section aria-labelledby="issues-heading">...</section>
+</main>
+<footer role="contentinfo">...</footer>
+```
+
+### Color Independence
+
+All information conveyed by color is also conveyed by:
+- **Icons** (status icons for agents, category icons for issues)
+- **Text labels** (status text, category labels)
+- **Patterns** (error states have different borders)
+
+Example: Agent status
+- Green circle + "idle" text
+- Blue spinning icon + "working" text
+- Red X icon + "error" text
+
+### Skip Links
+
+```html
+<a href="#main-content" class="skip-link">Skip to main content</a>
+<a href="#tasks-panel" class="skip-link">Skip to tasks</a>
+<a href="#issues-panel" class="skip-link">Skip to issues</a>
+```
+
+Skip links visible on focus, hidden otherwise.
+
+---
+
+## Responsive Design
+
+### Breakpoints
+
+| Breakpoint | Width | Layout |
+|------------|-------|--------|
+| Desktop | 1200px+ | 3-column top, full-width bottom |
+| Tablet | 768px - 1199px | 2-column stacked |
+| Mobile | 320px - 767px | Single column, collapsible panels |
+
+### Tablet Layout (768px - 1199px)
+
+```
++------------------------------------------+
+|  VIBE FORGE DASHBOARD     [Settings] [T] |
++------------------------------------------+
+|                                          |
+|  +------------------+ +----------------+ |
+|  | TASKS            | | AGENTS         | |
+|  |                  | |                | |
+|  | [Cards...]       | | [Cards...]     | |
+|  |                  | |                | |
+|  +------------------+ +----------------+ |
+|                                          |
+|  +--------------------------------------+|
+|  | NOTIFICATIONS                        ||
+|  | [Cards...]                           ||
+|  +--------------------------------------+|
+|                                          |
+|  +--------------------------------------+|
+|  | ISSUES (Actionable)                  ||
+|  | [Cards...]                           ||
+|  +--------------------------------------+|
+|                                          |
++------------------------------------------+
+```
+
+### Mobile Layout (320px - 767px)
+
+```
++------------------------+
+|  VIBE FORGE    [M] [T] |
++------------------------+
+|                        |
+| [Tasks] [Agents] [Notif]  <- Tab bar
+|                        |
+| +--------------------+ |
+| | TASKS              | |
+| |                    | |
+| | +----------------+ | |
+| | | TASK-042       | | |
+| | | Fix login bug  | | |
+| | +----------------+ | |
+| |                    | |
+| | +----------------+ | |
+| | | TASK-041       | | |
+| | | Dashboard UI   | | |
+| | +----------------+ | |
+| |                    | |
+| +--------------------+ |
+|                        |
+| +--------------------+ |
+| | ISSUES             | |
+| | +----------------+ | |
+| | | [DOC] README   | | |
+| | | [Dispatch >>]  | | |
+| | +----------------+ | |
+| +--------------------+ |
+|                        |
++------------------------+
+| [Status] | [Refresh]   |
++------------------------+
+```
+
+**Mobile Adaptations:**
+- Tab bar for panel switching
+- Issues always visible at bottom (sticky)
+- Compact task cards
+- Bottom navigation bar
+- Hamburger menu for settings
+- Swipe gestures for panel navigation
+
+---
+
+## Keyboard Shortcuts
+
+### Quick Reference Card (shown with `?`)
+
+```
++------------------------------------------------+
+|                                                |
+|  Keyboard Shortcuts                        [X] |
+|                                                |
+|  Navigation                                    |
+|  ----------------------------------------      |
+|  1 2 3 4    Focus panels (Tasks, Agents, etc.) |
+|  j / k      Move down / up in list             |
+|  Enter      Expand / select item               |
+|  Escape     Close / deselect                   |
+|                                                |
+|  Actions                                       |
+|  ----------------------------------------      |
+|  d          Dispatch (on issue)                |
+|  r          Refresh current panel              |
+|  t          Toggle theme                       |
+|  /          Focus search (future)              |
+|                                                |
+|  General                                       |
+|  ----------------------------------------      |
+|  ?          Show this help                     |
+|  Tab        Next element                       |
+|  Shift+Tab  Previous element                   |
+|                                                |
++------------------------------------------------+
+```
+
+---
+
+## Implementation Notes for Anvil
+
+### Priority Order
+
+1. **Core Layout** - Header, 3 panels, footer
+2. **Dark Mode** - CSS variables, theme toggle
+3. **Tasks Panel** - Cards, filters, expansion
+4. **Agents Panel** - Status display, avatars
+5. **Issues Panel** - Issue cards, dispatch buttons
+6. **Dispatch Flow** - Modal, confirmation, feedback
+7. **Notifications** - Toast system, panel
+8. **Loading/Error States** - Skeletons, error handling
+9. **Responsive** - Tablet, then mobile
+10. **Accessibility** - Keyboard nav, ARIA, skip links
+
+### Component Library Suggestions
+
+Keep it simple for MVP:
+- No framework (vanilla JS) or lightweight (Alpine.js)
+- CSS custom properties for theming
+- Semantic HTML for accessibility
+- Web Components if reuse needed
+
+### Animation Guidelines
+
+| Element | Duration | Easing |
+|---------|----------|--------|
+| Hover effects | 150ms | ease-out |
+| Panel transitions | 200ms | ease-in-out |
+| Modal open/close | 200ms | ease-out |
+| Toast slide-in | 200ms | ease-out |
+| Skeleton shimmer | 1500ms | linear |
+| Card expansion | 200ms | ease-in-out |
+
+### Testing Checklist
+
+- [ ] All states tested (loading, empty, error, success)
+- [ ] Keyboard-only navigation works end-to-end
+- [ ] Screen reader announces important changes
+- [ ] Color contrast passes WCAG AA
+- [ ] Dark/light mode transitions smoothly
+- [ ] Mobile layout is usable
+- [ ] Dispatch flow completes successfully
+- [ ] WebSocket reconnects on disconnect
+
+---
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | 2026-01-16 | Pixel | Initial specification |
+
+---
+
+*"The best interface is no interface. The second best is one that just works." - Pixel*