--- name: vn-design-system-ux description: "Vietnamese UI/UX microcopy, design systems, typography tokens, stacked-diacritic line-height gates, button/tab/badge/toast character caps, state copy (empty, loading, optimistic, partial failure, destructive modals, biometric/passkey prompts, AI streaming UX), widow/orphan compound-word binding (\\u00A0), and en.json <-> vi.json i18n parity." repository: "https://github.com/jangtrinh/design-os-vietnamese" --- # `vn-design-system-ux`: Flagship Vietnamese UI/UX & Design System Engine > The flagship DESIGN:OS design system and microcopy skill for engineering production-grade software interfaces in Vietnamese (`vi-VN`). > Governs typography vertical metrics, diacritic clipping floors, component character budgets, state-first UX writing, and bidirectional localization parity. --- ## 1. Core Engineering Workflow Building or localizing a modern digital product in Vietnamese requires strict adherence to vertical diacritical physics, horizontal syllabic expansion (+25% to +35%), and conversational clarity: ``` [1. Font & Glyph Audit] │ check_font_coverage.py ▼ [2. Typography Tokens & Leading Floors] │ references/design-tokens-vi.md, references/typography-and-layout.md ▼ [3. State-First UX Microcopy & Character Caps] │ references/microcopy-states.md, references/glossary.md, references/banned-phrases.md ▼ [4. Register Contract & Locale Formatting] │ references/register-matrix.md, references/unicode-and-tone.md, references/locale-formatting.md ▼ [5. i18n Catalog & Placeholder Parity] │ check_i18n_parity.py, assets/en.sample.json, assets/vi.sample.json ▼ [6. Automated Copy & Domain Rule Linting] │ validate_copy.py, references/examples.md ▼ [7. Pre-Deploy Release Verification] references/qa-checklist.md ``` --- ## 2. Step-by-Step Implementation Guide ### Step 1: Font Selection & Glyph Coverage Verification Before applying any typography styles, ensure your web font contains all 134 precomposed Vietnamese diacritics, `Đ/đ` (`U+0110/U+0111`), and the currency symbol `₫` (`U+20AB`): - Consult [typography-and-layout.md](references/typography-and-layout.md) for approved production typefaces (`Be Vietnam Pro`, `Plus Jakarta Sans`, `Inter`). - When configuring `next/font/google`, enforce `subsets: ['latin', 'vietnamese']` to prevent fallback font flashing on stacked diacritics (`UX007`). - Run font coverage verification: ```bash python3 skills/vn-design-system-ux/scripts/check_font_coverage.py public/fonts/BeVietnamPro-Regular.ttf ``` ### Step 2: Establish Design Tokens & Vertical Leading Floors Vietnamese stacked diacritics (`Ẫ`, `Ễ`, `Ộ`, `Ữ`, `Ậ`, `Ệ`) collide or clip under standard English tight leading: - Load the standardized W3C Design Tokens from [assets/design-tokens.vi.json](assets/design-tokens.vi.json). - Review leading specifications in [design-tokens-vi.md](references/design-tokens-vi.md) and [typography-and-layout.md](references/typography-and-layout.md). - Enforce mandatory line-height floors (`UX006`): - **Headings (`h1`–`h6`, `.title`):** `line-height >= 1.18` (recommended `1.20`–`1.30`). - **Body Prose (`p`, `.prose`):** `line-height >= 1.35` (recommended `1.50`–`1.60`). - Apply CSS `text-wrap: balance` on headings to eliminate single-syllable trailing orphans, or bind final compounds with `\u00A0`. ### Step 3: Craft State-First Microcopy Within Component Caps Write clear, verb-first microcopy for all UI controls following [microcopy-states.md](references/microcopy-states.md): - **Component Character Caps (`UX001`):** - Buttons (`ui-button`): `<= 24 characters` NFC (`Tạo dự án mới`, `Lưu thay đổi`). - Navigation Tabs (`ui-tab`): `<= 18 characters` NFC (`Tổng quan`, `Thanh toán`). - Status Badges (`ui-badge`): `<= 16 characters` NFC (`Đang hoạt động`, `Quá hạn`). - Toast Notifications (`ui-toast`): `<= 90 characters` NFC (`Đã xóa 3 tệp. Hoàn tác`). - **Eliminate Padding & Pronouns in Compact Controls (`UX002`):** Strip conversational pronouns (`bạn`, `tôi`) and polite padding (`vui lòng`) from buttons and tabs. - **Empty States (`UX003`):** Replace raw dead-end placeholders (`Không có dữ liệu`) with contextual explanations and creation CTAs. - **Error States (`UX004`):** Replace generic errors (`Đã xảy ra lỗi`) with plain-language causes and actionable recovery buttons (`Thử lại`). - **Destructive Modals (`UX005`):** Explicitly warn that actions cannot be undone (`Hành động này không thể hoàn tác`) and replace vague `OK`/`Đồng ý` with specific verbs (`Xóa vĩnh viễn`). ### Step 4: Validate Terminology, Registers, & Compliance Check all interface strings against standardized dictionaries and legal constraints: - Filter calques and machine translation artifacts using [glossary.md](references/glossary.md) and [banned-phrases.md](references/banned-phrases.md). - Enforce the `ux-microcopy` register contract defined in [register-matrix.md](references/register-matrix.md) (`bạn` or implicit subject; forbid `quý khách` in SaaS). - Validate tone placement consistency and NFC normalization via [unicode-and-tone.md](references/unicode-and-tone.md). - Format numbers, currencies, dates, and phone numbers in accordance with [locale-formatting.md](references/locale-formatting.md). - Guard against unsubstantiated superlatives (`số 1`, `hàng đầu`) as required by [compliance.md](references/compliance.md). ### Step 5: Audit i18n Localization Parity Maintain bidirectional parity between English source catalogs and Vietnamese target catalogs: - Reference canonical localization models in [assets/en.sample.json](assets/en.sample.json) and [assets/vi.sample.json](assets/vi.sample.json). - Run the strict i18n parity linter: ```bash python3 skills/vn-design-system-ux/scripts/check_i18n_parity.py en.json vi.json --strict ``` - Verify: 1. Key parity (zero missing keys, zero orphaned keys). 2. Exact placeholder alignment (`{name}`, `{{count}}`). 3. Precomposed NFC encoding across all Vietnamese values. 4. ICU plural compliance: only the `other` branch is permitted in Vietnamese (no `one`, `few`, `many`). ### Step 6: Automated Copy & Domain Rule Linting Run the complete automated validator across UI source files and locale bundles: - Study worked diagnostic pairs in [examples.md](references/examples.md) to understand defect remediation patterns. - Execute linter across project catalogs: ```bash python3 skills/vn-design-system-ux/scripts/validate_copy.py src/locales/vi.json --strict ``` - Validate specialized component states using doctypes: ```bash # Check button copy against 24-character cap and pronoun padding python3 skills/vn-design-system-ux/scripts/validate_copy.py button.txt --doctype ui-button --strict # Check tab label against 18-character cap python3 skills/vn-design-system-ux/scripts/validate_copy.py tabs.txt --doctype ui-tab --strict # Check empty state card for creation CTA python3 skills/vn-design-system-ux/scripts/validate_copy.py empty-card.md --doctype ui-empty --strict # Check error state for actionable recovery python3 skills/vn-design-system-ux/scripts/validate_copy.py error-banner.txt --doctype ui-error --strict # Check destructive modal for permanent consequence python3 skills/vn-design-system-ux/scripts/validate_copy.py modal.txt --doctype ui-destructive-modal --strict # Check CSS tokens for stacked diacritic leading floors python3 skills/vn-design-system-ux/scripts/validate_copy.py styles/tokens.css --doctype css-tokens --strict # Check Next.js font declaration for vietnamese subset python3 skills/vn-design-system-ux/scripts/validate_copy.py src/app/layout.tsx --doctype nextjs-font --strict ``` ### Step 7: Release Readiness Sign-Off Complete the comprehensive release gate defined in [qa-checklist.md](references/qa-checklist.md): - [ ] NFC Unicode precomposed normalization confirmed (`--fix`). - [ ] Display and body leading tokens meet or exceed Vietnamese mandatory floors (`UX006`). - [ ] Next.js Google font loaders include `'vietnamese'` subset (`UX007`). - [ ] Buttons, tabs, badges, and toasts adhere to NFC character caps (`UX001`). - [ ] Empty, error, and destructive dialog states provide clear user agency (`UX003`, `UX004`, `UX005`). - [ ] i18n catalog parity passes with 0 errors and 0 warnings. --- ## 3. Defect Remediation Quick Reference | Symptom / Defect | Rule ID | Root Cause | Production Remediation | |---|---|---|---| | Diacritics on `Ẫ`, `Ệ` sliced off | `UX006` | Leading `< 1.18` on headings | Bump heading `line-height` to `>= 1.20` | | Font switches to fallback mid-word | `UX007` | Missing `vietnamese` subset | Add `'vietnamese'` to Google Font loader | | Button wraps to 2 lines | `UX001` | Label exceeds 24 characters | Shorten to verb-first action (`Tạo dự án`) | | Conversational button padding | `UX002` | Label contains `bạn` or `vui lòng` | Remove conversational filler | | Dead-end "Không có dữ liệu" | `UX003` | Empty state lacks action | Add contextual reason and `+ Tạo mới` CTA | | Dead-end "Đã xảy ra lỗi" | `UX004` | Error state lacks recovery | State plain cause + provide `Thử lại` button | | Dangerous vague modal button | `UX005` | Destructive modal uses `Đồng ý` | Use `Xóa vĩnh viễn` + warn cannot undo | --- ## 4. Tool & CLI Reference | Tool | Script Path | Primary Responsibility | |---|---|---| | **Copy & UX Linter** | `scripts/validate_copy.py` | Validates NFC, calques, registers, and domain rules (`UX001`–`UX007`) | | **i18n Parity Gate** | `scripts/check_i18n_parity.py` | Verifies key, placeholder, ICU plural, and cap parity (`en.json` <-> `vi.json`) | | **Font Coverage Checker** | `scripts/check_font_coverage.py` | Scans TTF/OTF cmap tables and WOFF2 unicode-ranges for 134 vi-VN glyphs | --- ## 5. Reference Library Map - **Typography & Metrics:** [typography-and-layout.md](references/typography-and-layout.md) · [design-tokens-vi.md](references/design-tokens-vi.md) - **Microcopy & States:** [microcopy-states.md](references/microcopy-states.md) · [glossary.md](references/glossary.md) · [banned-phrases.md](references/banned-phrases.md) - **Linguistic Rules:** [register-matrix.md](references/register-matrix.md) · [unicode-and-tone.md](references/unicode-and-tone.md) · [locale-formatting.md](references/locale-formatting.md) · [compliance.md](references/compliance.md) - **Diagnostics & QA:** [examples.md](references/examples.md) · [qa-checklist.md](references/qa-checklist.md) - **Token & Asset Catalogs:** [design-tokens.vi.json](assets/design-tokens.vi.json) · [en.sample.json](assets/en.sample.json) · [vi.sample.json](assets/vi.sample.json)