# Microcopy — VN Voice Guide

> Kit-level (brand-agnostic) microcopy patterns + Vietnamese voice principles. Mọi consumer của Cowork UI Kit phải tham chiếu doc này khi viết label, placeholder, error, empty, toast, confirm.
> Live: 🌐 https://ui.dang.pm/microcopy/
> Companion: 📄 [UXSTATE.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/uxstate/UXSTATE.md) · 📄 [UX-PATTERNS.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/UX-PATTERNS.md) · 📄 [MOTION.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/motion/MOTION.md)

**Date:** 2026-05-20 · v0.5.11 baseline · Iter 44C

---

## How to read this document

Mỗi pattern entry có structure cụ thể:

```
### Pattern name
What:       1 câu định nghĩa surface
Authority:  primary reference + rule cụ thể
VN voice:   format đúng cho tiếng Việt
Anti:       chỉ rõ kiểu lười / sai
Where:      atom/molecule nào sẽ dùng
```

Không vague principles. Không motivational filler. Mọi rule có nguồn cited.

---

## 1 · VN Voice Principles (7 nguyên tắc)

### 1.1 — Ngắn gọn, không lê thê

Mỗi câu microcopy < 12 từ. Mỗi message < 2 câu. Loại bỏ "rất", "thì", "là", "mà", "có thể" khi có thể cắt.

