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

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

@@ -0,0 +1,131 @@
+# Bottom Tab Bar — Design Guideline
+
+## Overview
+
+Bottom tab navigation provides primary app-level navigation with 3–5 tabs and an optional floating action button (FAB).
+
+---
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────┐
+│                                                  │
+│                 Screen Content                   │
+│                                                  │
+├──────────────────────────────────────────────────┤
+│                                                  │
+│  [🏠]      [🔍]      [＋]      [💬]      [👤]   │
+│  Home     Search    (FAB)    Chat    Profile     │
+│                                                  │
+│  ────── active indicator ──────                  │
+│                                                  │
+└──────────────────────────────────────────────────┘
+     ↑ safe area bottom
+```
+
+---
+
+## Visual Specs
+
+| Property | Value |
+|----------|-------|
+| Height | 64dp (excluding safe area) |
+| Background | `theme.colors.background.surface` |
+| Top border | 1px `theme.colors.border.default` |
+| Tab count | 3–5 tabs |
+| Icon size | 24px |
+| Label typography | `caption_s_regular` (10sp) |
+| Icon-to-label gap | `Spacing.XXS` (2) |
+
+### Tab States
+
+| State | Icon Color | Label Color |
+|-------|-----------|-------------|
+| Active | `theme.colors.primary` (pink_03) | `theme.colors.primary` |
+| Inactive | `theme.colors.text.hint` (black_12) | `theme.colors.text.hint` |
+
+### Active Indicator
+- Animated bar that follows the selected tab
+- Color: `theme.colors.primary`
+- Height: 2px
+- Width: tab width
+- Position: top of tab bar
+- Animation: horizontal slide (200ms)
+
+---
+
+## Badge & Notification Dot
+
+### BadgeDot
+- **Size**: Small (10dp)
+- **Position**: Top-right of icon, offset -2/-2
+- **Color**: `Colors.red_03`
+- **Use for**: Unread indicator, new content flag
+
+### Badge Count
+- **Min size**: 18x18
+- **Shape**: Pill (full radius)
+- **Background**: `Colors.red_03`
+- **Text**: White, `caption_s_semibold`
+- **Position**: Top-right of icon
+- **Content**: Number or "99+" for overflow
+- **"0"**: Hidden (badge disappears)
+
+---
+
+## Floating Action Button (FAB)
+
+- **Position**: Centered between tabs, elevated above tab bar
+- **Size**: 56x56
+- **Shape**: Circle with curved container cutout
+- **Background**: `theme.colors.primary` (pink_03)
+- **Icon**: White, 24px
+- **Label**: `caption_s_regular` below FAB, `theme.colors.primary`
+- **Shadow**: Elevation shadow
+- **Container**: Curved cutout in tab bar creates visual separation
+
+---
+
+## Tab Transition
+
+- **Animation**: Fade + scale (200ms)
+- **Content**: Each tab maintains its own navigation stack
+- **State preservation**: Tab content preserved when switching between tabs
+- **Scroll position**: Maintained per tab
+
+---
+
+## Usage Guidelines
+
+### Tab Count Rules
+
+| Count | Recommendation |
+|-------|---------------|
+| 2 | Don't use tabs — consider segmented control or toggle |
+| 3 | Ideal — clean layout with clear purpose per tab |
+| 4 | Good — balanced with clear labels |
+| 5 | Maximum — use concise labels, consider icon-only for some |
+| 6+ | Don't — use different navigation pattern |
+
+### Tab Label Rules
+- Keep labels to 1 word (max 2 short words)
+- Use nouns, not verbs ("Home" not "Go Home")
+- Be consistent — all nouns or all verbs, not mixed
+
+---
+
+## Do's & Don'ts
+
+### Do's
+- Use bottom tabs for top-level navigation (3–5 destinations)
+- Show badges for actionable notifications
+- Keep tab labels short and descriptive
+- Maintain scroll position when switching tabs
+
+### Don'ts
+- Don't use more than 5 tabs
+- Don't use bottom tabs for secondary or nested navigation
+- Don't hide the tab bar on scroll (keep it always visible)
+- Don't use different icon styles across tabs (outline vs filled — be consistent)
+- Don't place destructive actions in the tab bar

package/.claude/skills/design-system/references/navigation/bottomsheet.md

@@ -0,0 +1,161 @@
+# Bottom Sheet — Design Guideline
+
+## Overview
+
+Bottom sheets slide up from the bottom of the screen to reveal additional content or actions. They maintain context by keeping the parent screen partially visible.
+
+---
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────┐
+│                                              │
+│           Parent Screen (dimmed)             │
+│                                              │
+├──────────────────────────────────────────────┤
+│            ─── Handle ───                    │  Radius.L
+│                                              │  (top corners)
+│                                              │
+│     Sheet Content                            │
+│     (scrollable if needed)                   │
+│                                              │
+│                                              │
+│                                              │
+└──────────────────────────────────────────────┘
+       ↑ safe area bottom
+```
+
+---
+
+## Visual Specs
+
+| Property | Value |
+|----------|-------|
+| Background | `theme.colors.background.surface` |
+| Corner radius | `Radius.L` (16) — top-left and top-right only |
+| Handle | 36x4, `Colors.black_06`, centered, `Spacing.S` from top |
+| Backdrop | `Colors.black_20` at 40% opacity |
+| Content padding | `Spacing.XL` (24) horizontal, `Spacing.L` (16) vertical |
+| Max height | 90% of screen height |
+| Min height | Content-driven (auto-size) |
+
+---
+
+## Sheet Variants
+
+### Standard Sheet
+- **Content**: Custom composable content
+- **Height**: Auto-sized to content (up to 90% screen)
+- **Scroll**: Scrollable if content exceeds height
+- **Use for**: Action lists, selections, additional info
+
+### Surface Sheet
+- **Surface mode** (`isSurface = true`): White surface background without handle
+- **Use for**: Integrated content that feels like part of the screen
+
+---
+
+## Interaction Specs
+
+### Opening
+- Animation: Slide up from bottom (300ms, ease-out)
+- Backdrop: Fade in simultaneously
+
+### Closing
+- Swipe down on handle or content
+- Tap backdrop (if `barrierDismissible = true`)
+- System back button/gesture
+- Programmatic dismiss
+- Animation: Slide down (250ms, ease-in)
+
+### Gestures
+- **Drag handle**: Swipe down to dismiss
+- **Content scroll**: If content is scrollable, scroll reaches top then swipe dismisses
+- **Velocity threshold**: Fast swipe down auto-dismisses
+
+---
+
+## Content Patterns
+
+### Action List
+```
+─── Handle ───
+
+  Action Item 1            [icon]
+  ─────────────────────────────
+  Action Item 2            [icon]
+  ─────────────────────────────
+  Action Item 3            [icon]
+
+  [ Cancel button (full width, text type) ]
+```
+
+- Item height: 48
+- Item padding: `Spacing.L` horizontal
+- Typography: `body_default_regular`
+- Divider: 1px `border.default` between items
+- Cancel button: `Spacing.L` top margin
+
+### Selection List
+```
+─── Handle ───
+
+  Title (headline_s_bold)
+
+  ○  Option A
+  ●  Option B (selected)
+  ○  Option C
+
+  [ Confirm button (full width, primary) ]
+```
+
+- Radio/Checkbox with label
+- Spacing between options: `Spacing.M`
+- Confirm button: `Spacing.XL` top margin
+
+### Information Sheet
+```
+─── Handle ───
+
+  Title (headline_s_bold)
+
+  Description text (body_default_regular)
+  Multi-line content with details...
+
+  [ Got it (full width, primary) ]
+```
+
+---
+
+## Usage Guidelines
+
+### When to Use Bottom Sheet
+- Secondary actions for a list item
+- Filter/sort options
+- Selection from a list of options (< 10 items)
+- Additional details without leaving context
+- Share/export options
+
+### When NOT to Use
+- Critical confirmations → Use Dialog Modal (PopupNotify)
+- Complex forms → Use full-screen modal (Present) or new screen
+- Primary navigation → Use Push or tabs
+- Many options (10+) → Use a full screen with search
+
+---
+
+## Do's & Don'ts
+
+### Do's
+- Keep bottom sheet content concise and scannable
+- Show handle for swipe-to-dismiss affordance
+- Allow backdrop tap to dismiss for non-critical sheets
+- Use standard content patterns (action list, selection, info)
+
+### Don'ts
+- Don't nest bottom sheets inside bottom sheets
+- Don't use bottom sheets for lengthy forms
+- Don't disable swipe-to-dismiss unless data loss is possible
+- Don't make bottom sheets taller than 90% of screen
+- Don't use bottom sheets for content that needs to persist

