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

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

@@ -0,0 +1,98 @@
+# Switch
+
+> Toggle control cho binary on/off settings — state thay đổi ngay khi tap, không cần confirm.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `value` | boolean | `true` \| `false` | `false` | Current on/off state |
+| `disabled` | boolean | `true` \| `false` | `false` | Non-interactive state |
+| `label` | string | — | — | Title label alongside switch [VERIFY] |
+| `onChange` | function | — | — | Callback khi toggle. `"onChange": "setState://settingName"` |
+
+---
+
+## States
+
+| State | Track Color | Thumb Color | Opacity | Interactive |
+|-------|-----------|-----------|---------|-------------|
+| **Off** | `Colors.black_04` | `Colors.white` | 1 | true |
+| **On** | `Colors.pink_03` | `Colors.white` | 1 | true |
+| **Disabled Off** | `Colors.black_04` | `Colors.white` | reduced | false |
+| **Disabled On** | `Colors.pink_03` | `Colors.white` | reduced | false |
+
+Thumb slides smoothly between left (off) → right (on) with animation.
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Setting toggle** | Binary on/off setting có effect ngay | Cần submit → dùng CheckBox | Bật/tắt thông báo, bật/tắt sinh trắc học |
+| **Feature enable** | Enable/disable feature | Chọn giữa 2 options khác nhau → dùng Radio | Bật Dark mode, bật Face ID |
+| **Preference** | User preference có effect ngay | — | Ẩn số dư, hiển thị gợi ý |
+
+---
+
+## SSR Pattern
+
+### Settings List
+```json
+{
+  "id": "settings_section",
+  "type": "section",
+  "forEach": "{{data.settings}}",
+  "render": {
+    "id": "setting_row",
+    "type": "row",
+    "children": [
+      {
+        "component": "Text",
+        "props": {
+          "content": "{{item.label}}",
+          "typography": "body_default_regular"
+        }
+      },
+      {
+        "component": "Switch",
+        "props": {
+          "value": "{{item.enabled}}",
+          "label": "{{item.label}}"
+        },
+        "onChange": "setState://setting_{{item.key}}"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Screen readers announce: title label, current state (on/off), role (switch/toggle).
+- Tapping toggles state và announce new state.
+- Entire row (label + switch) tappable.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho instant settings — effect ngay khi toggle.
+- Provide title label mô tả what switch controls.
+- Đặt trong settings screens / preference panels.
+
+### Don't
+- Không dùng cho form selections cần submit → dùng **CheckBox**.
+- Không dùng cho chọn giữa 2 distinct options → dùng **Radio** / segmented control.
+- Không group switches mutual-exclusive → đó là Radio behavior.

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

@@ -0,0 +1,120 @@
+# TabView
+
+> Horizontal tab bar — switch between content panels. Categorized content within single screen.
+
+**Package:** `@momo-kits/tab-view`
+**Platform:** RN ✅ | Compose ❌ (use TabRow + HorizontalPager)
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Variant Axes
+
+| Axis | Options | Default |
+|------|---------|---------|
+| **Layout** | `fixed` · `scrollable` | `fixed` (≤4 tabs), `scrollable` (>4 tabs) |
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `tabs` | array | `[{ label, key }]` | required | Tab definitions |
+| `activeKey` | string | — | first tab's key | Currently active tab key |
+| `layout` | string | `"fixed"` \| `"scrollable"` | auto per tab count | Fixed: equal width. Scrollable: intrinsic width, horizontal scroll [VERIFY] |
+| `swipeable` | boolean | `true` \| `false` | `true` | Allow swipe gesture to switch content panels [VERIFY] |
+| `onChange` | function | — | — | Callback khi tab changes. `"onChange": "setState://activeTab"` |
+
+### Tab Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `label` | string | yes | Tab text label (1-2 words) |
+| `key` | string | yes | Unique identifier for tab |
+| `badge` | number | no | Optional badge count on tab [VERIFY] |
+
+---
+
+## States
+
+| State | Text Color | Indicator | Interactive |
+|-------|-----------|-----------|-------------|
+| **Active** | `Colors.pink_03` | 2dp pink underline | true |
+| **Inactive** | `Colors.black_12` | None | true |
+| **Pressed** | Opacity 0.8 | — | true |
+
+Indicator slides smoothly between tabs on switch. Content panels transition via horizontal swipe or tap.
+
+---
+
+## Variant-to-Context Map
+
+| Layout | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|--------|-------------|-----------|-------------------|
+| **fixed** | ≤4 tabs, equal importance | >4 tabs → cramped | "Tất cả" / "Đã gửi" / "Đã nhận" |
+| **scrollable** | >4 tabs, variable label lengths | ≤4 tabs → use fixed | Category filters, nhiều loại giao dịch |
+
+---
+
+## SSR Pattern
+
+### Transaction History Tabs
+```json
+{
+  "component": "TabView",
+  "props": {
+    "tabs": [
+      { "label": "Tất cả", "key": "all" },
+      { "label": "Chuyển tiền", "key": "transfer" },
+      { "label": "Thanh toán", "key": "payment" },
+      { "label": "Nhận tiền", "key": "receive" }
+    ],
+    "activeKey": "{{state.activeTab}}",
+    "layout": "fixed"
+  },
+  "onChange": "setState://activeTab"
+}
+```
+
+### Scrollable Category Tabs
+```json
+{
+  "component": "TabView",
+  "props": {
+    "tabs": "{{data.categories}}",
+    "activeKey": "{{state.selectedCategory}}",
+    "layout": "scrollable"
+  },
+  "onChange": "setState://selectedCategory"
+}
+```
+
+---
+
+## Accessibility
+
+- Each tab announces: label + position ("Tab 2 trong 4") + state ("đang chọn").
+- Content panels navigable by swiping.
+- Tab labels descriptive and concise.
+- Minimum 44dp touch target height per tab.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho organizing related content into parallel categories.
+- Tab labels short — 1-2 words.
+- Default to most relevant tab active on first load.
+- Scrollable variant khi >4 tabs.
+- Consistent content structure across tab panels.
+
+### Don't
+- Không dùng cho sequential steps → dùng **Steps**.
+- Không dùng cho app-level navigation → dùng **BottomTab**.
+- Không >6-7 tabs even in scrollable mode.
+- Không mix icons and text in tab labels unless all tabs have both.
+- Không nest TabView trong TabView — confusing navigation.
+- Không truncate tab labels → shorten text or switch to scrollable.

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

@@ -0,0 +1,118 @@
+# Tag
+
+> Label indicator — classify content theo status, category, hoặc type. Non-interactive.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `label` | string | — | required | Tag text. 1-2 words max |
+| `variant` | string | `"default"` \| `"orange"` \| `"green"` \| `"red"` \| `"blue"` \| `"grey"` | `"default"` | Color variant [VERIFY] |
+| `size` | string | `"large"` \| `"medium"` | `"medium"` | Tag size [VERIFY] |
+
+---
+
+## Variants
+
+| Variant | Background | Text Color | Semantic |
+|---------|-----------|-----------|----------|
+| **default** | `Colors.black_04` | `Colors.black_17` | Neutral |
+| **orange** | `Colors.orange_08` | `Colors.orange_03` | Warning, pending |
+| **green** | `Colors.green_08` | `Colors.green_03` | Success, completed |
+| **red** | `Colors.red_08` | `Colors.red_03` | Error, failed |
+| **blue** | `Colors.blue_08` | `Colors.blue_03` | Informational |
+| **grey** | `Colors.black_04` | `Colors.black_12` | Inactive, expired |
+
+---
+
+## States
+
+| State | Appearance | Description |
+|-------|-----------|-------------|
+| **Default** | Static label với assigned color variant | Non-interactive |
+
+Tag là **non-interactive** — chỉ display. Không respond to taps.
+
+---
+
+## Variant-to-Context Map
+
+| Variant | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **green** | Trạng thái thành công/hoàn thành | — | "Thành công" trên giao dịch |
+| **red** | Trạng thái lỗi/thất bại | Non-error status | "Thất bại" trên giao dịch |
+| **orange** | Trạng thái chờ xử lý/cảnh báo | Already resolved | "Đang xử lý" trên giao dịch |
+| **blue** | Thông tin/category | — | "Khuyến mãi" trên deal card |
+| **default** | Neutral label không có semantic | Cần semantic color | "Tài chính" category label |
+| **grey** | Inactive/expired | Active items | "Hết hạn" trên voucher |
+
+---
+
+## SSR Pattern
+
+### Transaction Status Tag
+```json
+{
+  "component": "Tag",
+  "props": {
+    "label": "Thành công",
+    "variant": "green",
+    "size": "medium"
+  }
+}
+```
+
+### Tags in List Item
+```json
+{
+  "id": "transaction_item",
+  "type": "row",
+  "children": [
+    {
+      "component": "Text",
+      "props": {
+        "content": "{{item.title}}",
+        "typography": "body_default_regular"
+      }
+    },
+    {
+      "component": "Tag",
+      "props": {
+        "label": "{{item.statusLabel}}",
+        "variant": "{{item.statusVariant}}",
+        "size": "medium"
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Accessibility
+
+- Tag text provides accessible label — screen readers đọc content.
+- Color alone không phải only indicator of meaning — text content convey status.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng Tag cho status ("Thành công", "Đang xử lý", "Thất bại").
+- Dùng Tag cho classification ("Tài chính", "Khuyến mãi").
+- Chọn color variant match semantic meaning.
+- Keep tag text short, scannable.
+
+### Don't
+- Không dùng Tag cho interactive filtering — dùng **Chip**.
+- Không dùng Tag cho numeric counts — dùng **Badge**.
+- Không make Tag tappable — display-only.
+- Không dùng long sentences làm tag text.

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

@@ -0,0 +1,151 @@
+# Text
+
+> Base typography component — render mọi nội dung text trong MoMo theo design tokens.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `content` | string | — | required | Text content to display |
+| `typography` | string | token name | `"body_default_regular"` | Typography token. Pattern: `{category}_{size}_{weight}` |
+| `color` | string | `Colors.*` token | `"Colors.black_17"` | Text color token |
+| `numberOfLines` | number | — | — | Max visible lines. Ellipsis khi truncated [VERIFY] |
+| `align` | string | `"left"` \| `"center"` \| `"right"` | `"left"` | Text alignment [VERIFY] |
+| `fontFamily` | string | `"SFProText"` \| `"AlegreyaSans"` \| `"BarlowCondensed"` | `"SFProText"` | Font family [VERIFY] |
+
+---
+
+## Variants
+
+Text không có visual variants riêng — thay vào đó dùng typography tokens.
+
+### Typography Token Pattern
+
+```
+{category}_{size}_{weight}
+```
+
+| Category | Sizes | Dùng cho |
+|----------|-------|---------|
+| `heading` | `l`, `default`, `s` | Section titles, screen headers |
+| `body` | `default`, `s` | Body content, descriptions |
+| `action` | `default`, `s` | Button labels, interactive text |
+| `caption` | `default`, `s` | Small supporting text, timestamps |
+| `label` | `default`, `s` | Form labels, metadata |
+
+**Weights:** `regular`, `medium`, `semibold`, `bold`
+
+**Examples:** `body_default_regular`, `heading_l_bold`, `caption_s_medium`, `action_default_bold`
+
+### Color Pairing Rules
+
+| Role | Token | Usage |
+|------|-------|-------|
+| **Default** | `Colors.black_17` | Primary content, headings, body |
+| **Secondary** | `Colors.black_15` | Supporting text |
+| **Hint** | `Colors.black_12` | Placeholder, helper text |
+| **Disabled** | `Colors.black_08` | Non-interactive text |
+| **Accent** | `Colors.pink_03` | Links, highlighted text |
+| **Error** | `Colors.red_03` | Error messages |
+| **Info** | `Colors.blue_03` | Informational text |
+
+---
+
+## States
+
+| State | Color | Description |
+|-------|-------|-------------|
+| **Default** | per `color` prop | Normal display |
+| **Disabled** | `Colors.black_08` | Non-interactive context |
+
+Text là static, non-interactive component. States chỉ ảnh hưởng color.
+
+---
+
+## Variant-to-Context Map
+
+| Typography | Color | Khi nào dùng | Ví dụ trong MoMo |
+|-----------|-------|-------------|-------------------|
+| `heading_l_bold` | `Colors.black_17` | Screen heading chính | "Chuyển tiền" title |
+| `heading_default_bold` | `Colors.black_17` | Section title | "Người nhận gần đây" section header |
+| `body_default_regular` | `Colors.black_17` | Body content | Mô tả giao dịch, hướng dẫn |
+| `body_default_regular` | `Colors.black_12` | Helper/hint text | "Nhập số điện thoại người nhận" |
+| `caption_s_regular` | `Colors.black_12` | Timestamp, metadata | "Hôm nay, 14:30" |
+| `action_default_bold` | `Colors.pink_03` | Tappable text link | "Xem tất cả", "Chi tiết" |
+| `body_default_regular` | `Colors.red_03` | Error message | "Số tiền vượt hạn mức" |
+
+---
+
+## SSR Pattern
+
+### Section with Heading + Body
+```json
+{
+  "id": "info_section",
+  "type": "section",
+  "children": [
+    {
+      "component": "Text",
+      "props": {
+        "content": "Thông tin giao dịch",
+        "typography": "heading_default_bold"
+      }
+    },
+    {
+      "component": "Text",
+      "props": {
+        "content": "Vui lòng kiểm tra thông tin trước khi xác nhận",
+        "typography": "body_default_regular",
+        "color": "Colors.black_12"
+      }
+    }
+  ]
+}
+```
+
+### Truncated List Item Text
+```json
+{
+  "component": "Text",
+  "props": {
+    "content": "{{item.description}}",
+    "typography": "body_s_regular",
+    "color": "Colors.black_15",
+    "numberOfLines": 2
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Text content accessible mặc định cho screen readers.
+- Decorative text: ẩn khỏi assistive technology.
+- Minimum font size: 10sp absolute, prefer 14sp+ cho body.
+- Contrast: tất cả text-on-background meet WCAG AA (4.5:1 normal, 3:1 large text).
+- Không convey meaning chỉ bằng color — pair với icon hoặc label.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng typography tokens consistently — không set font size/weight manually.
+- Dùng `Colors.black_17` cho primary readable content.
+- Dùng truncation `numberOfLines` khi space constrained.
+- Heading tokens cho titles, body tokens cho content.
+
+### Don't
+- Không dùng font sizes dưới 10sp.
+- Không override line height / letter spacing từ typography tokens.
+- Không dùng `Colors.black_08` (Disabled) cho readable content — thiếu contrast.
+- Không mix multiple font families trong cùng paragraph.
+- Không dùng heading tokens cho body content hoặc ngược lại.

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

@@ -0,0 +1,99 @@
+# Toast
+
+> Transient notification — auto-dismiss message at top of screen. Non-interactive feedback for completed actions.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ❌ (use SnackBar)
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `type` | string | `"info"` \| `"warning"` \| `"error"` \| `"success"` | `"info"` | Toast type — determines icon và color |
+| `message` | string | — | required | Toast text content |
+| `duration` | number | milliseconds | `3000` | Auto-dismiss duration [VERIFY] |
+| `position` | string | `"top"` \| `"bottom"` | `"top"` | Screen position [VERIFY] |
+
+---
+
+## Variants
+
+| Type | Icon | Icon Color | Background |
+|------|------|-----------|-----------|
+| **info** | info-circle | `Colors.blue_03` | `Colors.white` with shadow [VERIFY] |
+| **warning** | warning-triangle | `Colors.orange_03` | `Colors.white` with shadow [VERIFY] |
+| **error** | error-circle | `Colors.red_03` | `Colors.white` with shadow [VERIFY] |
+| **success** | check-circle | `Colors.green_03` | `Colors.white` with shadow [VERIFY] |
+
+Text color: `Colors.black_17` for all types.
+
+---
+
+## States
+
+| State | Appearance |
+|-------|-----------|
+| **Entering** | Slide in from top with fade animation |
+| **Visible** | Full opacity, countdown active |
+| **Exiting** | Slide out with fade animation |
+| **Dismissed** | Removed from view |
+
+---
+
+## Variant-to-Context Map
+
+| Type | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|------|-------------|-----------|-------------------|
+| **success** | Confirm completed action | Action needs follow-up | "Chuyển tiền thành công" |
+| **error** | Brief error feedback | Error needs user action → dùng Information | "Không thể kết nối" |
+| **warning** | Caution notification | Needs persistent visibility → dùng Information | "Mạng yếu" |
+| **info** | Neutral notification | Critical information | "Đã copy mã giới thiệu" |
+
+---
+
+## SSR Pattern
+
+### Success Toast after Action
+```json
+{
+  "id": "submit_action",
+  "type": "action",
+  "trigger": "onSuccess",
+  "toast": {
+    "component": "Toast",
+    "props": {
+      "type": "success",
+      "message": "Thanh toán thành công!"
+    }
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Announce toast content as live region — screen reader speaks message immediately.
+- Auto-dismiss timing should be sufficient for screen reader to complete announcement (~3s minimum).
+- Non-interactive — no tap targets within toast.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho brief, non-critical feedback messages.
+- Auto-dismiss — user không cần interact.
+- Keep message short — 1 line.
+- Success type cho completed actions.
+
+### Don't
+- Không dùng cho errors requiring user action → dùng **Information** hoặc **PopupNotify**.
+- Không dùng cho persistent status → dùng **Information**.
+- Không include action buttons trong toast → dùng **SnackBar** (Compose).
+- Không stack multiple toasts simultaneously.
+- Không dùng trên Compose → dùng **SnackBar**.