**Authority:** Nielsen Norman Group research — users scan, không đọc; pages viết concise + scannable improve usability +58% ([NN/G Microcopy](https://www.nngroup.com/articles/3-is-of-microcopy/)). Microsoft Style Guide: "be crisp and clear — eliminate extraneous information" ([Microsoft Top 10](https://learn.microsoft.com/en-us/style-guide/top-10-tips-style-voice)).

| ❌ Lê thê | ✅ Gọn |
|---|---|
| "Bạn vui lòng nhập số điện thoại của bạn vào ô này" | "Số điện thoại" |
| "Có vẻ như đã có lỗi xảy ra khi xử lý yêu cầu" | "Không gửi được. Thử lại sau." |
| "Bạn có chắc chắn muốn xoá không?" | "Xoá 3 ảnh? Không hoàn tác được." |

### 1.2 — Anh/em với personal, formal với B2B

Cowork UI Kit serve 2 dạng product:

- **Personal / consumer** (KHI member, An Nhien shopper, A-Kryphan reader, BetterBuy buyer): xưng **anh/em** hoặc **bạn** tuỳ ngữ cảnh thân thuộc.
- **B2B / internal admin** (dashboard, CRM, ops tool): **không xưng**. Tránh ngôi 1-2 hoàn toàn — câu mệnh lệnh hoặc passive cảnh báo.

**Authority:** Mailchimp voice guide — "tone changes depending on the emotional state of the person you're addressing" ([Mailchimp Voice](https://styleguide.mailchimp.com/voice-and-tone/)). VTEX Localization — Vietnamese pronouns đa nghĩa (inclusive/exclusive), tránh khi không cần ([VTEX i18n](https://uxwriting.vtex.com/docs/best-practices/i18n/)).

```
[KHI Wellness — member booking]
✅ "Lịch tập của em đã được giữ. Hẹn em sáng mai 7h."
❌ "Đặt lịch thành công." (cứng)

[KWM Admin — internal dashboard]
✅ "Đã lưu thay đổi. 3 phòng tập cập nhật giá."
❌ "Em đã lưu xong rồi anh ơi." (sai context)
```

### 1.3 — Câu chủ động, không bị động

Bị động (vd "được", "bị", "được xử lý") làm câu rườm rà + che chủ thể. Tiếng Việt mạnh ở câu chủ động.

**Authority:** Mailchimp Style Guide — "use active voice, avoid passive voice" ([Mailchimp Writing Principles](https://styleguide.mailchimp.com/writing-principles/)). Shopify Polaris — "use active voice to clarify subject and action" ([Polaris Voice](https://polaris.shopify.com/content/voice-and-tone)).

| ❌ Bị động | ✅ Chủ động |
|---|---|
| "Đơn hàng đã được tạo" | "Tạo đơn xong" |
| "Email sẽ được gửi tới bạn" | "Em gửi email cho anh trong 5 phút nữa" |
| "Tài khoản của bạn bị khoá" | "Khoá tài khoản. Liên hệ admin để mở." |

**Exception:** Cảnh báo system-level (không có actor rõ): "Phiên đã hết hạn" OK vì user là object thực sự.

### 1.4 — Số liệu cụ thể, không mơ hồ

Tránh "vài", "khoảng", "có thể". Số cụ thể tăng trust + giảm cognitive load.

**Authority:** Material 3 — "use numerals in place of words for numbers" ([Material 3 Style](https://m3.material.io/foundations/content-design/style-guide)). NN/G — vague terms increase error rates ([NN/G Error Messages](https://www.nngroup.com/articles/error-message-guidelines/)).

| ❌ Mơ hồ | ✅ Cụ thể |
|---|---|
| "Đơn hàng sắp tới" | "Đơn hàng đến trong 2-3 ngày" |
| "Một vài ảnh tải lỗi" | "3 trong 12 ảnh tải lỗi" |
| "Sẽ mất một lúc" | "Khoảng 30 giây" |
| "Còn ít chỗ trống" | "Còn 2 slot lúc 19h" |

### 1.5 — Verb + Object, không verb-only

Button label luôn dạng **động từ + tân ngữ**. Tân ngữ làm rõ action affect cái gì.

**Authority:** Microsoft Style — "use a verb corresponding to the user action (Create, Delete, Add) instead of generic Submit" ([Microsoft Writing Style](https://learn.microsoft.com/en-us/windows/apps/design/style/writing-style)). NN/G Confirmation Dialogs — "vague Yes/No should be avoided" ([NN/G Proximity](https://www.nngroup.com/articles/proximity-consequential-options/)).

| ❌ Verb-only / generic | ✅ Verb + Object |
|---|---|
| "Submit" / "Gửi" | "Đặt lịch tư vấn" |
| "OK" / "Đồng ý" | "Xác nhận đơn" |
| "Save" / "Lưu" | "Lưu thay đổi" |
| "Delete" / "Xoá" | "Xoá 3 ảnh" |
| "Continue" / "Tiếp tục" | "Tiếp tục thanh toán" |

**Exception:** Trong dialog mà title đã nêu rõ object → button có thể verb-only. Vd: title "Xoá đơn hàng #1234?" → button "Xoá vĩnh viễn".

### 1.6 — Vấn đề + cách fix, không "Required field"

Error message cần 2 thông tin: (a) sai cái gì, (b) fix bằng cách nào. Không chỉ "Required" / "Invalid".

**Authority:** NN/G Error Guidelines — "human-readable language, concisely describe the issue, offer constructive advice, don't blame the user" ([NN/G Error Messages](https://www.nngroup.com/articles/error-message-guidelines/)). Atlassian Guide tone — "be human, give guidance and support" ([Atlassian Voice Tone](https://atlassian.design/content/voice-and-tone-principles/)).

| ❌ Generic | ✅ Vấn đề + Fix |
|---|---|
| "Bắt buộc" | "Em nhập số điện thoại để bên anh gọi xác nhận" |
| "Sai định dạng" | "Số điện thoại 10 chữ số, bắt đầu 0 (vd 0901234567)" |
| "Server error 500" | "Mạng chậm. Thử lại trong 5 giây hoặc gọi 1900..." |
| "Password too weak" | "Cần thêm 1 chữ hoa và 1 số (hiện đang 6 ký tự thường)" |

### 1.7 — Tone match emotional state

Cùng 1 surface, tone phải đổi theo việc user đang vui (mới đăng ký) hay frustrated (lỗi thanh toán).

**Authority:** Atlassian Situational Tone — Inform/Guide/Educate/Inspire/Direct dùng theo context ([Atlassian Voice Tone Overview](https://atlassian.design/foundations/content/voice-tone)). Shopify Polaris — "error messages are not written the same way as onboarding content" ([Shopify Voice Tone](https://polaris.shopify.com/content/voice-and-tone)).

| Emotional state | Tone | Ví dụ |
|---|---|---|
| Onboarding (excited) | Warm, light | "Mừng anh quay lại. Tuần này có 3 lớp Pilates mới." |
| Task success (satisfied) | Brief, confident | "Đã lưu." |
| Error (frustrated) | Calm, no-blame, fix-oriented | "Mạng chậm — thử lại trong 5 giây." |
| Destructive (cautious) | Explicit, consequence | "Xoá 5 ảnh? Không hoàn tác được." |
| Empty (neutral) | Inviting, with CTA | "Chưa có lịch hẹn nào. [+ Đặt lịch đầu tiên]" |

---

## 2 · Tone Matrix — 6 brand archetype

Brand voice = brand archetype × Cowork core VN voice. Không phải brand nào cũng playful — sai tone breaks brand trust.

| Brand | Archetype | Default tone | Pronoun | Sample voice |
|---|---|---|---|---|
| **KHI Wellness** | Caregiver (wellness) | Warm, calm, grounded | anh/em (member) — none (admin) | "Lịch tập của em đã được giữ. Hẹn em sáng mai." |
| **An Nhien** | Sage (agarwood, ritual) | Quiet, reverent, slow | mình/bạn (consumer) | "Mộc trầm gửi đến bạn, gói gọn trong giấy dó." |
| **BetterBuy** | Everyman (e-com mass) | Direct, energetic, transparent | bạn / không xưng | "Còn 4 món. Đặt trong 10p để ship sáng mai." |
| **A-Kryphan** | Sage/Creator (personal blog) | Personal, reflective, dry | mình / tôi | "Mình ghi lại, để 3 tháng sau đọc lại đỡ quên." |
| **Xanh Marketing** | Innocent (skincare clean) | Soft, honest, plain | bạn | "Da bạn cần thêm thời gian. Đừng vội." |
| **HaoGood Group** | Ruler (NZL retail) | Confident, slightly formal, vibrant (NZL EN) | (English-first) | "Save 30% today. Stock running low — 4 left." |
| **AI Tools (admin)** | Magician (internal) | Crisp, no-pronoun, telemetry-aware | none | "3 sync jobs failed. Logs in #ops-alerts." |
| **Cowork (kit demo default)** | Engineer (utility) | Neutral kit voice | none | "Đã lưu 2 thay đổi. Hoàn tác trong 10s." |

**Rule:** Khi build cho 1 brand cụ thể, override default kit copy bằng brand-specific phrasing trong code-level (component prop), không hard-code kit voice nếu brand context có sẵn.

---

## 3 · Microcopy Patterns by Surface

### 3.1 — Button labels

**Authority:** Microsoft Style ([button text](https://learn.microsoft.com/en-us/windows/apps/design/style/writing-style)) · Shopify Polaris ([CTAs](https://polaris.shopify.com/content/voice-and-tone)) · GOV.UK plain language ([GOV.UK content design](https://www.gov.uk/guidance/content-design/writing-for-gov-uk))

**Pattern:** `<động từ cụ thể> + <object>`. Không generic, không câu hỏi, không "Click here".

| Context | ✅ Đúng | ❌ Anti |
|---|---|---|
| Form submit (booking) | "Đặt lịch tư vấn" | "Gửi" / "Submit" |
| Form submit (signup) | "Tạo tài khoản" | "Đăng ký" (OK nhưng yếu) / "OK" |
| Save changes | "Lưu thay đổi" | "Save" / "Lưu" |
| Destructive | "Xoá vĩnh viễn" | "Đồng ý" / "OK" |
| Cancel (destructive context) | "Giữ lại" / "Không xoá" | "Cancel" / "Huỷ" |
| Cancel (in-progress) | "Huỷ tải lên" | "Huỷ" (mơ hồ) |
| Continue multi-step | "Tiếp tục thanh toán" | "Next" / "Tiếp" |
| Primary CTA hero | "Đặt lịch trải nghiệm miễn phí" | "Bắt đầu" / "Get started" |
| Empty state | "+ Thêm sản phẩm đầu tiên" | "Add" / "Create new" |
| Loading button | (giữ label + spinner + `aria-busy`) | đổi label thành "Loading..." |

**In kit:** All button atoms (`atoms/button.html`, `atoms/icon-button.html`). React lib button component `props.children` chuẩn verb+object.

### 3.2 — Form labels + placeholders + helper text

**Authority:** NN/G — placeholder text disappears + confuses users; helper text persists ([NN/G placeholder antipattern](https://www.nngroup.com/articles/form-design-placeholders/)). Material 3 — "you/your for direct address" ([Material 3 Style](https://m3.material.io/foundations/content-design/style-guide)).

**Pattern 3 layer:**

1. **Label** (above input): danh từ ngắn, không có dấu hai chấm
2. **Placeholder** (inside input): **ví dụ format**, không phải instruction
3. **Helper text** (below input): rule + lý do (nếu non-obvious)

```
✅ Đúng
┌─────────────────────────────┐
│ Số điện thoại               │  ← Label
│ ┌─────────────────────────┐ │
│ │ 0901234567              │ │  ← Placeholder = ví dụ thật
│ └─────────────────────────┘ │
│ Bên anh dùng để xác nhận đơn │  ← Helper = lý do
└─────────────────────────────┘

❌ Anti
┌─────────────────────────────┐
│ Số điện thoại của bạn: *    │  ← Label dư "của bạn" + ":" + "*"
│ ┌─────────────────────────┐ │
│ │ Nhập số điện thoại      │ │  ← Placeholder lặp label
│ └─────────────────────────┘ │
│ Bắt buộc                    │  ← Helper vô nghĩa
└─────────────────────────────┘
```

**3 field examples:**

| Field | Label | Placeholder | Helper |
|---|---|---|---|
| Phone | "Số điện thoại" | "0901234567" | "Bên anh dùng để xác nhận đơn" |
| Email | "Email" | "ten@email.com" | (omit nếu obvious) |
| Date of birth (member) | "Ngày sinh" | "15/03/1990" | "Tặng quà sinh nhật mỗi năm" |

**In kit:** 📄 [atoms/number-input.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/number-input.html) · 📄 [molecules/date-picker.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/date-picker.html) — copy guideline áp dụng cho mọi form atom.

### 3.3 — Error messages

**Authority:** NN/G Error Scoring Rubric — score on 5 axes: clear + concise + helpful + polite + visible ([NN/G Error Rubric](https://www.nngroup.com/articles/error-messages-scoring-rubric/)). Atlassian — "tone down boldness, be human" ([Atlassian Voice Tone](https://atlassian.design/content/voice-and-tone-principles/)).

**Pattern:** `<vấn đề là gì> + <cách fix>`. Không "Required". Không blame user.

| Surface | ❌ Generic | ✅ Đúng |
|---|---|---|
| Inline field (required) | "Bắt buộc" | "Em nhập số điện thoại để bên anh gọi xác nhận" |
| Inline field (format) | "Sai định dạng" | "Số điện thoại 10 chữ số, bắt đầu 0" |
| Inline field (taken) | "Email đã tồn tại" | "Email này đã đăng ký. [Đăng nhập] hoặc dùng email khác" |
| Block error | "Lỗi tải dữ liệu" | "Mạng chậm — không tải được lịch hẹn. [Thử lại]" |
| Route fatal (500) | "Internal server error" | "Hệ thống đang trục trặc. Bên anh đã được báo. Thử lại trong 1-2 phút." |
| Route 404 | "404 Not Found" | "Trang này không có nữa. [Về trang chủ]" |
| Network offline | "Network error" | "Mất kết nối mạng. Em sẽ tự lưu khi có mạng." |

**Tone rule:** Không "Bạn đã nhập sai", không "Lỗi của bạn". Frame issue, không frame người.

**In kit:** 📄 [molecules/error-state.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/error-state.html) — `role="alert"` cho inline, error-page cho fatal. Cross-ref 📄 [UXSTATE.md § 4](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/uxstate/UXSTATE.md).

### 3.4 — Empty states

**Authority:** NN/G Empty State Guidelines — "headline + supporting description + CTA, designed for this moment" ([NN/G Empty State](https://www.nngroup.com/articles/empty-state-interface-design/)). Shopify Polaris — "new users appreciate light fun tone, but no jokes when frustrated".

**Pattern:** `Chưa có <thing>. <Lý do/value>. [+ <Verb cụ thể>]`

| Variant | ✅ Đúng |
|---|---|
| No-data (first time) | "Chưa có sản phẩm nào. Thêm sản phẩm đầu tiên để bắt đầu bán. [+ Thêm sản phẩm]" |
| No-results (filtered) | "Không tìm thấy 'trầm hương 5kg'. Thử bỏ bớt filter hoặc đổi từ khoá." |
| First-use (onboarding) | "Sắp xong rồi. Còn 2 bước để mở studio. [→ Tiếp tục setup]" |
| Offline | "Mất mạng. Khi có mạng, em sẽ tự đồng bộ lại." |
| Completed (good empty) | "Hết việc hôm nay 🎉 Nghỉ ngơi đi anh." |

**Anti:**
- ❌ "No data" / "Empty"
- ❌ "There's nothing here yet" — qua chung chung
- ❌ Joke khi user đang frustrated (vd empty sau filter fail)

**In kit:** 📄 [molecules/empty-state.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/empty-state.html) — 4 variants (no-data/no-results/first-use/offline). Cross-ref 📄 [UXSTATE.md § 4](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/uxstate/UXSTATE.md).

### 3.5 — Loading states

**Authority:** NN/G Response Times — <100ms = no spinner, 100ms-1s = spinner, 1-10s = skeleton, >10s = progress + cancel ([NN/G Skeleton Screens](https://www.nngroup.com/articles/skeleton-screens/)). Microsoft Style — "explain what's going on" ([Microsoft Top 10](https://learn.microsoft.com/en-us/style-guide/top-10-tips-style-voice)).

**Pattern:** Context-specific, không "Loading...".

| Duration | ✅ Đúng | ❌ Anti |
|---|---|---|
| <100ms | (no copy) | "Loading..." |
| Inline button (1-2s) | (giữ label + spinner) | đổi sang "Loading..." |
| Block skeleton (2-10s) | "Đang tải lịch hẹn..." | "Loading data..." |
| Long process (>10s) | "Đang xử lý đơn hàng (5/12)" | "Please wait..." |
| Upload (with %) | "Đang tải ảnh 3/5 — 45%" | "Uploading..." |
| Searching | "Đang tìm 'trầm hương'..." | "Searching..." |

**Rule:** Verb tiếng Việt **+ đang +** object. Càng cụ thể object càng tốt.

**In kit:** 📄 [atoms/loading-spinner.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/loading-spinner.html) · 📄 [atoms/loading-skeleton.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/loading-skeleton.html) · 📄 [atoms/loading-progress.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/loading-progress.html).

### 3.6 — Confirmations (success)

**Authority:** Mailchimp — "plainspoken, value clarity above all" ([Mailchimp TLDR](https://styleguide.mailchimp.com/tldr/)). Atlassian — "be human, give support" ([Atlassian Voice Tone](https://atlassian.design/content/voice-and-tone-principles/)).

**Pattern:** Verb past + (optional) object cụ thể. **Không** "Success!" / "Thành công!"

| Context | ✅ Đúng | ❌ Anti |
|---|---|---|
| Saved | "Đã lưu" | "Success!" / "Thành công!" |
| Saved with object | "Đã lưu 3 thay đổi" | "Saved successfully" |
| Order placed | "Tạo đơn #1234 xong. Gửi xác nhận qua email." | "Order placed successfully" |
| Booking confirmed | "Lịch tập sáng mai 7h đã giữ ✓" | "Booking successful" |
| Sent | "Đã gửi tới ten@email.com" | "Email sent" |
| Deleted (destructive) | "Đã xoá 5 ảnh. [Hoàn tác]" — phải có undo nếu được | "Deleted" |
| Copied | "Đã copy" (auto-dismiss 2s) | "Copied to clipboard" |

**Toast duration rule (per UXSTATE):** 4s info, 6s warning, persistent danger.

**In kit:** 📄 [organisms/toast.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/toast.html) — `role="status"` (polite) cho success/info, `role="alert"` (assertive) cho danger.

### 3.7 — Destructive confirmations

**Authority:** NN/G Confirmation Dialogs — "Delete 3 issues?" beats "Are you sure?"; explicit consequence + reverse-able info ([NN/G Proximity](https://www.nngroup.com/articles/proximity-consequential-options/)). UX Movement — "irreversible actions need explicit consequence statement" ([Destructive Action Guide](https://medium.com/design-bootcamp/a-ux-guide-to-destructive-actions-their-use-cases-and-best-practices-f1d8a9478d03)).

**Pattern:**
```
Title:   <Verb> <số cụ thể> <object>?
Body:    <Hệ quả ngắn>. <Có / không hoàn tác được>.
Action:  [<Verb-only — match title>]
Cancel:  [Giữ lại] / [Không xoá]   (KHÔNG "Huỷ")
```

| Context | ✅ Đúng |
|---|---|
| Delete photos | Title: "Xoá 5 ảnh?" · Body: "Không hoàn tác được. Ảnh đã share vẫn còn link." · Actions: [Xoá vĩnh viễn] [Giữ lại] |
| Cancel order | Title: "Huỷ đơn #1234?" · Body: "Tiền sẽ hoàn về ví trong 2-3 ngày." · Actions: [Huỷ đơn] [Quay lại] |
| Sign out | Title: "Đăng xuất?" · Body: "Em sẽ phải nhập số điện thoại lại lần sau." · Actions: [Đăng xuất] [Ở lại] |
| Delete account | Title: "Xoá tài khoản?" · Body: "Tất cả lịch tập, gói, lịch sử biến mất. Không hoàn tác được." · Actions: [Xoá tài khoản] [Giữ lại] + gõ "XOÁ" để confirm |

**Rule cứng:** Destructive primary button **bên phải** (eye lands last), cancel **bên trái**. Theo Apple HIG. Cancel label **không được** là "Huỷ" (overload với "Huỷ đơn" trong cùng dialog).

### 3.8 — Date/time formatting

**Authority:** ICU + Vietnamese locale (vi-VN). Material 3 — "use simple verb forms for past/future" ([Material 3](https://m3.material.io/foundations/content-design/style-guide)).

| Surface | Format |
|---|---|
| Full date | `15/03/2026` (dd/mm/yyyy — vi-VN locale) |
| Date with day | `Thứ Bảy, 15/03/2026` |
| Relative recent | `2 phút trước` / `Hôm qua` / `Tuần trước` |
| Relative future | `Trong 30 phút` / `Ngày mai` / `Thứ Hai tới` |
| Time only | `14:30` (24h, không AM/PM) |
| Month label | `Tháng Một` ... `Tháng Mười Hai` (in DatePicker calendar) |
| Day-of-week abbreviated | `T2 T3 T4 T5 T6 T7 CN` (Chủ Nhật) |
| Range | `15/03 - 22/03/2026` (cùng năm thì bỏ năm bên trái) |

**Anti:** ❌ `March 15, 2026` ❌ `3/15/26` (US format) ❌ `Mon Tue Wed` ❌ `2:30 PM`

**In kit:** 📄 [molecules/date-picker.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/date-picker.html) — đã enforce vi-VN.

### 3.9 — Number formatting

**Authority:** ICU `vi-VN` standard. Vietnamese uses `.` for thousands separator + `,` for decimal (opposite US).

| Surface | Format | Ví dụ |
|---|---|---|
| Currency VND | `1.250.000đ` (dot separator, suffix `đ`) | `1.250.000đ` |
| Currency USD | `$1,250.00` (US standard, không local) | `$1,250.00` |
| Decimal | `,` separator | `3,14` |
| Large number | dot every 3 | `1.250.000` |
| Percentage | `45%` (no space) | `ROAS 4,2x` (`x` for multiplier) |
| Phone display | `0901 234 567` (group 4-3-3) | `0901 234 567` |

**Anti:** ❌ `1,250,000 VND` (US format + verbose suffix) ❌ `1250000đ` (no separator) ❌ `3.14` (US decimal trong VN context)

---

## 4 · Voice Swap Table

Quick-reference cho AI agent: gặp anti-pattern → swap đúng VN voice.

| ❌ Anti-pattern (often AI default) | ✅ VN voice swap | Why |
|---|---|---|
| "Submit" | "Đặt lịch" / "Gửi đơn" (verb+object) | Generic verb invisible |
| "OK" | (specific verb-noun) | "OK" = không action |
| "Cancel" (in destructive dialog) | "Giữ lại" / "Không xoá" | "Huỷ" overload với destructive |
| "Are you sure?" | "Xoá 3 ảnh?" (specific) | Vague — NN/G research |
| "Loading..." | "Đang tải lịch hẹn..." (context) | Tell what's loading |
| "Success!" / "Thành công!" | "Đã lưu" / "Đã gửi" | Past tense verb is enough |
| "Required field" / "Bắt buộc" | "Em cần số điện thoại để gọi xác nhận" | Explain why |
| "Invalid email" | "Email cần dấu @ (vd ten@email.com)" | Show what valid looks like |
| "Server error" | "Mạng chậm — thử lại trong 5 giây" | Frame, not jargon |
| "You have no items" | "Chưa có sản phẩm nào. [+ Thêm cái đầu tiên]" | CTA + invitation |
| "Click here" | (verb+object link text) | "Click here" fails screen readers |
| "Please enter your email" | "Email" (label) + "ten@email.com" (placeholder) | "Please" + "your" = bloat |
| "Bạn vui lòng..." | (cắt — vào thẳng action) | Politeness padding lạc tone |
| "Hệ thống ghi nhận..." | "Đã lưu" | Bureaucratic |
| "Quý khách" (consumer) | "anh/em" / "bạn" | "Quý khách" cold in personal |
| "Click vào nút..." | (linked verb) | Tautology |

---

## 5 · Cross-reference Matrix

Khi dùng atom X → tham chiếu microcopy section Y:

| Atom / Molecule / Organism | Microcopy section | Notes |
|---|---|---|
| 📄 [atoms/button.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/button.html) | § 3.1 Button labels | Verb+object pattern |
| 📄 [atoms/number-input.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/number-input.html) | § 3.2 Form labels | Label/placeholder/helper 3-layer |
| 📄 [atoms/slider.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/slider.html) | § 3.2 + § 3.9 Number | Value display vi-VN |
| 📄 [atoms/loading-spinner.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/loading-spinner.html) | § 3.5 Loading | Context-specific verb |
| 📄 [atoms/loading-skeleton.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/loading-skeleton.html) | § 3.5 Loading | `aria-label` = "Đang tải <X>" |
| 📄 [atoms/loading-progress.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/loading-progress.html) | § 3.5 + § 3.9 Number | Show fraction "3/12" |
| 📄 [atoms/file-uploader.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/file-uploader.html) | § 3.3 Error + § 3.5 Loading | Upload error format |
| 📄 [molecules/date-picker.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/date-picker.html) | § 3.8 Date/time | vi-VN format enforced |
| 📄 [molecules/empty-state.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/empty-state.html) | § 3.4 Empty states | 4 variants matching |
| 📄 [molecules/error-state.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/error-state.html) | § 3.3 Error messages | Issue + Fix |
| 📄 [organisms/toast.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/toast.html) | § 3.6 Confirmations + § 3.3 Error | Severity → tone |
| 📄 [organisms/modal.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/modal.html) | § 3.7 Destructive | When `severity=destructive` |

**Companion docs:**
- 📄 [UX-PATTERNS.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/UX-PATTERNS.md) — abstract patterns (motion, density, accessibility tokens)
- 📄 [MOTION.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/motion/MOTION.md) — timing tokens + choreography
- 📄 [UXSTATE.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/uxstate/UXSTATE.md) — state decision trees + ARIA reference
- 📄 [A11Y-RULES.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/A11Y-RULES.md) — POUR enforcement (label requirements)

---

## 6 · Brand Examples (same surface, 3 brand)

Mỗi brand cùng surface → microcopy khác để showcase tone matrix § 2.

### Surface A — Hero CTA (landing page)

| Brand | Headline | Subline | CTA |
|---|---|---|---|
| **KHI Wellness** | "Pilates cho ngày mai dài hơn" | "Studio nhỏ, đông HLV, chỗ ngồi đủ thoáng. Buổi đầu miễn phí." | "Đặt buổi trải nghiệm" |
| **An Nhien** | "Trầm trong nhà, tâm trong người" | "Mộc trầm núi Bồng, đốt 45 phút, không nồng." | "Xem bộ sưu tập" |
| **A-Kryphan** | "Ghi lại trước khi quên" | "Một blog mình viết khi xong việc, không lên lịch, không SEO." | "Đọc bài mới nhất" |

### Surface B — 404 page

| Brand | Headline | Body | CTA |
|---|---|---|---|
| **KHI Wellness** | "Trang này không có nữa" | "Có thể link cũ rồi. Em đưa anh về trang lịch tập nhé?" | "Về lịch tập" |
| **An Nhien** | "Trang đã đi vắng" | "Không tìm thấy đường này. Trở về vườn trầm chính." | "Về trang chủ" |
| **A-Kryphan** | "404 — chưa viết bài này" | "Hoặc đã xoá. Hoặc link sai. Mình cũng không nhớ." | "Quay lại danh sách bài" |

### Surface C — Empty cart / list

| Brand | Headline | Body | CTA |
|---|---|---|---|
| **KHI Wellness** | "Chưa đặt lịch nào" | "Tuần này còn slot lúc 7h, 18h, 19h30. Đặt thử buổi đầu nhé." | "+ Đặt lịch đầu tiên" |
| **An Nhien** | "Giỏ còn trống" | "Có vài bộ trầm mới về tuần này. Xem thử." | "Xem bộ sưu tập" |
| **A-Kryphan** | "Chưa có gì ở đây" | "Bài đầu tiên sẽ lên cuối tuần. Quay lại Chủ Nhật." | "Đọc lưu trữ" |

---

## 7 · References (10 cited sources)

Mọi rule trên đều có authority. Khi confused, đọc nguồn gốc:

1. 🌐 [Nielsen Norman Group — Error-Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/) — Heuristic #9, human-readable + no-blame.
2. 🌐 [Nielsen Norman Group — The 3 I's of Microcopy](https://www.nngroup.com/articles/3-is-of-microcopy/) — Inform/Influence/Interact framework.
3. 🌐 [Nielsen Norman Group — Empty State Interface Design](https://www.nngroup.com/articles/empty-state-interface-design/) — 3 guidelines for complex applications.
4. 🌐 [Microsoft Writing Style Guide — Top 10](https://learn.microsoft.com/en-us/style-guide/top-10-tips-style-voice) — Warm/relaxed, ready to lend hand, crisp/clear.
5. 🌐 [Microsoft Windows Apps — Writing Style](https://learn.microsoft.com/en-us/windows/apps/design/style/writing-style) — Button text rules (verb-noun).
6. 🌐 [Material Design 3 — Content Style Guide](https://m3.material.io/foundations/content-design/style-guide) — Numerals, sentence case, "you/your".
7. 🌐 [Atlassian Design System — Voice and Tone Principles](https://atlassian.design/content/voice-and-tone-principles/) — Bold/optimistic/practical + Inform/Guide/Educate/Inspire/Direct.
8. 🌐 [Mailchimp Content Style Guide — Voice and Tone](https://styleguide.mailchimp.com/voice-and-tone/) — Voice constant, tone shifts with emotional state.
9. 🌐 [Shopify Polaris — Voice and Tone](https://polaris.shopify.com/content/voice-and-tone) — Read aloud, every word weighed.
10. 🌐 [GOV.UK Content Design](https://www.gov.uk/guidance/content-design/writing-for-gov-uk) — Plain language is mandatory, not dumbing down.
11. 🌐 [VTEX UX Writing — Localization](https://uxwriting.vtex.com/docs/best-practices/i18n/) — Vietnamese pronoun complexity, avoid when possible.
12. 🌐 [NN/G — Skeleton Screens](https://www.nngroup.com/articles/skeleton-screens/) — Loading thresholds 100ms / 1s / 10s.

**Kit-internal cross-ref:** 📄 [UX-PATTERNS.md § "Brand voice as a token layer (future)"](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/UX-PATTERNS.md) — this doc operationalizes that promised layer.

---

## Appendix — Quick decision tree for AI agents

```
Cần viết microcopy cho surface X?
│
├─ Surface = button?
│  └─ § 3.1 — Verb + Object. Không "OK"/"Submit".
│
├─ Surface = form field?
│  └─ § 3.2 — Label (noun) + Placeholder (example) + Helper (why)
│
├─ Surface = error?
│  └─ § 3.3 — Vấn đề + Fix. Không blame user. role="alert"
│
├─ Surface = empty?
│  └─ § 3.4 — Chưa có X. CTA verb. 4 variants (no-data/no-results/first-use/offline)
│
├─ Surface = loading?
│  └─ § 3.5 — Đang + verb + object. Context-specific, không "Loading..."
│
├─ Surface = success toast?
│  └─ § 3.6 — "Đã + verb" past tense. Không "Success!"
│
├─ Surface = destructive confirm?
│  └─ § 3.7 — "Xoá N <thing>?" + explicit consequence + match verb in CTA
│
├─ Surface = date/time?
│  └─ § 3.8 — dd/mm/yyyy, T2-CN, 24h, Tháng Một-Tháng Mười Hai
│
└─ Surface = number/currency?
   └─ § 3.9 — `1.250.000đ`, `,` decimal, `0901 234 567` phone
```

Sau khi pick section → check brand tone matrix § 2 → adjust pronoun + warmth.

---

**Version:** v0.5.11 · Iter 44C · 2026-05-20
**Maintainer:** Cowork UI Kit
**Status:** ✅ Production reference doc. Mọi `/kry-ui` generated UI must follow.