@design-ai/cli 4.55.0

package/knowledge/conversational/chatbot-design.md

@@ -0,0 +1,312 @@
+<!-- hand-written -->
+---
+title: Chatbot design (rule-based, intent-driven, hybrid)
+applies_to: [chatbot, conversational, customer-support]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Chatbot design
+
+Chatbots are conversational text interfaces, often for customer support, FAQ deflection, lead capture, or transactional flows. This file covers traditional / intent-based / hybrid chatbots; for LLM-based AI chat (ChatGPT-style), see [`ai-chat-interfaces.md`](ai-chat-interfaces.md).
+
+Read [`conversational-ui-fundamentals.md`](conversational-ui-fundamentals.md) first.
+
+## Three architectures
+
+### 1. Rule-based / button-driven
+
+User clicks options; bot responds per scripted tree.
+
+```
+Bot:  "What can I help with?"
+       [Order status]  [Returns]  [Other]
+User: [taps "Order status"]
+Bot:  "Please share your order number."
+User: "ORD-12345"
+Bot:  [looks up; responds with status]
+```
+
+Pros: predictable, cheap, no AI.
+Cons: rigid; users escape via "Other" → human.
+
+### 2. Intent-based (NLP / classifier)
+
+User types free text; bot classifies intent and responds.
+
+```
+User: "Where's my package?"
+[Intent: ORDER_STATUS]
+Bot:  "Sure, let me check. What's your order number?"
+```
+
+Tools: Dialogflow, Rasa, Microsoft Bot Framework, Amazon Lex.
+
+Pros: more natural; users don't have to find buttons.
+Cons: misclassifies; needs training data; updates are work.
+
+### 3. Hybrid (intent + buttons + LLM fallback)
+
+Most modern chatbots:
+- Buttons for common flows.
+- Intent classification for typed input.
+- LLM fallback when intent unknown.
+- Human handoff when stuck.
+
+```
+User: [opens chat]
+Bot:  "Hi! What can I help with?"
+       [Order status]  [Returns]  [Other questions]
+
+User: "I want to know about your shipping policy"
+[Intent classified: SHIPPING_INFO; confidence 0.85]
+Bot:  "We ship within 1-3 days for domestic..."
+       [Track package]  [Talk to a human]
+```
+
+Pros: best of all. Cons: more engineering.
+
+## Anatomy of a chatbot UI
+
+```
+┌──────────────────────────┐
+│ Chat with Support      [×] │   ← header
+├──────────────────────────┤
+│  Bot: 안녕하세요! 무엇을      │
+│       도와드릴까요?         │
+│                          │
+│  [상품 문의] [반품 문의] [기타]│   ← suggested chips
+│                          │
+│  User: 배송 언제 와요?      │
+│                          │
+│  Bot: 주문 번호를 알려주세요.│
+│                          │
+│  [Bot is typing...]       │   ← typing indicator
+├──────────────────────────┤
+│ Type a message...   [Send]│   ← input
+└──────────────────────────┘
+```
+
+### Anatomy parts
+
+| Part | Purpose |
+| --- | --- |
+| Header | Branding, agent identity, close button |
+| Message list | Scrollable history of turns |
+| Bot bubble | Bot messages; typically left-aligned, distinct color |
+| User bubble | User messages; right-aligned, brand color |
+| Suggested chips | Quick reply buttons below bot message |
+| Typing indicator | "..." while bot processes |
+| Input field | Text entry + Send button |
+| Attachment | File / image upload (if supported) |
+
+## Conversation patterns
+
+### Greeting
+
+First message sets tone:
+
+| Style | Example |
+| --- | --- |
+| Helpful | "Hi! What can I help with today?" |
+| Branded | "Welcome to [Brand]. How can we make your day better?" |
+| Direct | "What's your question?" |
+| Korean (해요체) | "안녕하세요! 무엇을 도와드릴까요?" |
+
+Don't greet with feature list — overwhelms.
+
+### Quick replies
+
+Suggested next-step buttons. Reduces typing friction:
+
+```
+Bot: "What kind of issue?"
+     [Login problem]  [Payment]  [Bug report]
+```
+
+Quick replies should:
+- Be 3-5 max (more = scroll / paralysis).
+- Cover 80% of common cases.
+- Always include "Other / 기타" escape.
+
+### Forms in chat
+
+Long forms in chat = bad. Two patterns:
+
+**Inline questions** (one-at-a-time):
+
+```
+Bot: "What's your name?"
+User: "John"
+Bot: "Email?"
+User: "john@example.com"
+```
+
+OK for 2-4 fields. Above that, switch to form embed.
+
+**Form card** (embedded):
+
+```
+Bot: "Please complete this:"
+    ┌─────────────────────┐
+    │ [Name field]        │
+    │ [Email field]       │
+    │ [Issue type ▼]      │
+    │ [Description text]  │
+    │      [Submit]       │
+    └─────────────────────┘
+```
+
+For 5+ fields. Don't make user type "name", "email" via separate turns.
+
+### Lists / cards
+
+Bot can show rich card content (product list, search results):
+
+```
+Bot: "Found these for you:"
+
+[Product card 1]   [Product card 2]   [Product card 3]
+[image]            [image]            [image]
+[name]             [name]             [name]
+[price]            [price]            [price]
+[Buy]              [Buy]              [Buy]
+```
+
+Carousel-style or grid. Keep cards small; full detail behind tap.
+
+### Confirmation
+
+Before destructive / costly actions:
+
+```
+Bot: "Just to confirm: cancel order ORD-12345 for ₩50,000?"
+User: [Yes, cancel]  [No, keep it]
+```
+
+## Korean chatbot conventions
+
+- **Greeting**: "안녕하세요" + 해요체.
+- **Confirmation**: 합쇼체 sometimes for formality ("주문을 취소하시겠습니까?").
+- **Channel integration**: 카카오톡 채널 — bots common in KakaoTalk.
+- **Customer service** chatbots heavy in fintech, e-commerce, telecom.
+
+For 카카오톡 채널 bots:
+- Use Kakao's bot builder (i 챗봇 / Kakao Channel).
+- Persona consistency with the company's main brand.
+- Often hand off to human after 2-3 unresolved turns.
+- Operating hours displayed.
+
+## Empty states / no-match
+
+When bot doesn't understand:
+
+| Recovery | Phrase |
+| --- | --- |
+| Re-ask | "Sorry, could you rephrase?" |
+| Suggest | "I can help with: [Order] [Returns] [Returns]. Which?" |
+| Hand-off | "Let me connect you with a human." |
+| Search alternative | "Try asking differently or search our help center." |
+
+After 2-3 failures: hand off, don't keep cycling.
+
+## Human handoff
+
+Critical for chatbot UX:
+
+```
+Bot: "Let me get a person to help. One moment..."
+[connecting indicator]
+[Human agent joins]
+Agent: "Hi, I'm 김대리. How can I help?"
+```
+
+Design:
+- **Always available** — user can request "human" at any point.
+- **Context transfer** — agent sees the prior conversation; user doesn't repeat.
+- **Wait time displayed** — "Estimated wait: 3 minutes" / "Position 4 in queue".
+- **Off-hours behavior** — "We're closed; leave a message" or schedule callback.
+
+## Personality
+
+Bots should feel consistent:
+
+| Pattern | Use |
+| --- | --- |
+| **Branded persona** | "I'm Aera Bot, here to help." |
+| **Generic helpful** | Standard support tone |
+| **Anonymous** | Just "Bot" or company name |
+
+Don't pretend bot is a human. Disclose: "You're chatting with an AI assistant; switch to a human anytime."
+
+For Korean: 자기소개 ("저는 [브랜드] 봇이에요") common; helps relationship.
+
+## Persistent vs ephemeral
+
+| Type | Use |
+| --- | --- |
+| **Persistent** (history saved) | Customer support; multi-session; transactional |
+| **Ephemeral** (cleared on close) | One-shot help; non-sensitive |
+
+For persistent:
+- User can return and see history.
+- Cross-device sync.
+- Privacy: user can delete history.
+
+For ephemeral:
+- Less storage, simpler.
+- User can't refer to past.
+- Common for onboarding bots.
+
+## Notification UX
+
+For persistent chatbots that proactively message:
+
+- **Notification badge** on chat icon when new bot message.
+- **Sound / push** when bot messages user (configurable).
+- **Quiet hours** — don't bot-message at 3am.
+
+## Accessibility
+
+- **ARIA live region** for new messages (screen reader announces).
+- **Keyboard nav** — Tab to focus input; Up/Down to navigate messages.
+- **Read aloud** option for users who prefer voice.
+- **Adjustable text size**.
+- **Color contrast** for bubble bg / text.
+- **Suggested chips**: must be focusable + keyboard activatable.
+
+## Performance
+
+- **Streaming bot responses** when LLM-driven.
+- **Lazy-load message history** when long.
+- **Debounce typing indicator** updates.
+- **Optimistic send** — show user's message immediately, retry if failed.
+
+## Common chatbot mistakes
+
+- **Hiding human handoff** — users get trapped.
+- **Long preamble** — bot's first 3 messages before action.
+- **Confusing "I" / "we"** — pretending bot has feelings or memories it doesn't.
+- **Robotic confirmations** — "I have processed your request" vs "Done!"
+- **Not handling typos** — strict matching breaks.
+- **Forgetting context** within session.
+- **Spam-style proactive messages**.
+
+## Don't
+
+- Don't pretend the bot is human.
+- Don't make human handoff hidden / hard.
+- Don't write the bot's first message as a feature menu.
+- Don't run forms longer than 2-3 turns inline. Switch to form card.
+- Don't ignore typos / variations.
+- Don't push proactive messages outside business hours.
+- Don't hide what data the bot stores. Be transparent.
+
+## Cross-reference
+
+- [`knowledge/conversational/conversational-ui-fundamentals.md`](conversational-ui-fundamentals.md) — fundamentals
+- [`knowledge/conversational/voice-ui-patterns.md`](voice-ui-patterns.md) — voice
+- [`knowledge/conversational/ai-chat-interfaces.md`](ai-chat-interfaces.md) — LLM-based
+- [`knowledge/conversational/korean-voice-conventions.md`](korean-voice-conventions.md) — KR
+- [`examples/component-chat-interface.md`](../../examples/component-chat-interface.md) — chat UI spec

