/design-chatbot

description: "Design a complete chatbot or conversational assistant UI — dialog flows, message bubbles, quick replies, typing indicators, error states, and accessibility."
argument-hint: "[assistant type: support|sales|onboarding|general] [platform: web|mobile|slack] [persona brief]"
allowed-tools: ["Read", "Write", "mcp__*"]

/design-chatbot

You are designing a complete chatbot or conversational assistant UI. Your output is a single structured spec covering persona, dialog flows, message UI, component library, error states, and accessibility.

Input

Arguments: **$ARGUMENTS**

Parse the following from `$ARGUMENTS`:

• **Assistant type**: customer support / sales / onboarding / general (default: general)
• **Platform**: web / mobile / Slack (default: web)
• **Persona brief**: any name, tone, or personality notes the user provides

---

Step 1: Load Knowledge Base

Read `${CLAUDE_PLUGIN_ROOT}/skills/design/references/conversational-designer.md` to apply the full Conversational Designer knowledge base to every section below.

**MCP Fallback**: If the file cannot be read, proceed using inline knowledge. The inline knowledge for this command covers: persona dimensions (name, avatar, voice tone, vocabulary, emoji use), dialog flow states (GREETING → MAIN_FLOW → SLOT_FILLING → CONFIRMATION → EXECUTION, plus DISAMBIGUATION, FALLBACK_1/2/ESCALATION, GOODBYE), message bubble specs (user right-aligned brand accent; bot left-aligned neutral surface), quick reply chips (pill buttons, disappear on tap, max 5), typing indicator (3-dot pulse, 500ms delay), error state mapping (API timeout → retry, 5xx → retry + escalation, session expired → restart), and accessibility (aria-live="polite", role="log", keyboard nav, screen reader announcement order).

---

Step 2: Generate the Spec

Produce all six sections below as a single continuous output. Do not pause or ask for confirmation between sections.

---

Section 1: Persona & Voice Spec

Define the assistant's identity before any dialog is written.

| Dimension | Value | |---|---| | **Name** | [Derived from persona brief, or propose one if not provided] | | **Platform context** | [assistant type on platform] | | **Avatar style** | [Human-adjacent / abstract shape / brand mascot — choose based on assistant type and platform] | | **Language register** | [Formal / Casual / Technical — justify by assistant type] | | **Vocabulary level** | [Reading grade level, contraction use, jargon policy] | | **Emoji use** | [None / Sparingly (1 per message max) / Moderate — justify] |

**Tone adjectives (3–5):** [List tone words that characterize every message the bot sends, e.g.: warm, direct, efficient, clear, empathetic]

**Personality spectrum position:**

Formal     ←————[mark position]————→ Casual
Verbose    ←————[mark position]————→ Concise
Serious    ←————[mark position]————→ Playful

**Prohibited language patterns** (never say):

• Never claim to be human if directly asked
• Never use hedging on factual questions ("I think", "I believe") — use "I don't have information on that"
• Never express impatience or mock the user, even after repeated failures
• Never apologize more than once per error
• [Add 2–3 assistant-type-specific prohibitions based on the parsed assistant type]

---

Section 2: Dialog Flow Map

Four key conversation paths rendered as text-based flow diagrams.

Happy Path (user resolved in ≤3 turns)

User: [opening message matching primary use case]
  └─→ BOT: [greeting + immediate value offer]
       └─→ User: [core request — intent recognized, high confidence ≥0.85]
            └─→ BOT: [slot-fill or direct response]
                 └─→ User: [confirmation or completion trigger]
                      └─→ BOT: [success message + next step or close]
                           └─→ [END or continue]

Escalation Path (bot cannot resolve → human handoff)

User: [message — intent not recognized]
  └─→ BOT: FALLBACK_1 — rephrase + 2–3 quick reply options
       └─→ User: [still unrecognized or escalation phrase]
            └─→ BOT: FALLBACK_2 — different language + top capabilities
                 └─→ User: [third failure or "talk to a person"]
                      └─→ BOT: ESCALATION — connect to human, share context
                           └─→ [HUMAN HANDOFF — session_id, summary, transcript]

Out-of-Scope Path (topic outside bot's domain)

User: [request the bot cannot handle]
  └─→ BOT: Acknowledge the request is outside scope
       └─→ BOT: Redirect to what the bot CAN do
            └─→ BOT: Offer alternative channel (link, email, phone)
                 └─→ User: [chooses alternative or returns to scope]

Error Recovery Path (API failure → graceful degradation)

BOT: [action attempted — API call fails]
  └─→ BOT: Friendly error message — no raw error codes exposed
       └─→ BOT: Retry button inline OR automatic retry in 3s
            ├─→ [Retry succeeds] → Resume flow from current state
            └─→ [Retry fails] → Escalation link + async alternatives (email/phone)

**Confidence threshold routing:**

| Confidence | Threshold | Action | |---|---|---| | High | ≥ 0.85 | Proceed; implicit confirmation for reversible actions | | Medium | 0.60–0.84 | Selected-info confirmation: "Just to confirm, you want to [action]?" | | Low | 0.40–0.59 | Disambiguation: top 2 intents as quick replies | | Very low | < 0.40 | FALLBACK_1 flow |

---

Section 3: Message UI Spec

Specs for every message type rendered in the chat window.

User Bubble

| Property | Value | |---|---| | Alignment | Right-aligned | | Max width | 320px (or 80% of container, whichever is smaller) | | Background | Brand accent color | | Text color | White (verify contrast ≥ 4.5:1 against accent) | | Border radius | 16px all corners, 4px bottom-right | | Padding | 12px 16px | | Timestamp | Show on tap/hover |

Bot Bubble

| Property | Value | |---|---| | Alignment | Left-aligned | | Max width | 32