package/.claude/skills/design-system/references/navigation/modal.md

@@ -0,0 +1,133 @@
+# Modal — Design Guideline
+
+## Overview
+
+Modals are overlay dialogs that require user attention and action before continuing. They interrupt the user flow for important decisions.
+
+---
+
+## Modal Types
+
+### Dialog Modal (PopupNotify)
+- **Coverage**: Centered overlay, ~80% screen width, max 320
+- **Background dim**: `Colors.black_20` at 40% opacity
+- **Container**: `theme.colors.background.surface`, `Radius.L` (16), `Spacing.XL` (24) padding
+- **Animation**: Fade in + scale from 0.9 to 1.0
+
+### Full-screen Modal (Present)
+- **Coverage**: Full screen (slides up from bottom)
+- **Background**: No dimming (full replacement)
+- **Has own header**: Default or custom
+- **Animation**: Vertical slide up
+- **Dismiss**: Swipe down or back button
+
+---
+
+## Dialog Modal Anatomy
+
+```
+┌────── Dimmed Background (40% black) ─────────┐
+│                                               │
+│    ┌──────────────────────────────┐            │
+│    │  [✕]                        │  Radius.L  │
+│    │                              │            │
+│    │  [Illustration/Image]        │            │
+│    │                              │            │
+│    │  Title                       │            │
+│    │  (headline_s_bold)           │            │
+│    │                              │            │
+│    │  Description text            │            │
+│    │  (body_default_regular)      │            │
+│    │                              │            │
+│    │  ┌──────────┐ ┌──────────┐  │            │
+│    │  │ Secondary│ │ Primary  │  │  row mode  │
+│    │  └──────────┘ └──────────┘  │            │
+│    │                              │            │
+│    └──────────────────────────────┘            │
+│                                               │
+└───────────────────────────────────────────────┘
+```
+
+### Dialog Elements
+
+| Element | Spec | Required |
+|---------|------|----------|
+| Close icon (✕) | Top-right, 24px, `black_12` | Optional |
+| Image/Illustration | Centered, max 120px height | Optional |
+| Title | `headline_s_bold`, `text.default` | Yes |
+| Description | `body_default_regular`, `text.secondary` | Optional |
+| Primary button | Full width or half width | Yes |
+| Secondary button | Full width or half width | Optional |
+
+### Button Layout
+
+| Mode | Behavior | Use when |
+|------|----------|----------|
+| Row | Side-by-side (secondary left, primary right) | Short button labels |
+| Column | Stacked (primary top, secondary bottom) | Long button labels |
+| Auto | System decides based on text length | Default |
+
+### Button Spacing
+- Gap between buttons: `Spacing.S` (8)
+- Buttons to container edge: `Spacing.XL` (24)
+- Title to description gap: `Spacing.S` (8)
+- Description to buttons gap: `Spacing.XL` (24)
+
+---
+
+## Interaction Specs
+
+### Opening
+- Animation: 200ms fade in + scale (0.9 → 1.0)
+- Background dim: 200ms fade in
+
+### Closing
+- Tap close icon (✕)
+- Tap dimmed background (if `barrierDismissible = true`)
+- System back button/gesture
+- Button action
+- Animation: 150ms fade out
+
+### Focus Trap
+- Focus stays within modal while open
+- Tab order: Close → Content → Secondary → Primary
+- Escape/Back dismisses
+
+---
+
+## Usage Guidelines
+
+### When to Use Dialog Modal
+- Destructive confirmations ("Delete this item?")
+- Important alerts requiring acknowledgment
+- Decision points with 2 clear options
+- Success/error states that need user action
+
+### When to Use Full-screen Modal (Present)
+- Creation flows (new post, compose message)
+- Complex forms that need full screen
+- Media preview/editing
+- Multi-step flows within a modal context
+
+### When NOT to Use Modal
+- Simple feedback → Use Toast or SnackBar
+- Informational notices → Use Information component
+- Navigation → Use Push transition
+- Content that user may need to reference while acting → Use inline UI
+
+---
+
+## Do's & Don'ts
+
+### Do's
+- Keep dialog content concise — title + 1–2 sentences max
+- Make primary action clear and descriptive ("Delete", not "OK")
+- Use destructive style (`danger` button type) for irreversible actions
+- Allow dismissal via background tap for non-critical dialogs
+
+### Don'ts
+- Don't stack modals on top of modals
+- Don't use modals for long forms — use full-screen modal (Present) instead
+- Don't use generic labels ("OK" / "Cancel") — be specific
+- Don't auto-dismiss important dialogs — require user action
+- Don't put scrollable content in a dialog modal

