Submatter/.convoys/workspace-chat-polish/planning-ux.md

name	classification	success_metric	skip	status	created	model_policy
workspace-chat-polish	feature	Workspace Chat presents one coherent, accessible navigation and message experience with a contextual sidebar, recognizable authors, composer-based editing, modal deletion, and Favorites/Channels/DMs organization.		in-progress	2026-11-02	roles escalate_to role-conductor role-ia-architect role-ui-designer role-ux-reviewer role-architect role-implementer role-reviewer role-a11y-auditor claude-planning claude-planning claude-planning claude-planning claude-planning qwen-coder qwen-coder claude-planning claude-planning

UX Planning for Workspace Chat Polish

1. Evidence from existing planning document

• Route detection: Use usePathname segment‑aware helper to detect only /[workspaceSlug]/chat and descendants (line 190‑192). Avoid substring matches that could false‑positive on object titles.
• Component boundaries: AppShell decides Chat vs Sidebar; ChatSidebar owns section state, ChatSectionHeader owns disclosure/focus actions, ChatListRow is shared across sections, ChatWorkspace owns message history and composer state (lines 181‑188).
• Profile identity: Use existing users data (name, avatarUrl) and project a workspace‑authorized participant summary; never render raw UUID as visible identity (line 132, 197).
• Edit flow: Populate the primary composer, show “Update”/Cancel, keep original message in history with editing indicator (lines 135‑144).
• Delete flow: Use a shared accessible dialog primitive, trap/restore focus, prevent accidental submission, restore focus on cancel (lines 147‑148).
• Favorites & DMs: Favorites use a single router contract with discriminated target (object or chatChannel) and enforce cross‑workspace authorization; DMs support one‑to‑many participants via existing createDirect API (lines 198‑204).

2. Heuristic Risks & Recommendations

Heuristic	Risk	Recommendation
Recognition over recall	Flat Channels list may become long; users must scan many items.	Provide optional search/filter input in the sidebar header; keep default flat list but allow grouping via a user‑selected mode.
Visibility of system status	Saving edits, failed sends, reconnect, delete completion lack clear feedback.	Show inline status messages (toast/aria-live) and non‑visual announcements for each state change.
User control & freedom	Edit requires obvious Cancel; delete needs Cancel as default and focus restoration.	Ensure Cancel button is prominent, focus is restored to the originating action on cancel, and delete dialog defaults to Cancel.
Consistency & standards	UI may diverge from Spaces sidebar primitives.	Reuse existing ChatSectionHeader, ChatListRow, Dialog primitives; match colors, button styles, tooltips, dropdown behavior.
Flexibility & efficiency	Keyboard focus may not reveal hover actions.	Expose the same actions on :focus-within and focus-visible; ensure Add, More, and Delete are reachable via keyboard without hover.
Error prevention	Pending mutations may allow invalid edits or deletes.	Disable primary actions while mutations are in flight, show conflict resolution UI, preserve draft text on error.
Aesthetic / minimalist design	Risk of adding Defaults or duplicate lists.	Strictly enforce the three sections (Favorites, Channels, DMs) and prohibit Defaults/New Message sections.
Help users recover from errors	Profile lookup failures or favorite/DM creation errors need recovery.	Provide inline alerts/toast with retry where safe; fallback avatar/initials for missing profile data.

3. Flow Acceptance Criteria

1. Chat Route – Rail → Chat contextual surface (sidebar + conversation). Sidebar appears only when URL matches /[workspaceSlug]/chat*; otherwise global rail shows existing Spaces sidebar.
2. Edit Message – Click “Edit” → focus primary composer → load original body → show “Update” and “Cancel” → on “Update” submit mutation → status announcement (e.g., “Message edited”) → history refresh with editing indicator; on “Cancel” discard changes, restore focus, no history change.
3. Delete Message – Click “Delete” → accessible confirmation dialog appears → focus trapped → “Cancel” returns focus to delete button, “Delete” performs destructive action → message replaced with tombstone or removal → focus returns to message list; dialog cannot be submitted twice.
4. Add DM – Click “Add” in DMs header → participant picker opens → supports selecting one or multiple participants → on selection, creates/opens direct channel → shows participant avatars/names safely (no raw IDs) → conversation loads.
5. Section Interaction – Disclosure control (aria-expanded) toggles section visibility; hover reveals Add/More actions; focus‑visible reveals same actions; all actions are keyboard operable.
6. Accessibility – All interactive elements have accessible names, role="button" where appropriate, aria-live="polite" for status announcements, focus order logical, color contrast meets WCAG AA, and screen‑reader users can navigate sections via headings.

4. Keyboard & Accessibility Requirements

• Focus Management: Use focus-within and focus-visible to expose hover actions to keyboard users; trap focus inside the delete confirmation dialog and restore focus to the originating element on cancel.
• ARIA: aria-expanded on disclosure controls, labelled regions for each section, aria-live="polite" for status messages (edit save, delete confirm, reconnect).
• Navigation: Logical tab order; skip‑to‑content link to jump from global rail to Chat sidebar; ensure all interactive elements are reachable via Tab/Enter/Space.
• Screen Reader: Provide concise accessible names (e.g., “Edit message”, “Delete message”, “Add direct message”). Avoid reading raw UUIDs; use participant display names or initials.
• Contrast & Hit Targets: Minimum 44 × 44 px touch targets; ensure text and UI components meet WCAG AA contrast ratios.

5. Open Risks & Decisions Needed

1. Search/Filter Implementation – Should the sidebar include an input field for filtering channels/favorites, or rely on user‑selected grouping only? Decision pending.
2. Space Metadata in Channels – The plan mentions optional spaceId for channel metadata. Need to confirm whether existing space objects provide sufficient context or if additional fields are required.
3. Favorites Target Contract – Final schema for the favorites router (discriminated object vs chatChannel) and unique index strategy must be defined before implementation.
4. Responsive Behavior – Define breakpoint at which the Chat sidebar becomes a drawer/sheet; current guidance (260–300 px) needs concrete media query values.
5. Dialog Primitive Reuse – Verify if a shared accessible dialog component exists in the codebase; if not, a minimal shared dialog must be added.

6. Key Decisions (to be captured in implementation)

• Use segment‑aware route detection (usePathname) to limit ChatSidebar mounting to Chat routes only.
• Reuse existing ChatSectionHeader, ChatListRow, and Dialog primitives for consistency.
• Project participant identities from users data; never expose raw UUIDs in the UI.
• Implement favorites as a discriminated target with cross‑workspace authorization checks.
• Ensure all actions (Add, More, Edit, Delete) are reachable via keyboard (focus-visible) and have visible focus indicators.
• Provide inline status announcements for edit save, delete confirm, and failed operations.

---

File: /workspace/submatter/.convoys/workspace-chat-polish/planning-ux.md
Key decisions captured above; open risks listed for future resolution.