@design-ai/cli 4.55.0

package/knowledge/video/in-product-video.md

@@ -0,0 +1,277 @@
+<!-- hand-written -->
+---
+title: In-product video (onboarding, help, explainers)
+applies_to: [video, in-product, onboarding, help]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# In-product video
+
+Video inside the product itself: onboarding tutorials, help videos, feature explainers, embedded demos. Different rules from marketing video — these viewers already chose your product; they want help, not seduction.
+
+Read [`video-fundamentals.md`](video-fundamentals.md) first.
+
+## Three categories
+
+### 1. Onboarding video (first-run)
+
+Shown to new users during signup or first session.
+
+| Spec | Target |
+| --- | --- |
+| Length | 30-90 seconds |
+| Format | 16:9 desktop / 9:16 mobile |
+| Click | Skippable; optional |
+| Audio | Optional (often muted with captions) |
+| Goal | Get user to first value moment |
+
+Structure:
+```
+0:00-0:05  Welcome (warm; 2-3 word headline)
+0:05-0:30  What this product does (1-2 sentences max in caption)
+0:30-0:60  How to do the first thing (specific action)
+0:60-0:90  What's next (CTA: try it)
+```
+
+Don't over-explain. Onboarding video is supplemental; the actual product walkthrough does the teaching.
+
+### 2. Help video (in-context)
+
+Shown when user is stuck or asks for help. Embedded in help articles, settings pages, error states.
+
+| Spec | Target |
+| --- | --- |
+| Length | 30-120 seconds (focused on one task) |
+| Format | 16:9 mostly; 9:16 for mobile-only flows |
+| Click | Always playable; controls visible |
+| Audio | Voiceover preferred; captions mandatory |
+| Goal | User completes the task they're stuck on |
+
+Structure:
+```
+0:00-0:05  What this video shows
+0:05-end   Task steps in order, each with brief voiceover
+0:end      "Try it now" or close
+```
+
+Pace: brisk for power users; deliberate for beginners. Can produce 2 versions.
+
+### 3. Feature explainer / changelog video
+
+Promotes a new feature or update. Lives in product changelog, release notes, in-app announcements.
+
+| Spec | Target |
+| --- | --- |
+| Length | 15-60 seconds |
+| Format | 16:9 |
+| Click | Click-to-play; auto-play loop variant for hero |
+| Audio | Optional |
+| Goal | User understands new capability + tries it |
+
+Structure:
+```
+0:00-0:05  What's new (feature name + benefit)
+0:05-0:30  How it works (short demo)
+0:30-end   CTA (try it, learn more)
+```
+
+## Production approach
+
+### Screen recording vs filmed
+
+Most in-product video is **screen-recorded** (capturing actual UI):
+- **Tools**: Loom, ScreenFlow, OBS, Riverside, CleanShot X.
+- **Pros**: cheap, fast, accurate.
+- **Cons**: Less polished; cursor / UI quirks visible.
+
+Some is **filmed** (actor + product on phone / laptop):
+- **Tools**: full production setup.
+- **Pros**: more emotional, brand-feeling.
+- **Cons**: expensive, dates fast (UI changes → reshoot).
+
+**Hybrid**: filmed cutaways + screen-recorded core. Best of both.
+
+### Screen recording tips
+
+- **Resolution**: record at 2× display resolution; deliver at 1×.
+- **Cursor**: highlight (yellow circle, color trail) — visible at small sizes.
+- **Click feedback**: animate cursor click (Loom does this automatically).
+- **Zoom on detail**: zoom into the relevant UI region; don't show whole screen at small video size.
+- **Hide irrelevant UI**: minimize taskbar, hide dock, clean desktop.
+- **Realistic data**: use representative names, not "Test User #1".
+- **Korean data**: use Korean names / addresses for KR audiences (don't show "John Doe" in a Korean app).
+
+### Voiceover for in-product video
+
+- **Korean primary** for KR audience.
+- **Pace**: slightly slower than marketing — viewers are following along.
+- **Tone**: helpful, neutral; not salesy.
+- **Female / male voice**: pick one and consistent across the product video library.
+
+For AI voice: ElevenLabs / 클로바보이스 produce decent Korean output. Always review for pronunciation of brand / product names.
+
+### No-voice variant
+
+Some in-product video has no voice — just visual + on-screen text.
+
+| Pros | Cons |
+| --- | --- |
+| Faster production (no recording) | Limited information density |
+| Localizable easily (text only) | Can feel sterile |
+| Plays in muted contexts | Requires clear visual direction |
+
+For multi-region products: text-only might be better than recording 5 language voiceovers.
+
+## Embedded video player UX
+
+When video is embedded in product UI:
+
+```
+┌──────────────────────────────────────┐
+│  [Video thumbnail or first frame]    │
+│                                      │
+│        ▶ Play                        │
+│                                      │
+│  Duration: 0:45    [CC] [Speed]      │
+└──────────────────────────────────────┘
+```
+
+Controls users expect:
+- **Play / pause**.
+- **Progress bar** (seekable).
+- **Volume** (or muted-by-default toggle).
+- **Captions toggle** (default ON for product video).
+- **Speed control** (1x, 1.25x, 1.5x, 2x — power users skim).
+- **Fullscreen**.
+- **Close / dismiss** (if modal-embedded).
+
+For minimal UX: at least play/pause + caption toggle.
+
+See [`examples/component-video-player.md`](../../examples/component-video-player.md) for spec.
+
+## Lazy-loading video in-product
+
+In-product videos shouldn't slow down the app:
+
+```tsx
+// Show poster only; load video on click or on visibility
+<HelpVideoEmbed
+  poster="/help-videos/onboarding-poster.jpg"
+  src="/help-videos/onboarding.mp4"
+  loadOn="click"   // or "visible" via IntersectionObserver
+/>
+```
+
+For modal-embedded videos: lazy-load when modal opens, not when product mounts.
+
+## Captions for in-product video
+
+**Captions mandatory** for any in-product video with speech. Reasons:
+
+- Accessibility (deaf / hard-of-hearing users).
+- Sound-off viewing (open offices, public, late night).
+- Non-native speakers (Korean → English content).
+- Indexing (caption text searchable).
+
+Default: captions ON for product video. User can toggle off if preferred (remember preference).
+
+## Variable speed for power users
+
+Allow 1x, 1.25x, 1.5x, 2x. Power users skim help videos at 1.5-2x. Don't force them to wait.
+
+## Localization
+
+For multi-region products:
+
+- **English original** + Korean / Japanese / etc. caption tracks.
+- OR **separate videos per language** (different voiceover, captions).
+- OR **no-voice + localized text overlay** (cheapest scaling).
+
+Choose based on:
+- Audience size per region.
+- Voice / brand consistency requirements.
+- Budget.
+
+## Korean in-product video
+
+- **자막 ON by default**.
+- **Korean voiceover** for KR audience.
+- **Reach pace**: slightly slower than marketing video.
+- **Brand voice**: 해요체 (~해요) for friendly products; 합쇼체 for B2B / financial.
+- **Korean data in screen recordings** (Korean names, KRW currency).
+
+For Korean fintech in-product video: 해요체, female voice (Toss-style), captioned, brand-color CTA at end.
+
+## Updating videos when product changes
+
+In-product videos date fast. UI changes → video shows old UI → confused user.
+
+Strategies:
+- **Stylized animation** (After Effects mockup) instead of screen recording — doesn't date with UI changes.
+- **Periodic refresh schedule** (every 6 months: review + reshoot).
+- **Versioned URLs** so old videos can be archived without breaking links.
+- **Track which UI flows are video-documented** so you know what to update.
+
+For SaaS with rapid UI iteration: animation-based explainer videos > screen recordings.
+
+## Performance considerations
+
+- **Compress aggressively** — in-product video doesn't need 4K.
+- **Provide poster** — first paint shows poster, video loads behind.
+- **HLS / adaptive bitrate** for longer videos (5+ minutes) — players adjust quality based on connection.
+- **CDN delivery** — Cloudflare, Fastly, AWS CloudFront, or platform native (YouTube embed for some cases).
+
+## Accessibility
+
+- **Captions**: required.
+- **Transcripts**: post the full transcript for help articles (text-searchable, screen-reader-friendly).
+- **Audio descriptions**: for video where critical info is visual-only.
+- **Don't auto-play with sound**: users with sensitive ears, in shared spaces, abandon.
+- **Keyboard controls**: spacebar to play/pause; M to mute; arrows to seek.
+- **Pause control**: for any auto-play.
+
+## Common in-product video mistakes
+
+- **Too long** — users skip.
+- **Outdated UI** in screen recording — confused users.
+- **No captions** — accessibility fail + 80% miss the message.
+- **Auto-play with sound** — disorienting; abandoned.
+- **Video where text would do** — reading is faster for many tasks.
+- **Salesy tone** — these are existing users, not prospects.
+- **Generic stock footage** — feels off-brand for a help video.
+
+## When NOT to use video
+
+| Situation | Better alternative |
+| --- | --- |
+| Linear text task ("how to delete") | Text + screenshot |
+| Search / scan-friendly content | Text article (skimmable) |
+| Multi-step process where users go at their own pace | Annotated screenshots |
+| Reference (looked up later) | Text + animated GIF |
+| Common error explanation | Inline help in UI |
+
+Use video when:
+- Spatial / motion is hard to describe in text (drag-and-drop, gesture).
+- Emotional moment (welcome, celebration).
+- Walkthrough where seeing > reading.
+
+## Don't
+
+- Don't ship a 5-minute onboarding video. Cut to 60 seconds.
+- Don't skip captions. Mandatory.
+- Don't auto-play with sound.
+- Don't show outdated UI in screen recording. Update when product updates.
+- Don't use video for everything. Text + screenshots are often better.
+- Don't put video in time-critical flows (checkout, payment) — slows users.
+- Don't lock features behind "watch the video first" — let users skip.
+
+## Cross-reference
+
+- [`knowledge/video/video-fundamentals.md`](video-fundamentals.md) — encoding, captions
+- [`knowledge/video/marketing-video.md`](marketing-video.md) — marketing-side
+- [`knowledge/video/social-and-short-form.md`](social-and-short-form.md) — short-form
+- [`knowledge/video/korean-video-conventions.md`](korean-video-conventions.md) — KR
+- [`knowledge/patterns/technical-writing.md`](../patterns/technical-writing.md) — when text is better
+- [`examples/component-video-player.md`](../../examples/component-video-player.md) — player component

package/knowledge/video/korean-video-conventions.md

@@ -0,0 +1,247 @@
+<!-- hand-written -->
+---
+title: Korean video conventions (KR market, broadcast standards, ad disclosure)
+applies_to: [video, korean, kr-market, broadcast, advertising]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Korean video conventions
+
+Korean video has specific market conventions, regulatory requirements (broadcast standards 방송통신심의위원회, ad disclosure 표시광고법), and platform usage patterns that differ from Western markets.
+
+This file covers what's specific to Korean video. Read [`video-fundamentals.md`](video-fundamentals.md) first.
+
+## Korean platforms
+
+| Platform | Use | Notes |
+| --- | --- | --- |
+| **YouTube / YouTube Shorts** | Dominant for video | Korea's #1 video platform |
+| **Naver TV / Naver Now** | News, entertainment | Korea-only |
+| **Kakao TV** | Entertainment, drama | Kakao ecosystem |
+| **Instagram (Reels + Stories)** | Lifestyle, beauty, fashion | Strong Korean usage |
+| **TikTok** | Growing; Gen Z + Millennial | Strong but YouTube Shorts competing |
+| **Wavve, TVING, Coupang Play, Disney+ KR** | OTT subscription | Premium content |
+| **Twitch / AfreecaTV / SOOP** | Live streaming | AfreecaTV / SOOP is Korean-native; Twitch left KR market 2024 |
+| **NaverCafe / Daum Cafe** | Community video | Niche communities |
+
+For B2C marketing video: prioritize **YouTube + Instagram Reels + KakaoTalk channel + Naver TV**.
+For B2B: LinkedIn + YouTube.
+
+## Korean subtitle conventions (자막)
+
+Korean video almost always has burned-in subtitles (open captions) for:
+- Sound-off viewing.
+- Accessibility.
+- Style — visual energy.
+
+### Subtitle styling
+
+| Element | KR convention |
+| --- | --- |
+| **Position** | Bottom 15-20% of frame; sometimes centered for emphasis |
+| **Font** | NanumSquare / Pretendard / SB 어그로체 / 검은고딕 (bold, condensed) |
+| **Color** | White text + thick black outline OR brand color |
+| **Highlight** | Key word in yellow / brand color |
+| **Animation** | Word-by-word reveal common in entertainment |
+| **Size** | 4-6% of video height |
+| **Background** | Often no background (just outline); sometimes semi-opaque box |
+
+### Subtitle vs caption
+
+- **자막** = open caption (always visible, burned in).
+- **폐쇄자막 (CC)** = closed caption (toggleable via player).
+
+Korean broadcast law (방송통신심의위원회) requires 폐쇄자막 on broadcast TV for accessibility.
+Online video commonly uses 자막 (burned in) for visual impact.
+
+### Common Korean subtitle quirks
+
+- **Onomatopoeia visible** — "찰칵" "두근두근" overlaid as text effect (entertainment style).
+- **Reaction text** — narrator-style reactions "헐!" "대박!" superimposed.
+- **Brand-aligned styling** — fintech / luxury uses minimal subtitles; entertainment uses dramatic.
+
+## Voiceover conventions
+
+### Voice style
+
+For Korean voiceover:
+
+| Style | Use |
+| --- | --- |
+| **Female, gentle, warm** | Toss-style fintech, beauty, wellness |
+| **Female, professional** | B2B, news, education |
+| **Male, low, authoritative** | Premium products, banking, automotive |
+| **Male, friendly** | Casual consumer, food |
+| **Mascot voice (cute / playful)** | Kid products, entertainment |
+
+Default for fintech B2C: gentle female voiceover with 해요체 (~해요).
+
+### Honorific level
+
+| Level | Use |
+| --- | --- |
+| **합쇼체 (~합니다)** | Formal; banking, B2B, news |
+| **해요체 (~해요)** | Friendly; consumer brands, lifestyle |
+| **해체 (~해)** | Casual; entertainment, peer-to-peer (rare in marketing) |
+
+Korean B2C marketing 2024+ trends toward 해요체. Toss / Kakao / Naver use 해요체. Banks (KB, 신한) typically use 합쇼체 in formal communications.
+
+### AI voiceover for Korean
+
+Available tools (2024+):
+- **클로바보이스 (Naver Clova)** — strong Korean voices.
+- **ElevenLabs** — multi-lingual including Korean (improving).
+- **Typecast** — Korean-native AI voice.
+
+AI voice is increasingly common for product videos / changelogs / short-form. Always review for:
+- Pronunciation of brand names + product names.
+- Pacing of brand-critical lines.
+- Naturalness (should not sound robotic).
+
+For high-stakes brand video: use human voiceover.
+
+## Korean video advertising regulations
+
+### 표시광고법 (Display Advertising Law)
+
+Korean ad disclosure rules:
+
+- **PR 표시 (sponsored content)** — paid content must be disclosed: `#광고`, `#PR`, `#유료광고` clearly visible.
+- **Brand ambassador / collaboration** — disclosure required when influencer is paid.
+- **Health / medical claims** — pre-approved language only.
+- **Financial product ads** — risk disclosure required.
+
+For YouTube videos with brand sponsorship:
+- Tag video as "Includes paid promotion" (YouTube's built-in setting).
+- Disclose verbally / on screen at start: "이 영상은 [브랜드]로부터 광고비를 받아 제작됐습니다".
+
+For Instagram / TikTok sponsored posts:
+- `#광고`, `#유료광고`, `#PR` in caption (not hidden in #16th hashtag).
+
+Failure to disclose can result in 공정거래위원회 (KFTC) fines.
+
+### 방송통신심의위원회 (Broadcast review)
+
+For broadcast / cable TV (less relevant for online-only video, but applicable for cross-platform):
+
+- Profanity, violence, sexual content reviewed.
+- Children's programming: stricter ad rules.
+- Health / cosmetic / medical claims: pre-approved language.
+- Tobacco / alcohol restrictions on TV ads (vary by time slot).
+
+### KFDA / 식품의약품안전처 for product videos
+
+Health / beauty / supplement videos:
+- Claims must align with KFDA-approved language for the product type.
+- "치료" (treats), "효과" (efficacy) carefully regulated.
+- Before-after photos / videos: regulated for cosmetics + medical.
+
+## Korean video pacing
+
+Korean entertainment / commercial video tends toward **faster pacing** than Western:
+
+- Cuts every 1.5-3 seconds (Western: 2-5 seconds).
+- More text overlays per second.
+- More reaction shots / inserts.
+- Music + sound effects more prominent.
+
+For B2C: lean Korean-paced (faster). For B2B / formal: Western-paced is fine.
+
+## Korean color and style conventions
+
+| Genre | Color grade |
+| --- | --- |
+| **K-drama / cinematic** | Soft, warm, often slightly desaturated; signature "K-drama look" |
+| **K-pop MV** | High saturation, bold colors |
+| **Beauty / lifestyle** | Bright, soft, slightly pink/peach |
+| **Fintech / B2B** | Brand-color anchored; clean grade |
+| **Food / cooking** | Saturated; warm; food-pop |
+
+For Korean fintech video: keep close to brand palette; avoid heavy filters.
+
+## Korean live streaming
+
+### AfreecaTV / SOOP
+
+Korean-native live streaming platform. BJ (Broadcasting Jockey) culture, donations (별풍선), gaming + chat-heavy.
+
+For brand campaigns: collaboration with established BJs reaches engaged audiences.
+
+### Twitch — left Korea
+
+Twitch shut down Korean operations in 2024. Korean streamers migrated to Chzzk (Naver) and SOOP.
+
+### Live streaming format
+
+- **16:9 OR 9:16** depending on platform.
+- **1080p 30/60fps**.
+- **Adaptive bitrate** (HLS) for diverse viewers.
+- **Chat overlay** integral to Korean streaming culture.
+- **Donation / Super Chat** notifications visible during stream.
+
+## Korean video content trends (2024+)
+
+- **숏폼 (short-form) dominance** — Reels + Shorts everywhere.
+- **AI-generated content** — AI voiceover, AI thumbnails, AI editing increasingly common.
+- **Vertical-first production** — even traditional creators shooting vertical primary.
+- **자막 + 음성** — both subtitle and voiceover (sound-on viewers + sound-off).
+- **하이라이트 편집** — long live streams cut into short highlight clips for VOD.
+- **Branded content** — direct brand integration (not just product placement).
+
+## Production budget reference (Korean, 2024-2025)
+
+| Job | KRW |
+| --- | --- |
+| Phone shoot + Capcut edit (DIY) | 0-300,000 |
+| Indie videographer (1 day shoot + 2 day edit) | 1,500,000-3,500,000 |
+| Production agency (full B2B brand film) | 10,000,000-50,000,000 |
+| TVCM-quality 30s spot | 50,000,000-200,000,000+ |
+| YouTube / Reels short-form (per video, agency) | 1,000,000-5,000,000 |
+| K-pop MV-quality video | 100,000,000-500,000,000+ |
+
+Rates vary widely; get 2-3 quotes. Korean creative production agencies cluster in 강남 / 합정 / 성수 districts.
+
+## Korean platform algorithm notes
+
+| Platform | Algorithm signals |
+| --- | --- |
+| **YouTube** | Watch time, click-through rate, session start, language preferences |
+| **YouTube Shorts** | View-through rate, swipe-away rate, replays |
+| **Instagram Reels** | Engagement velocity, completion rate, shares |
+| **TikTok** | View-through, share, comment quality |
+| **Naver TV** | Naver search integration, Naver login engagement |
+| **Kakao TV** | KakaoTalk share velocity |
+
+For Korean reach: YouTube Shorts + Instagram Reels combined cover most B2C audience.
+
+## Distribution strategy for Korean B2C video
+
+1. **Master long-form** — produce 60-90s brand video.
+2. **Cut for platforms** — 9:16 vertical for Reels/Shorts/TikTok; 1:1 for IG feed; 16:9 for YouTube.
+3. **Localize** — Korean primary; English subtitles for export potential.
+4. **Stagger release** — YouTube first (long-form), then Reels/Shorts within 3-7 days.
+5. **Boost paid** — IG paid promotion for branded campaigns; YouTube ads for awareness.
+6. **Track + iterate** — weekly review of view-through, engagement; double down on what works.
+
+## Don't
+
+- Don't skip ad disclosure on sponsored content. KFTC fines are real.
+- Don't use unlicensed K-pop tracks. Strikes + legal exposure.
+- Don't translate Western video voiceover word-for-word. Adapt to KR phrasing.
+- Don't use only English subtitles for KR audience. Korean subtitles primary.
+- Don't shoot landscape for 9:16 distribution. Shoot vertical or 4K with safe-zone planning.
+- Don't ignore the algorithm signals — KR YouTube / Reels reward different things than US.
+- Don't use 합쇼체 for casual brands or 해요체 for premium banks. Match register to brand.
+- Don't auto-translate Korean voiceover to English — get a native Korean speaker review.
+
+## Cross-reference
+
+- [`knowledge/video/video-fundamentals.md`](video-fundamentals.md) — encoding, captions
+- [`knowledge/video/marketing-video.md`](marketing-video.md) — marketing video strategy
+- [`knowledge/video/social-and-short-form.md`](social-and-short-form.md) — Reels / Shorts / TikTok
+- [`knowledge/video/in-product-video.md`](in-product-video.md) — onboarding / help
+- [`knowledge/i18n/korean-document-style.md`](../i18n/korean-document-style.md) — honorific level
+- [`knowledge/i18n/korean-typography.md`](../i18n/korean-typography.md) — Hangul typography (subtitle fonts)
+- [`knowledge/patterns/email-design.md`](../patterns/email-design.md) — KR ad disclosure rules