@design-ai/cli 4.55.0

package/knowledge/conversational/korean-voice-conventions.md

@@ -0,0 +1,281 @@
+<!-- hand-written -->
+---
+title: Korean voice and conversational conventions
+applies_to: [korean, voice, chatbot, conversational, kr-market]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Korean voice and conversational conventions
+
+Korean voice and chat UIs have specific market patterns, regulatory requirements, and language conventions that differ from Western defaults.
+
+Read [`conversational-ui-fundamentals.md`](conversational-ui-fundamentals.md) first.
+
+## Korean voice assistant landscape
+
+| Product | By | Strength |
+| --- | --- | --- |
+| **Bixby** | Samsung | Default on Galaxy phones; deep Korean language support; Bixby Capsules for 3rd-party integration |
+| **Clova / 클로바** | Naver | Smart speakers (Friends, Wave, Slate); HyperCLOVA-powered |
+| **NUGU** | SK Telecom | Smart speakers (NUGU Mini, Candle); SKT services integration |
+| **GiGA Genie / 기가지니** | KT | Smart speakers; KT services |
+| **Kakao i** | Kakao | Smart speaker (Kakao Mini); Kakao services (Talk, Map, T) |
+| **HyperCLOVA X** | Naver | Korean-first LLM; conversational AI |
+| **Apple Siri** | Apple | iOS; Korean support adequate |
+| **Google Assistant** | Google | Android; Korean strong |
+| **Amazon Alexa** | Amazon | Limited Korean market |
+
+For B2C apps targeting Korean users: prioritize **Bixby** (Samsung's market share in KR is large), **Clova** (Naver ecosystem reach), and **Google Assistant** (Android global).
+
+## Honorific level (존댓말)
+
+The most important Korean conversational design choice:
+
+| Level | Suffix | Use |
+| --- | --- | --- |
+| **합쇼체** | ~ㅂ니다 / ~습니다 | Formal; banking, government, premium B2B |
+| **해요체** | ~해요 / ~예요 | Friendly polite; consumer apps, KakaoTalk channel bots |
+| **해체** | ~해 / ~야 | Casual; rare in commercial UI; kid / friend characters |
+
+### Default for product type
+
+| Product | Default |
+| --- | --- |
+| Banking app voice | 합쇼체 |
+| Fintech consumer (Toss, KakaoBank) | 해요체 |
+| E-commerce chatbot | 해요체 |
+| Customer support (formal company) | 합쇼체 |
+| Customer support (casual brand) | 해요체 |
+| Kids' content | 해요체 (slightly softer) |
+| Government / civic | 합쇼체 |
+| Smart speaker (Bixby, NUGU) | 해요체 |
+| Voice navigation (T-map, Naver Map) | 해요체 |
+
+### Don't mix levels
+
+Switching between 해요체 and 합쇼체 in one bot's responses sounds inconsistent / sloppy. Pick one and apply throughout.
+
+Exception: agent-handoff transitions where company voice (합쇼체) replaces bot voice (해요체) is acceptable as a deliberate handoff signal.
+
+### Mixed in long-form content
+
+For longer responses (FAQ answers, terms), 합쇼체 sometimes fits even when surrounding chat is 해요체:
+
+```
+User: 환불은 어떻게 받나요?
+
+Bot: (해요체 conversational layer)
+환불 절차를 안내해 드릴게요!
+
+(합쇼체 formal section, often quoted/styled differently)
+"주문일로부터 7일 이내에 반품 신청을 하셔야 합니다.
+반품 신청 후 7일 이내에 배송이 회수되며..."
+
+(다시 해요체)
+더 궁금한 점이 있으면 알려주세요!
+```
+
+## Greeting patterns
+
+| Time of day | Greeting |
+| --- | --- |
+| Anytime | 안녕하세요! |
+| Morning | 좋은 아침이에요! |
+| Late evening | 늦은 시간 죄송해요 (acknowledge after-hours) |
+
+For chatbot greeting:
+- "안녕하세요! [브랜드] 챗봇이에요. 무엇을 도와드릴까요?"
+- "어떤 도움이 필요하세요?"
+- "[브랜드]에 오신 것을 환영해요!"
+
+For voice assistant: short, no preamble — "네, 듣고 있어요" or just chime.
+
+## Confirmation phrases
+
+| Action | Korean |
+| --- | --- |
+| Affirmation | "네", "확인했어요", "알겠어요" |
+| Confirmation request | "...하시겠어요?" / "...할까요?" |
+| Reassurance | "잠시만 기다려 주세요" / "확인 중이에요" |
+| Apology | "죄송해요" / "죄송합니다" / "다시 말씀해 주시겠어요?" |
+| Thanks | "감사해요" / "감사합니다" |
+
+### Apology when bot doesn't understand
+
+```
+"죄송해요, 잘 못 알아들었어요. 다시 말씀해 주시겠어요?"
+"제가 잘 이해하지 못했어요. 다른 방식으로 말씀해 주시겠어요?"
+"음, 잘 모르겠어요. 도움이 필요하시면 [메뉴/연락처] 확인해 주세요."
+```
+
+## Code-switching (mixed Korean + English)
+
+Korean speakers often code-switch:
+
+```
+"맥북 프로 16인치 가격 알려줘"        ← English brand + Korean
+"Schedule a meeting with 김철수"      ← Korean name in English request
+"오늘 저녁에 LA에 도착해"             ← English city in Korean
+```
+
+Bot must:
+- Handle mixed-language input.
+- Preserve proper nouns in source language.
+- Choose response language (default: match user's primary).
+
+LLM-based bots (HyperCLOVA, GPT-4, Claude) handle this natively. Older intent-based bots struggle.
+
+## Korean-specific speech patterns
+
+### 반말 (informal) detection
+
+If user uses 반말 ("말해줘"), the bot must NOT respond in matching 반말 — looks rude. Stay in 해요체 / 합쇼체 always.
+
+If brand voice is intentionally casual (Toss-style "money character" voice), 해요체 is the friendly endpoint.
+
+### Honorifics for the user
+
+Bot should use 님 to address the user:
+- "고객님 안녕하세요"
+- "[Username]님, 주문이 도착했어요!"
+- 회원님 / 사용자님 / 고객님 (varies by brand)
+
+### Not addressing the user
+- "주문이 도착했어요" (good — passive)
+- "당신의 주문이 도착했어요" (bad — 당신 is impersonal / formal-distant)
+
+당신 is rarely used in Korean commercial UI. Avoid.
+
+## Voice and TTS in Korean
+
+### Voice characteristics
+
+Most Korean assistants default to:
+- **Female**, gentle.
+- 20s-30s perceived age.
+- Clear enunciation.
+- 해요체 register.
+
+Reasons:
+- Cultural expectation (legacy from Japanese / Korean GPS / station announcements).
+- Perceived warmth / approachability.
+- Test results (most users prefer female voice for assistants in studies).
+
+Modern apps offer choice: male voices, neutral voices, celebrity voices (premium).
+
+### TTS quality
+
+| Service | Korean TTS quality |
+| --- | --- |
+| **Naver Clova Voice** | Strong; many voice options |
+| **Samsung Bixby TTS** | Strong; Galaxy default |
+| **Google Cloud TTS** | Good; multiple Korean voices |
+| **ElevenLabs** | Improving; voice cloning for Korean |
+| **Apple Siri TTS** | Adequate; iOS only |
+| **AWS Polly** | Adequate |
+| **Typecast** | Korean-native; AI voice for content creation |
+
+For brand voice: use Clova or Bixby for Korean-first; ElevenLabs for cloning.
+
+### Pronunciation challenges
+
+Hangul → speech challenges:
+- **Number reading**: 1,000 = "천" or "1천" — context-dependent.
+- **Date format**: "5월 8일" not "5/8".
+- **Time**: "3시" not "3:00".
+- **Currency**: "5,000원" → "오천 원" (read), not "5,000 won".
+- **English brand names**: "Coca-Cola" → "코카콜라" or "코카-콜라" depending.
+- **Acronyms**: read letter-by-letter or as Korean (e.g., NASA → "나사").
+
+Modern Korean TTS handles most of this; test edge cases.
+
+## STT (speech-to-text) Korean
+
+Quality:
+- **Naver Clova Speech** — strong for Korean.
+- **Bixby STT** — strong; Galaxy ecosystem.
+- **Google Cloud Speech** — strong; supports code-switching.
+- **OpenAI Whisper** — open-source; excellent Korean.
+- **Apple speech recognition** — adequate.
+
+Issues:
+- **Dialect** (Busan, Jeju) — quality varies; Whisper handles best.
+- **Noise** — Korean characters are dense; mishears more common in noisy environments.
+- **Code-switching** — depends on STT model.
+- **Numbers in speech** — context-dependent ("이천이십사 년" = 2024).
+
+## Korean regulatory
+
+### Personal Information Protection Act (개인정보보호법)
+
+For voice / chat that collects personal data:
+- **Consent required** for collection.
+- **Disclosure** of what's collected, why, how long stored, with whom shared.
+- **Right to delete** voice recordings + chat history.
+- **Encrypted storage** for sensitive data.
+
+Voice assistants must disclose recording in privacy policy. Some require explicit "always listening" opt-in.
+
+### Information network Act (정보통신망법)
+
+For chatbot interactions:
+- **Same rules as email marketing** if chatbot proactively pushes offers.
+- **광고 disclosure** if chatbot promotes paid content.
+
+### Financial product chatbot (자본시장법 / 금융소비자보호법)
+
+If bot discusses investments / financial products:
+- **Risk disclosure** required.
+- **Advice qualifications** — bot can't give personalized investment advice without licensing.
+- **Consumer protection** disclosures.
+
+Korean fintech bots typically include extensive disclaimer text.
+
+## KakaoTalk channel chatbot specifics
+
+KakaoTalk is dominant in Korea; many businesses run chatbots there:
+
+- Use Kakao i Open Builder OR Kakao Channel admin tools.
+- 답변 시간 (response time hours) displayed.
+- Persistent menu (always-visible bottom bar) with categories.
+- Auto-greeting on first message.
+- Can hand off to human within KakaoTalk.
+
+Design:
+- Stick to KakaoTalk message types (text, image, card, list).
+- Don't replicate native UI in card format — looks broken.
+- Test on KakaoTalk mobile app primarily (most users there).
+
+## Common Korean chatbot / voice mistakes
+
+- **Mixed honorific levels** — 해요 + 합쇼 in same conversation.
+- **Wrong register for brand** — bank using 해체 / casual register.
+- **Direct translation from English** — sounds unnatural.
+- **당신 used as "you"** — too formal-distant.
+- **No 님 attached to user** — feels rude.
+- **English brand names not localized** — "Apple Pay" vs "애플 페이" inconsistency.
+- **TTS mispronouncing user names** — verify common names.
+- **Long preamble** — Korean voice users want directness.
+
+## Don't
+
+- Don't mix 해요체 and 합쇼체 within one bot's voice. Pick one.
+- Don't translate Western chatbot scripts word-for-word. Adapt to Korean phrasing.
+- Don't use 당신 as default "you". Use 고객님 / 회원님 / username + 님.
+- Don't ignore code-switching. Korean users mix English freely.
+- Don't ship voice in Korean without testing TTS pronunciation on brand / product names.
+- Don't omit 개인정보보호법 disclosures for data-collecting voice / chat.
+- Don't use 반말 in commercial UI even if user uses it. Stay polite.
+- Don't make Bixby Capsule integration an afterthought for Samsung-priority audience.
+
+## 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/chatbot-design.md`](chatbot-design.md) — chatbot
+- [`knowledge/conversational/ai-chat-interfaces.md`](ai-chat-interfaces.md) — AI chat
+- [`knowledge/i18n/korean-document-style.md`](../i18n/korean-document-style.md) — honorific level
+- [`knowledge/i18n/korean-typography.md`](../i18n/korean-typography.md) — Hangul typography
+- [`knowledge/patterns/email-design.md`](../patterns/email-design.md) — KR ad disclosure

package/knowledge/conversational/voice-ui-patterns.md

@@ -0,0 +1,297 @@
+<!-- hand-written -->
+---
+title: Voice UI patterns (smart speakers, in-app voice, IVR)
+applies_to: [voice-ui, smart-speaker, ivr, voice-assistant]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Voice UI patterns
+
+Voice user interfaces (VUIs) — smart speakers (Echo, Nest, NUGU), phone assistants (Siri, Google Assistant, Bixby, Clova), in-app voice features, IVR (interactive voice response phone systems), in-car voice control.
+
+Read [`conversational-ui-fundamentals.md`](conversational-ui-fundamentals.md) first.
+
+## Voice-only vs voice + visual
+
+| Modality | Constraints |
+| --- | --- |
+| **Voice-only** (smart speaker, in-car) | No visual; no list of options; rely on memory |
+| **Voice + visual** (phone assistant) | Voice input, visual response; richer feedback |
+| **Voice + ambient screen** (Echo Show) | Hybrid; visual supports voice |
+
+Pick the lowest common denominator. If your skill must work on Echo (audio only), don't design assuming visual.
+
+## Five voice UI patterns
+
+### 1. Wake word activation
+
+```
+User: "Hey Siri, set a timer for 5 minutes."
+```
+
+Wake words: "Hey Siri", "OK Google", "Alexa", "Hey Bixby", "Hi Clova", "Hey NUGU".
+
+Design:
+- **Auditory feedback** when wake word detected (chime, light pulse).
+- **Visual feedback** for visual-capable devices (animation, listening indicator).
+- **Timeout** — wake state lasts 6-10s; if no speech, returns to idle.
+- **False positive handling** — if wake fires accidentally, user can say "nevermind" or just stay silent.
+
+### 2. Tap-to-talk
+
+```
+[User taps mic icon]
+[Holds while speaking]
+[Releases when done]
+```
+
+Or push-and-release (continuous listen until silence).
+
+Design:
+- **Visual press feedback** during listening.
+- **Visualization** of audio level (waveform or pulse).
+- **Cancel** option (slide off button or back press).
+- **Auto-end** on silence (1-2 seconds of quiet).
+
+### 3. Conversational follow-up
+
+After response, briefly remain listening for follow-up:
+
+```
+User: "What's the weather?"
+System: "62°F, sunny."
+[brief pause; mic stays open]
+User: "What about tomorrow?"
+System: "Tomorrow: 58°F, cloudy."
+```
+
+Reduces "Hey Siri" repetition. Risk: false-trigger from background noise.
+
+### 4. Multi-turn dialogue
+
+```
+User: "Book a flight to Seoul."
+System: "Sure. What dates?"
+User: "Next Friday, returning Sunday."
+System: "Departing from where?"
+User: "San Francisco."
+System: "Found 12 flights. Cheapest is..."
+```
+
+System tracks slot-filling progress; asks only what's missing.
+
+For complex tasks (flight booking, meal planning): multi-turn is necessary. Keep turns short; confirm at end.
+
+### 5. Voice search → visual results
+
+```
+User: "Find me Korean restaurants nearby."
+[voice → text → search query]
+[visual results displayed]
+```
+
+Voice as input modality only; results are visual. Common in mobile apps (search by voice, browse results).
+
+## Smart speaker UX (audio-only)
+
+For Echo, Nest, etc.:
+
+### Information density
+
+You can convey ~15-30 words before user attention drifts. Be concise:
+
+✗ "I found 5 Korean restaurants nearby. The first is Han Yang at 123 Main Street, with a 4.5-star rating, $$$ price, open until 10pm. The second is Bibim, located at 456..."
+
+✓ "I found 5 Korean spots. Top result: Han Yang, 4.5 stars, half a mile away. Want details on it?"
+
+### Lists
+
+| Length | Pattern |
+| --- | --- |
+| 1 result | "I found one: X." |
+| 2-3 results | Read all briefly: "I found three. First: X. Second: Y. Third: Z." |
+| 4-7 results | Read 2-3, ask: "Want to hear more?" |
+| 8+ results | Summarize: "I found 12. Want me to read them?" |
+
+Don't read 12-item lists by default.
+
+### Audio cues
+
+- **Earcon** (short tone) for wake / acknowledgment.
+- **Different chime** for error vs success.
+- **Voice timbre** consistent across all responses.
+
+### Proactive notifications
+
+Smart speakers can announce:
+- Reminders ("Your package arrived").
+- Notifications ("Email from John").
+
+Risks:
+- Noisy household: announcements during conversation = rude.
+- Privacy: "Email from John about your medical results" announced loudly.
+
+Design:
+- **Quiet hours** setting.
+- **Notification style** option (silent vs chime vs full announcement).
+- **Privacy filter** — sensitive content not announced.
+
+## Phone assistant UX (voice + visual)
+
+Siri, Google Assistant, Bixby on phones:
+
+### Visual response anatomy
+
+```
+┌─────────────────────────┐
+│  [User: "What's the     │
+│   weather in Seoul?"]   │   ← transcribed user input
+├─────────────────────────┤
+│                         │
+│  [Sunny icon]           │
+│  Seoul: 12°C            │   ← visual response
+│  Sunny                  │
+│  H: 15°C  L: 5°C        │
+│                         │
+│  [More details ↓]       │
+└─────────────────────────┘
+```
+
+Voice spoken simultaneously: "Sunny, 12 degrees in Seoul."
+
+### Action buttons
+
+Voice can suggest actions; visual provides buttons:
+
+```
+"I found a cafe nearby. Want directions?"
+[Get directions]  [Call]  [Save for later]
+```
+
+User can voice-respond ("Yes") or tap.
+
+## In-car voice UX
+
+Voice in cars (Apple CarPlay, Android Auto, native):
+
+### Constraints
+
+- **Eyes on road**: minimal visual demand.
+- **Hands on wheel**: voice or steering-wheel button.
+- **Noisy environment**: STT robustness + clear TTS.
+- **Distraction limits**: regulated in some jurisdictions.
+
+### Patterns
+
+- **Steering wheel button** activation (push-to-talk, no wake word).
+- **Audio-only response by default**; visual for confirmation.
+- **Single voice command per task**: "Call Mom" not "Open contacts and find Mom".
+
+## IVR (Interactive Voice Response — phone systems)
+
+"For sales, press 1. For support, press 2."
+
+Largely deprecated for chatbots / live agents in 2024+, but still common.
+
+### Best practices
+
+- **Skip option** to a human at any time ("Press 0 for an operator").
+- **Avoid deep menus** (max 3-4 levels).
+- **Repeat option** at end of menu.
+- **Caller ID-based** routing where possible (don't ask for account number you already know).
+
+For Korean banking IVR: typically Korean voice menus, multi-tier, often with separate path for VIP customers.
+
+## Korean voice assistants
+
+| Assistant | By | Notes |
+| --- | --- | --- |
+| **Bixby** | Samsung | Default on Galaxy phones; Korean strong |
+| **Clova / 클로바** | Naver | Smart speakers (Friends, Wave); Korean services |
+| **NUGU** | SKT | Smart speakers (NUGU Mini, Candle); SKT services |
+| **GiGA Genie / 기가지니** | KT | Smart speaker; KT services |
+| **Kakao i** | Kakao | Smart speaker (Kakao Mini); Kakao services |
+| **Siri / Google Assistant / Alexa** | International | Korean support of varying quality |
+
+Korean assistants integrate with Korean services (Naver search, Kakao Talk, KT Olleh, SKT services). Western assistants integrate with global services (Apple, Google, Amazon).
+
+For Korean B2C apps: voice features should consider Bixby Capsule integration if Samsung-priority audience.
+
+## Voice + accessibility
+
+Voice UIs help motor / vision accessibility but exclude others:
+
+| Disability | Voice UI helpful? |
+| --- | --- |
+| Motor (typing hard) | Yes — voice replaces keyboard |
+| Vision (can't see screen) | Yes — voice replaces visual |
+| Deaf / hard-of-hearing | No — must offer text alt |
+| Speech (can't speak) | No — must offer text alt |
+| Cognitive (slow processing) | Variable — depends on pacing options |
+
+Always offer text alternative input AND visual output. Voice can be primary but never exclusive.
+
+## TTS voice selection
+
+For your assistant's voice:
+
+| Choice | Use |
+| --- | --- |
+| **Single voice** | Most consistent; users build relationship |
+| **Voice options** (male / female / neutral) | More inclusive; users pick |
+| **Voice cloning** (custom brand voice) | Distinctive but expensive + ethics |
+| **Multilingual same-voice** | Consistent across locales |
+
+For Korean assistants: typically single-voice default; Korean female warm tone common (Bixby default).
+
+## SSML for prosody control
+
+Speech Synthesis Markup Language adjusts TTS:
+
+```xml
+<speak>
+  Hello! <break time="500ms"/> Today is
+  <emphasis level="strong">Tuesday</emphasis>.
+  The temperature is <say-as interpret-as="cardinal">72</say-as> degrees.
+</speak>
+```
+
+Useful for:
+- Pauses / breaks.
+- Emphasis on key words.
+- Numbers vs digits ("1.0" → "one point zero" vs "one dot zero").
+- Dates: "2024-05-08" → "May 8, 2024" or "5월 8일".
+
+Korean SSML same syntax; supports Korean prosody marks.
+
+## Voice UI common mistakes
+
+- **Too verbose responses** — users abandon.
+- **Lists too long** — voice can't show 12 results.
+- **No fallback** when STT fails repeatedly.
+- **Wake word false positives** disrupting other audio.
+- **Privacy violations** announcing sensitive content.
+- **Inconsistent persona** (one response formal, next casual).
+- **Ignoring code-switching** (mixed Korean / English) for Korean users.
+
+## Don't
+
+- Don't make voice the only way to do things. Always offer touch / text alt.
+- Don't read 10-item lists by default. Summarize and offer to read.
+- Don't ignore false positives — wake words are noisy.
+- Don't drone on. Concise wins.
+- Don't leak privacy via voice ("Email from doctor about test results").
+- Don't break the "Hey Siri" ↔ "follow-up" expectation. Be consistent.
+- Don't ship one voice for all locales. Localize per-language.
+- Don't use only audio for critical actions (confirm with visual + voice when device permits).
+
+## Cross-reference
+
+- [`knowledge/conversational/conversational-ui-fundamentals.md`](conversational-ui-fundamentals.md) — fundamentals
+- [`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/a11y/keyboard-and-focus.md`](../a11y/keyboard-and-focus.md) — alt access
+- [`examples/component-voice-input.md`](../../examples/component-voice-input.md) — voice input spec