package/.claude/skills/design-system/references/navigation/navigation-options.md

@@ -0,0 +1,225 @@
+# Navigation Options — Design Guideline
+
+## Overview
+
+Navigation options configure screen headers — title types, right action buttons, background styles, and back behavior. These options are set dynamically per screen and control the header appearance and behavior.
+
+---
+
+## Header Title Types
+
+### Default Title
+- **Content**: Plain text string
+- **Typography**: `headline_s_bold`
+- **Color**: `theme.colors.text.default`
+- **Alignment**: Center-aligned within the header
+- **Max length**: ~20 characters (truncate with ellipsis)
+
+### User Title
+Shows a user profile in the header with avatar, name, subtitle, and optional verification icons.
+
+```
+┌──────────────────────────────────────────────┐
+│  [←]   [Avatar] John Doe [✓]      [🔍] [⋯]  │
+│                 Online                        │
+└──────────────────────────────────────────────┘
+```
+
+| Part             | Description                                    |
+|------------------|------------------------------------------------|
+| Avatar           | User profile image (circular, 32px)            |
+| Title            | User name, `headline_s_bold`                   |
+| Subtitle         | Status text (e.g., "Online"), `caption_default_regular` |
+| Status Dot       | Colored dot indicator on avatar                |
+| Verification Icons | Badge icons after the name                   |
+| Loading Skeleton | Placeholder skeleton while loading             |
+
+### Location Title
+Shows a location with dropdown chevron for location picker.
+
+```
+┌──────────────────────────────────────────────┐
+│  [←]   Ho Chi Minh City [▼]       [🔍] [⋯]  │
+│         Current location                      │
+└──────────────────────────────────────────────┘
+```
+
+| Part        | Description                                         |
+|-------------|-----------------------------------------------------|
+| Location    | Location name, `headline_s_bold`                     |
+| Description | Context text, `caption_default_regular`              |
+| Chevron     | Dropdown indicator, tappable to open location picker |
+
+### Journey Title
+Shows start and end points with directional indicator.
+
+```
+┌──────────────────────────────────────────────┐
+│  [←]   District 1 → District 7    [🔍] [⋯]  │
+│         12 km                                 │
+└──────────────────────────────────────────────┘
+```
+
+| Part        | Description                                          |
+|-------------|------------------------------------------------------|
+| Start       | Origin text, `headline_s_bold`                        |
+| Direction   | Arrow icon between start and end                      |
+| End         | Destination text, `headline_s_bold`                   |
+| Description | Distance or context, `caption_default_regular`        |
+
+---
+
+## Header Right Actions
+
+### Toolkit (Default)
+
+Standard header right configuration with help center, close/home button, and optional tool menu items.
+
+```
+┌──────────────────────────────────────────────┐
+│  [←]   Screen Title          [📌] [?] [🏠]   │
+└──────────────────────────────────────────────┘
+```
+
+| Part           | Description                                        |
+|----------------|----------------------------------------------------|
+| Help Button    | Opens help center (always present)                  |
+| Home/Close     | Navigate home or close screen (always present)      |
+| Shortcut Pin   | Pin/unpin to shortcuts (optional)                   |
+| Tool Items     | Additional action icons (optional)                  |
+
+**Tool menu behavior:**
+| Tool Count | Display                                           |
+|------------|---------------------------------------------------|
+| 0 tools    | Shows only help + close                            |
+| 1 tool     | Shows single tool icon directly in header          |
+| 2+ tools   | Shows `⋯` more button that opens a menu            |
+
+**Tool Item Spec:**
+
+| Property    | Description                                         |
+|-------------|-----------------------------------------------------|
+| Icon        | 24px icon name                                       |
+| Name        | Bilingual label `{ vi: '...', en: '...' }`          |
+| Key         | Unique identifier                                    |
+| Badge       | Optional badge indicator                             |
+
+### OnBoarding
+
+Simple text button for onboarding flows (e.g., "Skip" / "Bỏ qua").
+
+```
+┌──────────────────────────────────────────────┐
+│  [←]   Welcome                       [Skip]  │
+└──────────────────────────────────────────────┘
+```
+
+- **Typography**: `action_default_bold`
+- **Color**: `theme.colors.interactive.default`
+- **Touch target**: Minimum 44pt
+
+---
+
+## Header Background
+
+### Standard
+- **Color**: `theme.colors.background.surface`
+- **Bottom border**: 1px `theme.colors.border.default`
+
+### Gradient
+- **Color**: Custom gradient color (e.g., `#AF1F68`)
+- **Tint**: White icons and text on dark gradient backgrounds
+- **Override**: Replaces theme-based background
+
+### Custom Image
+- **Image**: Background image URL
+- **Overlay**: Semi-transparent overlay for text readability
+- **Tint**: White icons and text
+
+### Shadow
+- **Shadow**: Subtle bottom shadow for elevation effect
+- **Use when**: Header needs visual separation without a border line
+
+---
+
+## Animated Header
+
+Collapses from extended to default height on scroll.
+
+| Property        | Description                                     |
+|-----------------|-------------------------------------------------|
+| Expanded height | 88–120                                           |
+| Collapsed height| 44–56                                            |
+| Tint color      | Icon/text color (often white for custom backgrounds) |
+| Title           | Title shown in collapsed state                   |
+| Custom component| Optional component for expanded state            |
+
+---
+
+## Search Header
+
+Integrates InputSearch into an extended header.
+
+```
+┌──────────────────────────────────────────────┐
+│  [←]   Screen Title              [🔍] [⋯]    │
+│  ┌────────────────────────────────────────┐  │
+│  │  🔍  Search...                         │  │
+│  └────────────────────────────────────────┘  │
+└──────────────────────────────────────────────┘
+```
+
+- **Header type**: Must be `extended`
+- **Search bar**: Full-width InputSearch below the title area
+- **Animation**: Search expands on focus, collapses on cancel
+- **Filter button**: Optional action buttons alongside search
+
+---
+
+## Back Navigation
+
+### Standard Back
+- **Icon**: Chevron left, 24px
+- **Touch target**: 44x44pt
+- **Action**: Navigate back in the stack
+
+### Hidden Back
+- Hide the back button entirely (e.g., for root screens)
+
+### Custom Back Handler
+- Intercept the back action for custom logic
+- Example: show unsaved changes confirmation
+
+### Prevent Back (Confirmation Dialog)
+- Show a PopupNotify confirmation before allowing back navigation
+- Use for screens with unsaved changes or destructive navigation
+
+---
+
+## Usage Guidelines
+
+| Screen Type        | Title Type | Header Right  | Background    |
+|--------------------|-----------|---------------|---------------|
+| Standard detail    | Default   | Toolkit       | Standard      |
+| Chat/messaging     | User      | Toolkit       | Standard      |
+| Maps/location      | Location  | Toolkit       | Standard      |
+| Ride/delivery      | Journey   | Toolkit       | Standard      |
+| Onboarding flow    | Default   | OnBoarding    | Gradient      |
+| Search screen      | Default   | Toolkit       | Extended+Search |
+| Hero/marketing     | Default   | Toolkit       | Custom Image  |
+
+---
+
+## Do's & Don'ts
+
+### Do's
+- Use the appropriate title type for the screen context (User for profiles, Location for maps)
+- Provide bilingual labels `{ vi, en }` for all tool menu items
+- Use `preventBack` for screens with unsaved form data
+- Keep tool menu items to 3 or fewer per group
+
+### Don'ts
+- Don't put more than 3 action icons in the header right area
+- Don't mix OnBoarding and Toolkit header right styles
+- Don't use custom gradient backgrounds without adjusting tint color for contrast
+- Don't hide the back button on non-root screens without providing an alternative navigation path