@momo-kits/native-kits 0.157.5 → 0.158.1-beta.1

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(yarn react-native:*)",
+      "Read(//Users/phuc/.claude/skills/ai-skill-generator/**)",
+      "Bash(python3 scripts/install_skill.py --update)",
+      "Bash(cd /Users/phuc/momo-kits/.claude/skills/design-system-kits && mkdir -p .claude/skills/design-system-kits && mv SKILL.md README.md references .claude/skills/design-system-kits/)",
+      "Bash(mv .claude/skills/design-system-kits/* . && rmdir .claude/skills/design-system-kits && rmdir .claude/skills)"
+    ]
+  }
+}

package/.claude/skills/design-system/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: design-system
+description: Use this skill when designers need to create design specifications, usage guidelines, rules, or documentation for the MoMo KitX design system. Helps define visual specs, component usage rules, design patterns, and accessibility guidelines. Maps 1:1 with design-system-kits.
+
+---
+
+## Prereqs
+- Read [references/spec-convention.md](references/spec-convention.md) before generating design specs
+
+## How to Use
+
+1. **Identify the task**: spec, guideline, rule, or pattern documentation
+2. **Find reference** in catalog tables below
+3. **Load reference file** for visual specs, usage rules, and guidelines
+4. **Generate documentation** with correct token names and component mapping
+
+## References
+
+### Design Tokens
+| File | Load when... |
+|------|-------------|
+| `references/tokens/colors.md` | Color usage rules, palette, accessibility |
+| `references/tokens/theme.md` | Light/dark theme specs, semantic colors |
+| `references/tokens/typography.md` | Type scale, hierarchy, pairing rules |
+| `references/tokens/spacing-radius.md` | Spacing system, radius, layout grid |
+
+### Components
+| File | Component | RN | Compose |
+|------|-----------|:--:|:------:|
+| `references/components/button.md` | Button | ✅ | ✅ |
+| `references/components/text.md` | Text | ✅ | ✅ |
+| `references/components/input.md` | Input | ✅ | ✅ |
+| `references/components/input-search.md` | InputSearch | ✅ | ✅ |
+| `references/components/input-text-area.md` | InputTextArea | ✅ | ✅ |
+| `references/components/input-dropdown.md` | InputDropDown | ✅ | ✅ |
+| `references/components/input-phone-number.md` | InputPhoneNumber | ✅ | ✅ |
+| `references/components/input-money.md` | InputMoney | ✅ | ✅ |
+| `references/components/input-otp.md` | InputOTP | ✅ | ✅ |
+| `references/components/checkbox.md` | CheckBox | ✅ | ✅ |
+| `references/components/radio.md` | Radio | ✅ | ✅ |
+| `references/components/switch.md` | Switch | ✅ | ✅ |
+| `references/components/icon.md` | Icon | ✅ | ✅ |
+| `references/components/image.md` | Image | ✅ | ✅ |
+| `references/components/badge.md` | Badge, BadgeDot | ✅ | ✅ |
+| `references/components/tag.md` | Tag | ✅ | ✅ |
+| `references/components/chip.md` | Chip | ✅ | ✅ |
+| `references/components/popup-notify.md` | PopupNotify | ✅ | ✅ |
+| `references/components/toast.md` | Toast | ✅ | ❌ |
+| `references/components/snackbar.md` | SnackBar | ✅ | ✅ |
+| `references/components/skeleton.md` | Skeleton | ✅ | ✅ |
+| `references/components/loader.md` | Loader | ✅ | ❌ |
+| `references/components/tooltip.md` | Tooltip | ✅ | ✅ |
+| `references/components/avatar.md` | Avatar | ✅ | ❌ |
+| `references/components/carousel.md` | Carousel | ✅ | ❌ |
+| `references/components/tab-view.md` | TabView | ✅ | ❌ |
+| `references/components/divider.md` | Divider | ✅ | ✅ |
+| `references/components/pagination.md` | Pagination | ✅ | ✅ |
+| `references/components/progress-info.md` | ProgressInfo | ✅ | ❌ |
+| `references/components/rating.md` | Rating | ✅ | ❌ |
+| `references/components/slider.md` | Slider | ✅ | ❌ |
+| `references/components/stepper.md` | Stepper | ✅ | ❌ |
+| `references/components/steps.md` | Steps | ✅ | ❌ |
+| `references/components/collapse.md` | Collapse | ✅ | ❌ |
+| `references/components/swipe.md` | Swipe | ✅ | ❌ |
+| `references/components/suggest-action.md` | SuggestAction | ✅ | ❌ |
+| `references/components/uploader.md` | Uploader | ✅ | ❌ |
+| `references/components/date-picker.md` | DatePicker | ✅ | ✅ |
+| `references/components/information.md` | Information | ✅ | ✅ |
+
+### Navigation
+| File | Load when... |
+|------|------------------------------------------------|
+| `references/navigation/setup.md` | Screen layout structure, containers |
+| `references/navigation/stack.md` | Screen header, scroll behavior |
+| `references/navigation/navigation-options.md` | Header title, background, right buttons |
+| `references/navigation/navigator.md` | Screen transitions, push/pop patterns |
+| `references/navigation/bottom-tab.md` | Bottom tab bar specs |
+| `references/navigation/modal.md` | Modal overlay patterns |
+| `references/navigation/bottomsheet.md` | Bottom sheet patterns |
+
+## Important Rules
+
+1. **Always use design tokens** — Never reference raw hex/px values without mapping to a token name
+2. **Component mapping** — Every visual element must map to a KitX component
+3. **State coverage** — Specs must define all states: default, pressed, disabled, error, loading
+4. **Accessibility** — Include contrast ratios (WCAG AA min), touch targets (44pt min), screen reader notes
+5. **Platform parity** — Note when specs differ between React Native and Compose Multiplatform
+6. **Bilingual** — Use English for specs, add Vietnamese labels (tieng Viet) where relevant for MoMo team

