From 32f3abb0ab19379e5f0e6d2e30ef19d80600b6a5 Mon Sep 17 00:00:00 2001
From: Nexus Dev <nexus@local>
Date: Wed, 1 Apr 2026 17:30:40 +0000
Subject: [PATCH] =?UTF-8?q?docs(22):=20fix=20UI-SPEC=20checker=20blocks=20?=
 =?UTF-8?q?=E2=80=94=20copywriting,=20typography,=20spacing,=20color=20not?=
 =?UTF-8?q?e?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Replace generic "Save"/"Cancel" with "Save edit"/"Discard edit" in inline edit controls
- Add solution path to agent load error: "Could not load agents. Refresh to try again."
- Eliminate 12px font size by using 13px + text-muted-foreground for slash command descriptions (4 sizes total: 11/13/15/20px)
- Replace gap-1.5 (6px) with gap-2 (8px) in identity bar — multiples-of-4 compliance
- Add theming note on bg-cyan-400 semantic token promotion path

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../phases/22-agent-streaming/22-UI-SPEC.md   | 38 +++++++++----------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/.planning/phases/22-agent-streaming/22-UI-SPEC.md b/.planning/phases/22-agent-streaming/22-UI-SPEC.md
index 061c8584..554138c7 100644
--- a/.planning/phases/22-agent-streaming/22-UI-SPEC.md
+++ b/.planning/phases/22-agent-streaming/22-UI-SPEC.md
@@ -75,7 +75,7 @@ Every assistant message gains an identity bar above the message content:
 [ AgentIcon 16px ]  [ agentName 13px semibold ]  [ timestamp 11px muted ]
 ```
 
-- Identity bar: `flex items-center gap-1.5 mb-1`
+- Identity bar: `flex items-center gap-2 mb-1`
 - Icon: 16×16px, rendered via `<AgentIcon icon={agentIcon} className="h-4 w-4" />`
 - Name: `text-[13px] font-semibold text-foreground`
 - Timestamp: `text-[11px] text-muted-foreground`
@@ -160,7 +160,7 @@ Inherited from Phase 21. No new tokens for Phase 22.
 | xl | 32px | (no new usage) |
 
 **New spacing values (Phase 22 only):**
-- Identity bar gap: `gap-1.5` (6px) — between icon and agent name
+- Identity bar gap: `gap-2` (8px) — between icon and agent name; matches existing `gap-2` pattern in ChatPanel header
 - Edit/retry icon button size: 14×14px (`h-3.5 w-3.5`) — matches `MoreHorizontal` in `ChatConversationItem`
 - Streaming cursor width: `w-2` (8px), height: `h-[1em]`
 
@@ -173,14 +173,14 @@ All inherited from Phase 21. One addition for agent identity:
 | Role | Size | Weight | Line Height | Usage |
 |------|------|--------|-------------|-------|
 | Body / message text | 15px (0.9375rem) | 400 | 1.6 | Chat message prose (unchanged) |
-| Label / UI chrome | 13px (0.8125rem) | 400 | 1.4 | Conversation list, timestamps (unchanged) |
+| Label / UI chrome | 13px (0.8125rem) | 400 | 1.4 | Conversation list, timestamps, slash command descriptions (unchanged) |
 | Agent name (identity bar) | 13px (0.8125rem) | 600 | 1.4 | Agent name above assistant messages |
 | Message timestamp | 11px (0.6875rem) | 400 | 1.4 | Timestamp in identity bar |
-| Slash command label | 13px (0.8125rem) | 400 | 1.4 | Command name in slash popover |
-| Slash command description | 12px (0.75rem) | 400 | 1.4 | Description text in slash popover, `text-muted-foreground` |
 
 **Weights used:** 400 (regular) and 600 (semibold). No additional weights. Same constraint as Phase 21.
 
+**Slash command descriptions:** Rendered at 13px / 400 with `text-muted-foreground` — color/opacity distinction from the 13px / 400 command label is sufficient; no separate size needed. This keeps the total distinct sizes at 4 (11px, 13px, 15px, and 20px from Phase 21 markdown headings).
+
 **11px timestamp note:** This is a 2px reduction below the Phase 21 minimum of 13px, used only within the compact identity bar where spatial context is sufficient. It is never used for interactive or error text.
 
 ---
@@ -202,7 +202,7 @@ All values inherited from Phase 21 CSS variable system. No new color variables i
 - Same as Phase 21 (conversation rows, code block toolbar)
 - Slash command popover highlighted item: `bg-accent` (via `<Command>` item selection)
 
-**Streaming indicator color:** `bg-cyan-400 animate-pulse` — reused directly from `agentStatusDot.running` in `status-colors.ts`. Applied as a 6×6px dot beside the agent name in the identity bar while streaming.
+**Streaming indicator color:** `bg-cyan-400 animate-pulse` — reused directly from `agentStatusDot.running` in `status-colors.ts`. Applied as a 6×6px dot beside the agent name in the identity bar while streaming. Note: `bg-cyan-400` bypasses the CSS variable system. If theming requirements evolve (e.g. a theme requires a different streaming color), promote this to a semantic token such as `--streaming-indicator` in the CSS variable layer.
 
 ### Agent Role Colors (THEME-03)
 
@@ -285,10 +285,10 @@ New components to build in Phase 22:
 | Interaction | Behavior |
 |-------------|---------|
 | Hover user message | `Pencil` icon button appears at top-right of bubble |
-| Click `Pencil` | Message bubble becomes an inline textarea pre-filled with existing content; "Save" and "Cancel" buttons appear below; send button hidden |
-| Edit textarea + click "Save" | POST updated message to server; assistant messages after this message are removed from thread (regeneration); new streaming response begins |
-| Click "Cancel" | Textarea reverts to read-only bubble; no changes |
-| Save with empty content | "Save" button disabled when textarea is empty |
+| Click `Pencil` | Message bubble becomes an inline textarea pre-filled with existing content; "Save edit" and "Discard edit" buttons appear below; send button hidden |
+| Edit textarea + click "Save edit" | POST updated message to server; assistant messages after this message are removed from thread (regeneration); new streaming response begins |
+| Click "Discard edit" | Textarea reverts to read-only bubble; no changes |
+| Save with empty content | "Save edit" button disabled when textarea is empty |
 
 ### Retry (Assistant Messages)
 
@@ -359,16 +359,16 @@ All Phase 21 copy is preserved unchanged. Phase 22 additions:
 | Stop button label | "Stop generating" | `variant="outline" size="sm"`; icon `Square` precedes label |
 | Edit message button aria-label | "Edit message" | Icon-only; `Pencil` icon |
 | Retry message button aria-label | "Retry response" | Icon-only; `RefreshCw` icon |
-| Inline edit save button | "Save" | `variant="default" size="sm"` |
-| Inline edit cancel button | "Cancel" | `variant="ghost" size="sm"` |
+| Inline edit save button | "Save edit" | `variant="default" size="sm"` |
+| Inline edit cancel button | "Discard edit" | `variant="ghost" size="sm"` |
 | Streaming interrupted error | "Response interrupted." | Inline `text-destructive`; followed by Retry link |
 | Retry inline link | "Retry" | `text-primary underline cursor-pointer` — not a `<Button>` |
 | Stopped message suffix | "[stopped]" | `text-muted-foreground text-[11px] ml-1`; appended to partial message |
-| Slash command: `/brainstorm` description | "Route to Brainstormer" | Second line in slash popover item |
-| Slash command: `/ask-pm` description | "Route to PM" | Second line |
-| Slash command: `/ask-engineer` description | "Route to Engineer" | Second line |
-| Slash command: `/task` description | "Create a task" | Second line |
-| Slash command: `/search` description | "Search conversations" | Second line; greyed out — "Coming soon" suffix in muted text |
+| Slash command: `/brainstorm` description | "Route to Brainstormer" | Second line in slash popover item; `text-muted-foreground` |
+| Slash command: `/ask-pm` description | "Route to PM" | Second line; `text-muted-foreground` |
+| Slash command: `/ask-engineer` description | "Route to Engineer" | Second line; `text-muted-foreground` |
+| Slash command: `/task` description | "Create a task" | Second line; `text-muted-foreground` |
+| Slash command: `/search` description | "Search conversations" | Second line; `text-muted-foreground`; "Coming soon" suffix in muted text; greyed out |
 | Jump to bottom button aria-label | "Scroll to latest message" | Icon-only; `ArrowDown` icon |
 | Input placeholder (streaming) | "Waiting for response..." | Replaces "Message your agent..." while `isStreaming: true`; textarea is disabled |
 
@@ -380,7 +380,7 @@ All Phase 21 copy is preserved unchanged. Phase 22 additions:
 
 | Component | Loading state | Empty state | Error state | Streaming state |
 |-----------|--------------|-------------|-------------|-----------------|
-| `ChatAgentSelector` | Skeleton pill 80px wide | "No agents configured" | "Could not load agents." — popover body | n/a |
+| `ChatAgentSelector` | Skeleton pill 80px wide | "No agents configured" | "Could not load agents. Refresh to try again." — popover body | n/a |
 | `ChatMessage` (assistant) | n/a | n/a | Inline "Response interrupted. Retry" | Cursor blink + streaming text accumulation |
 | `ChatMessageList` | 3x Skeleton rows (h-16 variable) | Inherited from Phase 21 | Inherited from Phase 21 | Auto-scroll; Stop button visible |
 | `ChatInput` | n/a | n/a | Inherited from Phase 21 | `disabled`; placeholder "Waiting for response..." |
@@ -425,7 +425,7 @@ Inherits all Phase 21 accessibility contracts. Phase 22 additions:
 | Slash popover | `role="listbox"` on items; announce open state with `aria-expanded` |
 | Mention popover | `role="listbox"` on items; announce open state with `aria-expanded` |
 | Jump to bottom | `aria-label="Scroll to latest message"` |
-| Edit save/cancel | Standard button labels (no icon-only ambiguity) |
+| Edit save/cancel | Standard button labels — "Save edit" and "Discard edit" (no icon-only ambiguity) |
 | Focus after stop | Focus returns to `ChatInput` textarea after stop action |
 | Focus after retry | No focus change — user may be reading the regenerated message |