package/knowledge/conversational/conversational-ui-fundamentals.md

@@ -0,0 +1,299 @@
+<!-- hand-written -->
+---
+title: Conversational UI fundamentals (turn-taking, intents, context, modalities)
+applies_to: [conversational-ui, voice, chat, ai-chat]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Conversational UI fundamentals
+
+Conversational UI is design for back-and-forth exchanges. Voice assistants (Siri, Bixby), chatbots (customer support), AI chat (ChatGPT, Claude), and voice-controlled features in apps all share a foundation: a turn-taking exchange where each side has limited information about the other.
+
+This file is the foundation for [`voice-ui-patterns.md`](voice-ui-patterns.md), [`chatbot-design.md`](chatbot-design.md), [`ai-chat-interfaces.md`](ai-chat-interfaces.md), and [`korean-voice-conventions.md`](korean-voice-conventions.md).
+
+## Modalities
+
+| Modality | Examples |
+| --- | --- |
+| **Voice-only** | Smart speakers (Echo, Nest), in-car assistants |
+| **Voice + visual** | Phone assistants (Siri, Bixby) — voice input, visual response |
+| **Text-only chat** | SMS bots, Slack bots, in-app chatbots |
+| **Multimodal AI chat** | ChatGPT (text + image upload + voice), Claude (text + image) |
+| **Hybrid (voice → text)** | Voice search → text results |
+
+Each modality has different constraints. Voice can't show a list of 20 options; chat can't convey vocal warmth. Pick the modality that matches the task.
+
+## Turn-taking
+
+Conversation is **turn-based**:
+
+```
+User:    [request]
+System:  [response]
+User:    [follow-up or new request]
+System:  [response]
+```
+
+The system must:
+1. **Detect end of turn** — when has the user finished speaking / typing?
+2. **Respond appropriately** — relevant, paced, complete.
+3. **Yield turn** — signal "your turn" via prompt, cursor, or pause.
+
+For voice: end-of-utterance detection is hard. Pauses can be thinking, not finishing.
+
+For chat: end of turn is "Send" button or Enter. Easy.
+
+## Intents and slots (the canonical model)
+
+Most voice / chatbot systems classify input via **intents**:
+
+```
+User: "Set a timer for 5 minutes"
+
+Intent:        SET_TIMER
+Slots:         duration: 5 minutes
+```
+
+The system maps utterance → intent + parameters → action.
+
+| Concept | Definition |
+| --- | --- |
+| **Intent** | What the user wants (action / question type) |
+| **Slot / entity** | Specific values (time, amount, name) |
+| **Context** | Prior turns; user state; system state |
+| **Confidence** | How sure the system is about the interpretation |
+
+For LLM-based systems (ChatGPT, Claude): intents are implicit. The model interprets natural language end-to-end. But for product features (smart-home control, customer support), explicit intent + slot architecture is cheaper / more reliable.
+
+## Conversational design principles
+
+### 1. One thing per turn
+
+Don't ask for two pieces of info in one turn:
+
+✗ "What's your name and email?"
+✓ "What's your name?" → user answers → "And your email?"
+
+For visual chat: more info OK per turn (UI can hold a list). Voice: stricter.
+
+### 2. Confirmation for destructive / costly actions
+
+```
+User: "Delete all my photos"
+System: "Are you sure? This will delete 1,247 photos and can't be undone."
+User: "Yes"
+System: [does it]
+```
+
+Confirmation friction prevents accidents.
+
+### 3. Graceful failure
+
+When the system doesn't understand:
+
+| Bad | Good |
+| --- | --- |
+| "Error" | "Sorry, I didn't catch that. Could you say it differently?" |
+| Silence | Visible "Thinking..." indicator |
+| Repeat exactly the same prompt | Try a re-phrase or offer alternatives |
+
+After 2-3 failures: hand off to alternative (text input, human agent, settings menu).
+
+### 4. Context-awareness
+
+Remember context within a session:
+
+```
+User: "What's the weather in Seoul?"
+System: "Sunny, 12°C."
+User: "What about tomorrow?"   ← "tomorrow's weather in Seoul"
+System: "Tomorrow in Seoul: cloudy, 9°C."
+```
+
+Don't make the user repeat "Seoul" every turn.
+
+### 5. Be honest about capabilities
+
+Don't pretend to know more than you do:
+
+✗ "Yes, I can help you book a hotel" (when you can't)
+✓ "I can search hotels, but you'll need to book on the hotel's site."
+
+Misrepresentation breaks trust permanently.
+
+### 6. Respect user time
+
+- Voice: don't make users sit through long preamble.
+- Chat: don't message-bomb (5 short messages = noise; one combined message is better).
+- AI chat: stream tokens so user sees response forming, not just a blank screen.
+
+## Streaming responses
+
+For LLM-based chat, **stream the response token-by-token** rather than waiting for full completion:
+
+```
+[blank screen for 8 seconds] vs [text appears word-by-word starting at 200ms]
+```
+
+Streaming feels 10× faster even at the same total latency. Users see progress; mind fills in.
+
+For voice: stream audio similarly (start speaking before full response is generated, hide TTS latency).
+
+## Latency budgets
+
+| Modality | Acceptable latency |
+| --- | --- |
+| **Voice (assistant)** | < 1 second to first audio |
+| **Chat (typing indicator)** | < 500ms to typing indicator |
+| **Chat (first response token)** | < 1 second |
+| **AI chat full response** | streamed; total 5-30s OK |
+| **Wake word detection** | < 200ms |
+
+Beyond the budget: users assume broken / abandon.
+
+## Affordances
+
+For voice: how does the user know they can talk?
+- **Wake word** ("Hey Siri", "OK Google", "헤이 빅스비").
+- **Tap-to-talk** button (visible mic icon, button press, holding).
+- **Always listening** mode (controversial; privacy concerns).
+
+For chat:
+- **Persistent input field** at bottom.
+- **Suggested prompts** (chips above input) lower friction.
+- **"Type a message..." placeholder** with hint of capabilities.
+
+## Personality and voice
+
+Conversational UI has personality. Define:
+
+| Dimension | Examples |
+| --- | --- |
+| **Formality** | Casual ("Hey!") vs Formal ("How may I assist you?") |
+| **Verbosity** | Terse vs Discursive |
+| **Warmth** | Professional vs Warm |
+| **Humor** | None vs Dry vs Playful |
+| **Emoji** | Never vs Rare vs Frequent |
+
+For Korean fintech: 해요체 friendly; minimal humor; emoji rare.
+For Korean entertainment: 해체 / 해요체 casual; some humor; more emoji.
+For Korean B2B: 합쇼체 formal; no humor; no emoji.
+
+Pick deliberately and document. Don't let each engineer / writer pick differently.
+
+## Speech-to-text (STT) and text-to-speech (TTS)
+
+For voice UIs:
+
+### STT (recognition)
+
+- **Confidence scores** — each transcription has a confidence; below threshold = "Sorry, I didn't catch that".
+- **Language model bias** — train STT on domain (medical, legal, fintech terms).
+- **Noise robustness** — test in real environments (kitchen, car, street).
+- **Latency** — STT runs in background; final transcript at end of utterance.
+
+### TTS (synthesis)
+
+- **Voice choice** — male / female / neutral; per-language.
+- **Persona consistency** — use one voice per assistant; users build relationship.
+- **Prosody** — emphasis, pauses, intonation matter. SSML allows control.
+- **Latency** — pre-render common phrases; stream long ones.
+
+For Korean: Naver Clova, Samsung Bixby, Google TTS Korean, ElevenLabs Korean — all available. Test for naturalness; some still sound robotic.
+
+## Errors and recovery
+
+### Voice errors
+
+| Error | Recovery |
+| --- | --- |
+| Couldn't hear | "Sorry, could you say that again?" |
+| Heard but didn't understand | "I'm not sure what you meant. Did you mean X or Y?" |
+| Understood but can't do | "I can't do X. I can help with Y or Z." |
+| System failure | "Something went wrong. Try again later or say 'help' for options." |
+
+### Chat errors
+
+| Error | Recovery |
+| --- | --- |
+| Network error | Retry button + offline indicator |
+| AI response failed | "Couldn't generate response. Try again?" |
+| Rate limited | "You've sent a lot of messages. Wait a minute." |
+| Inappropriate content | "I can't help with that. Try rephrasing." |
+
+After repeated failures: offer alternative (text input, human agent, web link).
+
+## Privacy and consent
+
+Voice especially has privacy implications:
+
+- **Always-on listening** disclosure required.
+- **Recording retention** disclosure (where stored, how long, who can access).
+- **Opt-in for voice training** (using user audio to improve models).
+- **Wake word false-positive** transparency — Apple, Amazon publish how often Siri / Alexa false-trigger.
+
+For Korean market:
+- Personal Information Protection Act (개인정보보호법) compliance.
+- Consent flows for voice recording / storage.
+- Right-to-delete for voice data.
+
+For chat:
+- Disclose if conversations are stored / used for training.
+- Allow deletion.
+- Clear what's visible to humans (support agents, training reviewers).
+
+## Multilingual and code-switching
+
+Korean conversational UI often has mixed Korean + English:
+
+```
+User: "맥북 프로 16인치 가격 알려줘"
+User: "Schedule a meeting with 김철수 at 3pm"
+```
+
+System must:
+- Handle code-switching (mixed language input).
+- Preserve names / proper nouns in source language.
+- Choose response language (match user's primary, or per query).
+
+Modern LLMs handle this natively. Older intent-based bots struggle.
+
+## Accessibility
+
+### Voice UI accessibility
+
+- **Visual transcript** of voice (deaf / hard-of-hearing).
+- **Text alternative input** for users who can't speak (motor disability, voice issues).
+- **Visual feedback** of audio (listening, processing, responding states).
+- **Adjustable TTS speed**.
+
+### Chat UI accessibility
+
+- Standard text accessibility (contrast, screen reader support).
+- Skip-to-content (long histories).
+- ARIA live regions for new messages.
+- Keyboard nav for messages (Up / Down to navigate).
+
+For multimodal: provide both modalities. Voice-only excludes deaf users; text-only excludes low-vision / motor-impaired users.
+
+## Don't
+
+- Don't treat voice like a typed-command interface ("syntax errors" don't translate).
+- Don't ignore confidence scores — low-confidence guesses are worse than asking.
+- Don't bury error recovery in obscure phrases.
+- Don't break context within a session.
+- Don't lie about capabilities.
+- Don't force users into long preamble before action.
+- Don't leak privacy ("Did you say X?" loud in public is awkward).
+- Don't ship without graceful degradation when backend is down.
+
+## Cross-reference
+
+- [`knowledge/conversational/voice-ui-patterns.md`](voice-ui-patterns.md) — voice-specific
+- [`knowledge/conversational/chatbot-design.md`](chatbot-design.md) — text chat
+- [`knowledge/conversational/ai-chat-interfaces.md`](ai-chat-interfaces.md) — LLM chat
+- [`knowledge/conversational/korean-voice-conventions.md`](korean-voice-conventions.md) — KR
+- [`knowledge/i18n/korean-document-style.md`](../i18n/korean-document-style.md) — honorific level
+- [`knowledge/a11y/keyboard-and-focus.md`](../a11y/keyboard-and-focus.md) — keyboard a11y