package/.claude/skills/design-system/references/components/avatar.md

@@ -0,0 +1,134 @@
+# Avatar
+
+> User/entity representation — profile photo, initials fallback, hoặc placeholder icon. Supports grouping.
+
+**Package:** `@momo-kits/avatar`
+**Platform:** RN ✅ | Compose ❌ (build with Image + Text)
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `source` | object | `{ uri: string }` | — | Image source. Khi `null`/error → fallback to initials hoặc placeholder |
+| `name` | string | — | — | Full name — dùng để generate initials fallback (first letter of first + last word) |
+| `size` | string | `"xxs"` \| `"xs"` \| `"s"` \| `"m"` \| `"l"` \| `"xl"` \| `"xxl"` | `"m"` | Avatar size. xxs=24dp, xs=28dp, s=32dp, m=40dp, l=48dp, xl=56dp, xxl=72dp [VERIFY] |
+| `shape` | string | `"circle"` \| `"square"` | `"circle"` | Avatar shape [VERIFY] |
+| `badge` | element | — | — | Optional Badge overlay (e.g., online indicator, verification) [VERIFY] |
+| `onPress` | function | — | — | Callback khi tap avatar. `"onPress": "navigate://Profile"` |
+
+---
+
+## Variants
+
+| Variant | Display | Fallback Priority |
+|---------|---------|-------------------|
+| **Image** | Photo from `source.uri` | — |
+| **Initials** | 1-2 letter initials from `name` on colored background | When `source` is null or fails to load |
+| **Placeholder** | Generic person icon | When both `source` and `name` are absent |
+
+### Initials Background Colors
+
+Background color derived from `name` string hash — consistent color per user. Colors from predefined palette [VERIFY].
+
+---
+
+## States
+
+| State | Appearance | Interactive |
+|-------|-----------|-------------|
+| **Image loaded** | Photo displayed, clipped to shape | per onPress |
+| **Loading** | Placeholder/shimmer while image loads | false |
+| **Error / No image** | Initials (if `name` provided) or generic icon | per onPress |
+
+---
+
+## Avatar Group
+
+`AvatarGroup` renders multiple avatars overlapping horizontally.
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `avatars` | array | `[{ source, name }]` | required | List of avatar data |
+| `max` | number | — | `3` | Maximum visible avatars. Overflow shown as `+N` circle [VERIFY] |
+| `size` | string | Same as Avatar | `"s"` | Size for all avatars in group |
+| `overlap` | number | dp value | `8` | Horizontal overlap between avatars [VERIFY] |
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Profile display** | Show user identity in header, list, card | Decorative/non-user images | Avatar trên profile screen, chat list |
+| **Group display** | Show multiple participants | >5 visible → dùng list | Nhóm chia bill, nhóm chat |
+| **Placeholder** | User chưa upload ảnh | — | New user onboarding |
+
+---
+
+## SSR Pattern
+
+### User Profile Row
+```json
+{
+  "id": "user_profile",
+  "type": "row",
+  "children": [
+    {
+      "component": "Avatar",
+      "props": {
+        "source": { "uri": "{{data.user.avatarUrl}}" },
+        "name": "{{data.user.fullName}}",
+        "size": "l"
+      },
+      "onPress": "navigate://Profile"
+    },
+    {
+      "component": "Text",
+      "props": {
+        "content": "{{data.user.fullName}}",
+        "typography": "body_default_bold"
+      }
+    }
+  ]
+}
+```
+
+### Avatar Group
+```json
+{
+  "component": "AvatarGroup",
+  "props": {
+    "avatars": "{{data.participants}}",
+    "max": 3,
+    "size": "s"
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Announce avatar as: "Avatar of [name]" hoặc "Profile photo".
+- Initials fallback announce full name, not just letters.
+- onPress → announce as button with label.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho user/entity representation.
+- Always provide `name` — ensures initials fallback khi image fails.
+- Consistent sizing within same list/context.
+- AvatarGroup cho participant previews.
+
+### Don't
+- Không dùng cho product/brand images → dùng **Image** component.
+- Không dùng square shape cho user profiles — circle là standard.
+- Không dùng xxl trong lists — only for profile screens.
+- Không show >5 avatars inline → dùng AvatarGroup with `max`.

package/.claude/skills/design-system/references/components/badge.md

@@ -0,0 +1,127 @@
+# Badge
+
+> Numeric or dot indicator — signal unread counts, notifications, hoặc status trên parent element.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `type` | string | `"badge"` \| `"badgeDot"` \| `"badgeRibbon"` | `"badge"` | Badge variant [VERIFY] |
+| `value` | string/number | — | — | Badge content. Number hoặc text ("Mới"). "99+" for overflow |
+| `size` | string | `"small"` \| `"large"` | `"small"` | Size cho BadgeDot variant [VERIFY] |
+| `backgroundColor` | string | `Colors.*` token | `"Colors.red_03"` | Badge background color [VERIFY] |
+| `visible` | boolean | `true` \| `false` | `true` | Show/hide badge. Count = 0 → auto hide [VERIFY] |
+
+---
+
+## Variants
+
+| Variant | Description | Content | Color |
+|---------|-----------|---------|-------|
+| **badge** | Capsule với numeric/text value | Number hoặc short text ("99+", "Mới") | `Colors.red_03` bg, `Colors.white` text |
+| **badgeDot** | Simple circle, no text | — | `Colors.red_03` |
+| **badgeRibbon** | Ribbon-style label trên card/image edge | Short text | `Colors.red_03` bg, `Colors.white` text |
+
+---
+
+## States
+
+| State | Appearance | Description |
+|-------|-----------|-------------|
+| **Visible** | Badge displayed | Count > 0 hoặc status active |
+| **Hidden** | Badge removed entirely | Count = 0 → auto hide. Không show "0" |
+
+Badge là non-interactive — chỉ display indicator.
+
+---
+
+## Variant-to-Context Map
+
+| Variant | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **badge** (numeric) | Unread message/notification count | Count = 0 → hide | Chat tab badge "3", Notification bell "12" |
+| **badgeDot** | Signal new/unread status without count | Cần show số cụ thể → dùng badge | Profile tab có update mới, Setting có item mới |
+| **badgeRibbon** | Promotional label trên card/image | Trong list item đơn giản → dùng Tag | "Giảm 50%" ribbon trên deal card |
+
+---
+
+## SSR Pattern
+
+### Badge on Tab Icon
+```json
+{
+  "icon": "chat",
+  "label": "Chat",
+  "screen": "Chat",
+  "badge": "numericBadge",
+  "badgeValue": 3
+}
+```
+
+### Badge Dot on Avatar
+```json
+{
+  "id": "user_avatar",
+  "type": "stack",
+  "children": [
+    {
+      "component": "Avatar",
+      "props": {
+        "source": "{{data.avatar}}",
+        "size": "medium"
+      }
+    },
+    {
+      "component": "Badge",
+      "props": {
+        "type": "badgeDot",
+        "size": "small"
+      }
+    }
+  ]
+}
+```
+
+### Ribbon on Card
+```json
+{
+  "component": "Badge",
+  "props": {
+    "type": "badgeRibbon",
+    "value": "Giảm 50%",
+    "backgroundColor": "Colors.red_03"
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Badge value announce as part of parent element: "Chat, 3 thông báo mới".
+- BadgeDot: convey "mới" hoặc "unread" status to screen readers.
+- Không rely solely on badge color để convey meaning.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng Badge cho unread message/notification counts.
+- Dùng BadgeDot cho new/unread status without specific count.
+- Dùng BadgeRibbon cho promotional labels trên cards.
+- Hide badge khi count = 0.
+- Keep badge text short.
+
+### Don't
+- Không dùng Badge cho categorization — dùng **Tag**.
+- Không dùng Badge cho status text ("Active", "Pending") — dùng **Tag**.
+- Không display large strings trong Badge.
+- Không đặt multiple badges trên cùng element.

package/.claude/skills/design-system/references/components/bottom-tab.md

@@ -0,0 +1,177 @@
+# BottomTabBar
+
+> Fixed bottom navigation bar cho app-level navigation giữa top-level screens. 3–5 tabs + optional FAB.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ❌ (dùng BottomNavigation Material3)
+**Completeness:** need_update — Figma node ID unresolved
+**Figma node:** [VERIFY]
+
+---
+
+## Variant Axes
+
+| Property | Type | Values | Description |
+|----------|------|--------|-------------|
+| type | variant | default · special | Default = standard tabs. Special = center FAB elevated |
+| itemCount | variant | 2 · 3 · 4 · 5 | Số tabs. Special type chỉ support 3 hoặc 5 [VERIFY] |
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `type` | string | `"default"` \| `"special"` | `"default"` | Tab bar type |
+| `tabs` | array | Tab objects (2-5) | required | Tab configuration. Mỗi tab: `{ icon, label, screen, badge }` |
+| `activeTab` | number | index (0-based) | `0` | Currently active tab index |
+| `itemCount` | number | `2` \| `3` \| `4` \| `5` | — | Số tabs [VERIFY] |
+| `onTabPress` | function | — | — | Callback khi tap tab. `"onTabPress": "navigate://TabScreen"` |
+
+### Tab Object
+
+| Property | Type | Values | Description |
+|----------|------|--------|-------------|
+| `icon` | string | icon name | Tab icon |
+| `label` | string | — | Tab text. 1 word max (2 short words). Nouns, not verbs |
+| `screen` | string | screen name | Navigation target |
+| `badge` | string | `"hidden"` \| `"smallDotBadge"` \| `"largeDotBadge"` \| `"numericBadge"` \| `"textBadge"` | Badge type per tab |
+| `badgeValue` | string/number | — | Badge content. Number hoặc text ("Mới"). "99+" for overflow |
+| `isFAB` | boolean | `true` \| `false` | Center tab là FAB (chỉ dùng với type=special) |
+
+---
+
+## Variants
+
+| Type | Description | Tab Count | Center Tab |
+|------|-----------|-----------|------------|
+| **default** | Standard evenly distributed tabs | 2-5 | Normal |
+| **special** | Center tab elevated (FAB-style) cho primary action | 3 hoặc 5 only | Circular, elevated, `Colors.pink_03` background |
+
+---
+
+## States
+
+### Tab States
+
+| State | Icon Color | Label Color | Indicator |
+|-------|-----------|------------|-----------|
+| **Active** | `Colors.pink_03` | `Colors.pink_03` | 2px bar, `Colors.pink_03` |
+| **Inactive** | `Colors.black_12` | `Colors.black_12` | Hidden |
+
+- Active indicator: horizontal slide animation khi switch tabs.
+- Chỉ 1 tab active tại mỗi thời điểm.
+
+### Badge Types
+
+| Badge | Color | Text | Use Case |
+|-------|-------|------|----------|
+| `hidden` | — | — | No badge |
+| `smallDotBadge` | `Colors.red_03` | — | Unread/new indicator nhỏ |
+| `largeDotBadge` | `Colors.red_03` | — | Unread indicator lớn hơn |
+| `numericBadge` | `Colors.red_03` | `Colors.white`, count | Notification count. "99+" overflow |
+| `textBadge` | `Colors.red_03` | `Colors.white`, text | Short text ("Mới") |
+
+---
+
+## Variant-to-Context Map
+
+| Type + Count | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|-------------|-------------|-----------|-------------------|
+| **Default, 5 tabs** | App chính MoMo với đầy đủ navigation | — | Home / Khám phá / [+] / Chat / Cá nhân |
+| **Special, 5 tabs** | App chính với primary action (tạo mới, scan) | Primary action không cần prominence | Home / Search / [FAB Scan] / Chat / Profile |
+| **Default, 3 tabs** | Feature đơn giản, ít destinations | Cần >3 top-level sections | Sub-feature với 3 sections |
+| **Default, 4 tabs** | Balanced navigation | — | App có 4 main sections rõ ràng |
+
+### Tab Count Rules
+
+| Count | Recommendation |
+|-------|---------------|
+| 2 | Không recommended — dùng segmented control hoặc toggle |
+| 3 | Ideal — clean layout |
+| 4 | Good — balanced |
+| 5 | Maximum — keep labels very short |
+| 6+ | KHÔNG ĐƯỢC — dùng navigation pattern khác |
+
+---
+
+## SSR Pattern
+
+### Main App Shell
+```json
+{
+  "navigation": {
+    "headerType": "default",
+    "headerTitle": { "type": "text", "title": "Trang chủ" },
+    "backgroundType": "compact",
+    "bottomTab": {
+      "type": "special",
+      "activeTab": 0,
+      "tabs": [
+        { "icon": "home", "label": "Trang chủ", "screen": "Home", "badge": "hidden" },
+        { "icon": "search", "label": "Khám phá", "screen": "Explore", "badge": "hidden" },
+        { "icon": "scan", "label": "Quét mã", "screen": "Scan", "isFAB": true },
+        { "icon": "chat", "label": "Chat", "screen": "Chat", "badge": "numericBadge", "badgeValue": 3 },
+        { "icon": "user", "label": "Cá nhân", "screen": "Profile", "badge": "smallDotBadge" }
+      ]
+    }
+  }
+}
+```
+
+### Simple 3-tab Navigation
+```json
+{
+  "navigation": {
+    "bottomTab": {
+      "type": "default",
+      "activeTab": 0,
+      "tabs": [
+        { "icon": "list", "label": "Danh sách", "screen": "List", "badge": "hidden" },
+        { "icon": "chart", "label": "Thống kê", "screen": "Stats", "badge": "hidden" },
+        { "icon": "settings", "label": "Cài đặt", "screen": "Settings", "badge": "hidden" }
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Composition with Other Components
+
+| Component | Behavior |
+|-----------|----------|
+| **Toast** | Appears above BottomTabBar khi cả 2 visible |
+| **TopNav** | TopNav top + BottomTabBar bottom = standard screen shell |
+| **Popup** | Overlay full screen bao gồm BottomTabBar |
+| **Badge** | Dùng built-in badge system — KHÔNG stack external Badge component lên |
+
+---
+
+## Accessibility
+
+- Mỗi tab phải có accessible label: icon label + state ("Trang chủ, tab đang chọn").
+- Badge count announce: "Chat, 3 thông báo mới".
+- FAB: accessible label mô tả action ("Quét mã QR").
+- Tab switch announce: "Đã chuyển sang Chat".
+- Không hide tab bar khi scroll — luôn accessible.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho primary app-level navigation (3–5 destinations).
+- Keep labels 1 word (max 2 short words). Nouns, not verbs.
+- Show badges CHỈ cho actionable unread notifications.
+- Maintain scroll position per tab khi switching.
+- All icons cùng style (outline HOẶC filled — không mix).
+
+### Don't
+- Không dùng >5 tabs.
+- Không abbreviate labels ("LS.GD" → "Lịch sử").
+- Không mix icon styles across tabs.
+- Không dùng cho secondary/nested navigation — dùng back navigation.
+- Không hide tab bar on scroll.
+- Không đặt destructive actions trong tab bar.