roboco/docs/ux_ui/design/01-interaction-spec.md

Prompter — Interaction Specification

Overview

The Prompter is a first-class Panel page that lets users author tasks via conversational LLM assistance rather than hand-writing specs. The journey is intentionally linear and un-bypassable:

Chat → Draft → Review → Confirm → Launch → Success

Each transition is explicit. There is no hidden auto-launch; the human is always the final gate before a task enters the system.

---

Screen States

1. Chat Screen (Default)

Purpose: The user describes what they need in natural language. The LLM responds with clarifying questions and, when enough context is gathered, offers to generate a draft.

Layout (mapped to existing components):

• Container: Full page inside the dashboard layout ((dashboard)/layout.tsx)
• Header row:
  • Page title (H1): see 04-naming-and-navigation.md
  • Subtitle: "Describe what you need. The assistant will ask questions and draft a task for your team."
• Chat area (Card + custom flex column):
  • Message list (ScrollArea): user messages right-aligned, assistant messages left-aligned.
  • Message bubbles: Card with py-3 px-4 and subtle background differentiation:
    • User: bg-primary/10
    • Assistant: bg-muted
  • Typing indicator: Skeleton pulse (3 lines) when assistant is generating.
• Composer bar (fixed to bottom of chat area):
  • Textarea (auto-resize, max 4 lines) with placeholder: "Describe the task you want to create..."
  • Button (primary, icon Send) labeled "Send"
  • Keyboard: Enter sends; Shift+Enter adds newline.
• Empty state (first visit):
  • Centered Card with illustration placeholder + suggested prompts:
    • "Add a dark-mode toggle to the panel"
    • "Write a design spec for a confirmation flow"
    • "Create a backend task to add OAuth2 login"

Component references:

• panel/src/components/ui/card.tsx — message bubbles
• panel/src/components/ui/textarea.tsx — composer input
• panel/src/components/ui/button.tsx — send button
• panel/src/components/ui/scroll-area.tsx — scrollable message list
• panel/src/components/ui/skeleton.tsx — typing indicator

Accessibility:

• aria-live="polite" on the message list so screen readers announce new assistant messages.
• Composer Textarea has aria-label="Task description".

Error states:

• LLM error: assistant message styled as Alert variant destructive with text: "Something went wrong. Try rephrasing or try again later."
• Network error: toast via sonner (already in panel globals).

---

2. Draft Preview (Inline Transition)

Purpose: Once the LLM has enough context, it generates a structured task draft. The draft is presented inline in the chat as a special "proposal" message, not a separate page. This preserves conversational context.

Trigger: Assistant message ends with: "I can draft a task based on what we discussed. Would you like to review it?" + two quick actions.

Layout:

• Proposal card (full-width, Card with border-primary):
  • Header: CardHeader with CardTitle "Draft Task" and Badge showing suggested team.
  • Body (CardContent):
    • Title (bold, text-lg)
    • Description (truncated to 4 lines with fade-out; Button "Expand" to show full text in a Dialog)
    • Acceptance criteria (ScrollArea, max height 160px):
      • Numbered list using Badge variant outline for each item number.
    • Metadata row (flex, gap-4, text-sm text-muted-foreground):
      • Team: Badge
      • Complexity: Badge variant secondary
      • Nature: Badge variant secondary
  • Footer (CardFooter, justify-between):
    • Button variant outline: "Keep Chatting" (returns to free chat)
    • Button (primary): "Review & Confirm" (advances to confirmation interstitial)

Component references:

• panel/src/components/ui/card.tsx — proposal card
• panel/src/components/ui/badge.tsx — team, complexity, nature labels
• panel/src/components/ui/dialog.tsx — expand description
• panel/src/components/ui/scroll-area.tsx — criteria list

Accessibility:

• Proposal card is focusable (tabIndex={0}) and announces via aria-live.
• "Review & Confirm" button has aria-describedby pointing to a hidden span summarizing the draft title.

---

3. Confirmation Interstitial (Modal)

Purpose: The un-bypassable human gate. The user sees the full draft, can edit fields inline, and must explicitly confirm before the task is created.

Behavior: Opens as a full-size Dialog (DialogContent with sm:max-w-3xl lg:max-w-4xl max-h-[90vh]) so the user cannot miss it. This is not a sidebar or inline form; it interrupts the flow by design.

Detailed spec: see 02-confirmation-interstitial.md.

---

4. Launch / Success

Purpose: Provide clear feedback that the task has entered the system and give the user a next step.

Layout (inline in chat, replacing the proposal card):

• Success card (Card with border-green-600 or border-success token if available):
  • Header: CardHeader with CardTitle "Task launched" + Badge "Pending"
  • Body: one-sentence summary: "Your task '{title}' has been created and routed to the {team} cell."
  • Footer (CardFooter, gap-2):
    • Button variant ghost + Link to /tasks/{taskId}: "View Task →"
    • Button variant outline: "Start Another" (resets chat to empty state)

Component references:

• panel/src/components/ui/card.tsx
• panel/src/components/ui/badge.tsx
• panel/src/components/ui/button.tsx

---

State Machine

[Empty] --user types--> [Chatting]

[Chatting] --assistant offers draft--> [DraftPreview]
[Chatting] --user keeps typing--> [Chatting]
[Chatting] --LLM error--> [Chatting] (error bubble appended)

[DraftPreview] --"Keep Chatting"--> [Chatting]
[DraftPreview] --"Review & Confirm"--> [ReviewModal]

[ReviewModal] --"Cancel"--> [DraftPreview] (modal closes, chat scrolls to proposal)
[ReviewModal] --user edits fields--> [ReviewModal] (dirty state)
[ReviewModal] --"Confirm & Launch"--> [Launching] (button loading)

[Launching] --API success--> [Success]
[Launching] --API error--> [ReviewModal] (error banner + button enabled)

[Success] --"Start Another"--> [Empty]
[Success] --"View Task"--> (navigate away)

---

Loading Patterns

State	Visual
Assistant thinking	Skeleton 3-line pulse inside assistant bubble
Draft generating	Skeleton card (title + 4 lines + criteria placeholder)
Launching	Primary button shows spinner + "Launching..." text
Navigating to task	Page transition handled by Next.js; no extra UX needed

---

Error Patterns

Scenario	UI	Copy
LLM stream fails mid-chat	Toast + inline retry button	" assistant had a hiccup. [Retry]"
Draft generation fails	Inline alert inside chat	"Couldn’t draft a task right now. Keep chatting or try again."
Confirm & Launch API fails	Banner inside review modal	"We couldn’t create the task. Check your connection and try again."
Validation error (e.g. title too short)	Field-level error text	Same rules as CreateTaskDialog

---

Responsive Behavior

• Desktop (>= 1024px): Chat and composer are centered in a max-width 880px column inside the dashboard layout.
• Tablet (768–1023px): Same, max-width 720px.
• Mobile (< 768px): Composer bar becomes sticky at bottom of viewport; chat scrolls above it. Review modal becomes bottom sheet (Sheet component) instead of center Dialog if needed, but since this is a dashboard application primarily used on desktop, Dialog is acceptable for MVP.

---

Out of Scope (Phase 2)

• Conversation history / "My Prompts" list
• Persistent drafts across sessions
• Advanced model comparison side-by-side
• Rich media uploads in chat