@momo-kits/native-kits 0.157.1-skill.3 → 0.157.1-skill.6-debug

package/.claude/{momo-native-kits-skill → skills/momo-native-kits-skills}/references/constants.md

@@ -81,24 +81,51 @@ Design tokens and constants ensure consistent styling across the app.
 | `Colors.gray_08` | #616161 | ... |
 | `Colors.gray_09` | #424242 | Dark gray |
 
+### Semantic Mapping
+
+Use semantic colors from `AppTheme` for theme-aware UIs. Use `Colors.*` only when a specific color is needed regardless of theme.
+
+| Intent | Light Mode | Dark Mode | Usage |
+|--------|-----------|-----------|-------|
+| Primary text | `theme.colors.text.default` | Auto-adapts | Body, titles |
+| Secondary text | `theme.colors.text.secondary` | Auto-adapts | Captions, hints |
+| Disabled text | `theme.colors.text.disable` | Auto-adapts | Disabled states |
+| Surface | `theme.colors.background.surface` | Auto-adapts | Cards, sheets |
+| Error | `theme.colors.error.primary` | Auto-adapts | Error messages |
+| Brand CTA | `Colors.pink_01` | Same | Primary buttons |
+
+### Contrast & Accessibility
+
+- Text on backgrounds: minimum **4.5:1** contrast ratio (WCAG AA)
+- Large text (>= 20sp bold): minimum **3:1**
+- Safe pairs on light bg: `Colors.black_01`..`black_03` on `white_01`/`white_02`/`gray_01`..`gray_03`
+- Safe pairs on dark bg: `Colors.white_01`/`gray_01`..`gray_03` on `black_01`..`black_03`
+- Status colors: always use `_02` or darker variants for text, `_01` variants only for backgrounds
+- Never use color alone to convey meaning — pair with icons or text labels
+
 ### Usage
 
 ```kotlin
 import vn.momo.kits.const.Colors
 
-// Text color
+// Prefer semantic theme colors
+val theme = AppTheme.current
 Text(
     text = "Hello",
-    color = Colors.black_01
+    color = theme.colors.text.default  // adapts to light/dark
 )
 
-// Background
+// Use Colors.* for specific brand colors
 Box(
     modifier = Modifier.background(Colors.pink_01)
 ) { /* content */ }
 
-// Conditional color
-val statusColor = if (isSuccess) Colors.green_02 else Colors.red_02
+// Status colors: background + text pair
+Box(
+    modifier = Modifier.background(Colors.red_01)  // light bg
+) {
+    Text(text = "Error", color = Colors.red_04)     // dark text = good contrast
+}
 ```
 
 ---
@@ -151,6 +178,18 @@ Box(
 | `Spacing.XL` | 24.dp | Section spacing |
 | `Spacing.XXL` | 32.dp | Large gaps |
 
+### Contextual Rules
+
+| Context | Spacing | Example |
+|---------|---------|---------|
+| **Inset** (padding inside containers) | `Spacing.L` (16.dp) | Card content padding, screen padding |
+| **Stack** (between items in a list) | `Spacing.S`–`Spacing.M` (8–12.dp) | Form fields, list items |
+| **Inline** (between horizontal items) | `Spacing.S`–`Spacing.M` (8–12.dp) | Button + icon, label + badge |
+| **Section gap** (between content groups) | `Spacing.XL`–`Spacing.XXL` (24–32.dp) | Between form sections, card groups |
+| **Tight** (related sub-items) | `Spacing.XS` (4.dp) | Label + helper text, icon + text |
+
+**Rule of thumb:** related items → smaller spacing, distinct groups → larger spacing.
+
 ### Usage
 
 ```kotlin
@@ -189,6 +228,24 @@ Box(
 | `captionDefault` | 12sp | Regular | Captions |
 | `captionBold` | 12sp | Bold | Bold captions |
 
+### Pairing Rules
+
+Use these combinations to establish visual hierarchy:
+
+| Pattern | Title style | Body style | Caption style |
+|---------|------------|------------|---------------|
+| **Screen header** | `headlineDefaultBold` | `bodyDefault` | `captionDefault` |
+| **Card** | `titleDefaultBold` | `bodyDefault` | `captionDefault` |
+| **List item** | `bodyBold` | `bodySmall` | `captionDefault` |
+| **Form field** | — | `bodyDefault` (value) | `captionDefault` (label/error) |
+| **Button** | — | — | `actionDefaultBold` |
+
+**Rules:**
+- Max 3 typography levels per view (title + body + caption)
+- Bold variant for primary info, regular for secondary
+- `bodyDefault` (16sp) minimum for readable body text
+- `captionDefault` (12sp) only for non-essential info (timestamps, metadata)
+
 ### Usage
 
 ```kotlin
@@ -238,7 +295,7 @@ fun MyComponent() {
     Box(
         modifier = Modifier
             .background(theme.colors.background.surface)
-            .padding(theme.spacing?.let { Spacing.L } ?: 16.dp)
+            .padding(Spacing.L)
     ) {
         Text(
             text = "Themed text",
@@ -248,6 +305,24 @@ fun MyComponent() {
 }
 ```
 
+### Dark Mode Guidelines
+
+AppTheme auto-adapts colors for light/dark mode. Follow these rules:
+
+1. **Always use `theme.colors.*`** for surfaces, text, borders — they swap automatically
+2. **Surfaces in dark mode** use lighter shades (not shadows) for elevation hierarchy
+3. **Avoid `Colors.white_01` for backgrounds** — use `theme.colors.background.surface` instead
+4. **Status colors** (`Colors.red_*`, `Colors.green_*`) work in both modes, but prefer `theme.colors.error.*` when available
+5. **Test both modes** — check all screens in light and dark
+
+```kotlin
+// ✅ CORRECT — theme-aware
+Box(modifier = Modifier.background(AppTheme.current.colors.background.surface))
+
+// ❌ WRONG — hardcoded, breaks in dark mode
+Box(modifier = Modifier.background(Colors.white_01))
+```
+
 ---
 
 ## Best Practices

package/.claude/skills/momo-native-kits-skills/references/design-guidelines.md

@@ -0,0 +1,130 @@
+# Design Guidelines for MoMo Compose
+
+Actionable design principles for composing MoMo Native Kits components into well-structured screens.
+
+---
+
+## Visual Hierarchy
+
+Establish clear hierarchy so users see the most important content first.
+
+### Hierarchy Levels
+
+| Level | What | MoMo Implementation |
+|-------|------|---------------------|
+| **Primary** | Page title, main CTA | `Title(type = TITLE_1)` + `Button(type = PRIMARY)` |
+| **Secondary** | Section headings, key content | `Title(type = TITLE_2..3)` + `bodyBold` |
+| **Tertiary** | Supporting text, descriptions | `bodyDefault` / `bodySmall` + `theme.colors.text.secondary` |
+| **Quaternary** | Timestamps, metadata | `captionDefault` + `theme.colors.text.secondary` |
+
+### Rules
+
+1. **One primary CTA per screen** — use `ButtonType.PRIMARY` only once; others get `SECONDARY`/`OUTLINE`/`TEXT`
+2. **Size contrast >= 1.5x** between hierarchy levels (e.g. 24sp headline vs 16sp body)
+3. **Whitespace signals importance** — more `Spacing` around key elements isolates them visually
+4. **Color draws attention** — reserve `Colors.pink_01` for CTAs and critical info; don't overuse brand color
+
+### Screen Composition Pattern
+
+```kotlin
+Column(modifier = Modifier.padding(Spacing.L)) {
+    // Primary — seen first
+    Title(text = "Screen Title", type = TitleType.TITLE_1)
+
+    Spacer(modifier = Modifier.height(Spacing.XL))  // large gap = new section
+
+    // Secondary — scanned next
+    Title(text = "Section", type = TitleType.TITLE_3)
+
+    Spacer(modifier = Modifier.height(Spacing.S))    // small gap = related
+
+    // Tertiary — read on demand
+    Text(text = "Description...", style = Typography.bodyDefault,
+         color = AppTheme.current.colors.text.secondary)
+
+    Spacer(modifier = Modifier.height(Spacing.XXL))  // section break
+
+    // Primary CTA — anchored at bottom
+    Button(onClick = { }, title = "Continue", type = ButtonType.PRIMARY, isFull = true)
+}
+```
+
+---
+
+## Component Composition Patterns
+
+### Card Layout
+
+```
+Card
+├── Image / Icon (optional, visual anchor)
+├── Title (bodyBold or titleDefaultBold)
+├── Description (bodyDefault, text.secondary)
+└── Action (Button TEXT or OUTLINE, or clickable Card)
+```
+
+Spacing: `Spacing.L` inset, `Spacing.S` between internal items.
+
+### Form Layout
+
+```
+Column (spacedBy = Spacing.M)
+├── Input (floatingValue label)
+├── Input (floatingValue label)
+├── CheckBox (terms agreement)
+└── Button PRIMARY (submit, isFull = true)
+```
+
+Spacing: `Spacing.M` between fields, `Spacing.XL` before submit button.
+
+### List Item
+
+```
+Row
+├── Icon / Avatar (leading)
+├── Column
+│   ├── Text (bodyBold — primary info)
+│   └── Text (captionDefault, text.secondary — secondary info)
+└── Badge / Icon (trailing, optional)
+```
+
+Spacing: `Spacing.M` inline between leading/content/trailing.
+
+---
+
+## Spacing Decisions
+
+| Decision | Use |
+|----------|-----|
+| Items in same group | `Spacing.S` (8.dp) or `Spacing.M` (12.dp) |
+| Between groups / sections | `Spacing.XL` (24.dp) or `Spacing.XXL` (32.dp) |
+| Screen padding | `Spacing.L` (16.dp) |
+| Card internal padding | `Spacing.L` (16.dp) |
+| Icon-to-text gap | `Spacing.XS` (4.dp) or `Spacing.S` (8.dp) |
+| Before primary CTA | `Spacing.XL` (24.dp) minimum |
+
+---
+
+## Color Decisions
+
+| Decision | Use | Avoid |
+|----------|-----|-------|
+| Background | `theme.colors.background.surface` | Hardcoded `Colors.white_01` |
+| Primary text | `theme.colors.text.default` | `Colors.black_01` |
+| Secondary text | `theme.colors.text.secondary` | `Colors.gray_06` |
+| Disabled | `theme.colors.text.disable` | Custom opacity hacks |
+| Error text | `theme.colors.error.primary` or `Colors.red_04` | `Colors.red_01` (too light) |
+| Success feedback | `Colors.green_02` (icon/text) + `Colors.green_01` (bg) | Green text on green bg |
+| Brand accent | `Colors.pink_01` — sparingly | Pink on every element |
+
+---
+
+## Squint Test
+
+Before finalizing a screen, blur your eyes (or zoom to 25%). You should still see:
+1. Where the title is
+2. Where the primary action is
+3. Clear grouping of related content
+4. Separation between sections
+
+If everything looks the same size/weight, hierarchy is missing.

package/.claude/skills/momo-native-kits-skills/references/developer/android-compose.md

@@ -0,0 +1,29 @@
+---
+tags: android, compose, jetpack
+related: code-convention
+---
+
+# Android Compose Developer Reference
+
+## Scope
+
+Use this reference when creating or updating skills for Android UI with Jetpack Compose.
+
+## Core Stack
+
+1. Jetpack Compose for UI.
+2. Kotlin shared business/domain logic.
+3. MVVM with unidirectional state flow.
+
+## Implementation Rules
+
+1. Keep composables stateless where possible.
+2. Push side-effects and business rules to ViewModel/use-cases.
+3. Use shared Kotlin models for domain/state transformations.
+4. Keep Android-specific code in UI/platform adapters only.
+
+## Deliverables Required in Skills
+
+1. One composable screen example.
+2. One ViewModel + shared use-case integration example.
+3. Test checklist covering state reducer and UI rendering states.

package/.claude/skills/momo-native-kits-skills/references/developer/code-convention.md

@@ -0,0 +1,118 @@
+---
+tags: code, convention, formatting, style, lint, developer
+related:
+---
+
+# Code Convention
+
+Apply this convention to every AI-generated code output.
+
+## Scope and Consistency
+
+1. Use this document as the single source of truth for code-related skills.
+2. Any copied code-convention reference in other skills must be identical to this file.
+3. Apply header and marker requirements only to newly generated files or newly generated code blocks.
+4. Do not add markers/header to unchanged existing code.
+
+## 0) File Size and Line Width
+
+1. Keep each source file under about 500 lines.
+2. Enforce max line length (column width) of 120.
+3. If a file would exceed 500 lines, split by feature/module while preserving behavior.
+
+## 1) Required File Header
+
+Add a file header at the top of each newly generated code file with:
+
+1. `File`
+2. `Created At` (ISO-like timestamp with timezone)
+3. `Created By` (`AI`)
+4. `AI Agent`
+5. `Model`
+
+Template:
+
+```txt
+<COMMENT_OPEN>
+File: <relative-or-file-name>
+Created At: <YYYY-MM-DD HH:mm:ss Z>
+Created By: AI
+AI Agent: <agent-name>
+Model: <model-id>
+<COMMENT_CLOSE>
+```
+
+Language examples:
+
+```js
+/*
+File: src/example.js
+Created At: 2026-03-10 12:30:00 +07:00
+Created By: AI
+AI Agent: Codex
+Model: gpt-5
+*/
+```
+
+```py
+# File: src/example.py
+# Created At: 2026-03-10 12:30:00 +07:00
+# Created By: AI
+# AI Agent: Codex
+# Model: gpt-5
+```
+
+## 2) Required AI Block Markers
+
+Wrap every newly generated AI code block:
+
+- Start marker: `AI-GENERATED START`
+- End marker: `AI-GENERATED END`
+- Include short purpose text.
+
+JavaScript / TypeScript:
+
+```js
+// AI-GENERATED START: build payment retry helper
+function retryPayment() {
+  // ...
+}
+// AI-GENERATED END: build payment retry helper
+```
+
+Python:
+
+```py
+# AI-GENERATED START: parse webhook payload
+def parse_webhook(payload):
+    return payload
+# AI-GENERATED END: parse webhook payload
+```
+
+HTML / XML:
+
+```html
+<!-- AI-GENERATED START: login form -->
+<form></form>
+<!-- AI-GENERATED END: login form -->
+```
+
+CSS:
+
+```css
+/* AI-GENERATED START: card layout */
+.card { display: grid; }
+/* AI-GENERATED END: card layout */
+```
+
+## 3) Enforcement Checklist
+
+Before returning output, verify:
+
+1. File header exists at top of each newly generated file.
+2. Header includes filename, timestamp, AI creator, agent, and model.
+3. Every newly generated code block has start and end markers.
+4. Marker comment style matches target language.
+5. Unchanged existing code was not backfilled with new markers/header.
+6. New or modified files stay within ~500 lines.
+7. New or modified lines do not exceed 120 columns unless unavoidable.

package/.claude/skills/momo-native-kits-skills/references/developer/compose-multiplatform.md

@@ -0,0 +1,29 @@
+---
+tags: compose, multiplatform, kmp
+related: code-convention
+---
+
+# Compose Multiplatform Developer Reference
+
+## Scope
+
+Use this reference when creating skills for shared UI or multi-target UI with Compose Multiplatform.
+
+## Core Stack
+
+1. Compose Multiplatform for shared UI components where feasible.
+2. Shared Kotlin module for domain, data, and presentation logic.
+3. MVVM or MVI-compatible state management with shared state models.
+
+## Implementation Rules
+
+1. Keep platform-specific wrappers thin.
+2. Reuse shared Kotlin models and use-cases across Android/iOS/Desktop targets.
+3. Isolate platform APIs behind expect/actual or adapter boundaries.
+4. Avoid duplicating business logic in platform UI modules.
+
+## Deliverables Required in Skills
+
+1. Shared composable component/screen example.
+2. Platform adapter example (Android/iOS) calling shared logic.
+3. Test plan for shared module and target-specific integration checks.

package/.claude/skills/momo-native-kits-skills/scripts/logger.js

@@ -0,0 +1,63 @@
+/**
+ * File: scripts/logger.js
+ * Created At: 2026-03-16 10:00:00 +07:00
+ * Created By: AI
+ * AI Agent: Claude
+ * Model: opus-4-6
+ *
+ * Skill workflow logger
+ */
+
+// AI-GENERATED START: logger utility
+const fs = require('fs');
+const path = require('path');
+
+const SKILL_ROOT = path.resolve(__dirname, '..');
+const LOG_DIR = path.join(SKILL_ROOT, 'output', 'logs');
+
+function ensureLogDir() {
+    if (!fs.existsSync(LOG_DIR)) {
+        fs.mkdirSync(LOG_DIR, { recursive: true });
+    }
+}
+
+function getTimestamp() {
+    return new Date().toISOString();
+}
+
+function log(skillName, action, details = '') {
+    const timestamp = getTimestamp();
+    const message = `[${timestamp}] 🤖 ${skillName} | ${action} | ${details}`;
+
+    // Console output
+    console.log(message);
+
+    // File output
+    ensureLogDir();
+    const logFile = path.join(LOG_DIR, `${skillName}-${getTimestamp().split('T')[0]}.log`);
+    fs.appendFileSync(logFile, message + '\n');
+
+    return message;
+}
+
+function logWorkflow(skillName, steps) {
+    const timestamp = getTimestamp();
+    const workflowLog = {
+        skill: skillName,
+        timestamp,
+        steps
+    };
+
+    ensureLogDir();
+    const logFile = path.join(LOG_DIR, `${skillName}-workflow-${getTimestamp().split('T')[0]}.json`);
+    fs.appendFileSync(logFile, JSON.stringify(workflowLog, null, 2) + '\n');
+
+    return workflowLog;
+}
+
+module.exports = {
+    log,
+    logWorkflow,
+    getTimestamp
+};
+// AI-GENERATED END: logger utility

package/.claude/skills/momo-native-kits-skills/scripts/rules/badge.js

@@ -0,0 +1,32 @@
+/**
+ * Badge validation rules
+ */
+
+module.exports = [
+    {
+        id: 'badge-no-text',
+        category: 'Badge',
+        name: 'Badge uses "label" (not "text")',
+        severity: 'error',
+        applies: (content) => /\bBadge\s*\(/.test(content) && /vn\.momo\.kits/.test(content),
+        validate(content) {
+            if (/Badge\s*\([^)]*\btext\s*=/s.test(content)) {
+                return { passed: false, evidence: 'Badge has no "text" — use "label" instead' };
+            }
+            return { passed: true, evidence: 'Badge uses correct "label" param' };
+        }
+    },
+    {
+        id: 'badge-no-type',
+        category: 'Badge',
+        name: 'No BadgeType enum (does not exist)',
+        severity: 'error',
+        applies: (content) => /\bBadge\s*\(/.test(content) && /vn\.momo\.kits/.test(content),
+        validate(content) {
+            if (/BadgeType/.test(content)) {
+                return { passed: false, evidence: 'BadgeType does not exist — use backgroundColor: Color instead' };
+            }
+            return { passed: true, evidence: 'No invalid BadgeType usage' };
+        }
+    },
+];

package/.claude/skills/momo-native-kits-skills/scripts/rules/bottomtab.js

@@ -0,0 +1,19 @@
+/**
+ * BottomTab validation rules
+ */
+
+module.exports = [
+    {
+        id: 'bottomtab-items',
+        category: 'BottomTab',
+        name: 'BottomTab uses BottomTabItem (not TabItem)',
+        severity: 'error',
+        applies: (content) => /\bBottomTab\s*\(/.test(content) && /vn\.momo\.kits/.test(content),
+        validate(content) {
+            if (/\bTabItem\s*\(/.test(content) && !/BottomTabItem/.test(content)) {
+                return { passed: false, evidence: 'TabItem does not exist — use BottomTabItem(name, label, icon, screen)' };
+            }
+            return { passed: true, evidence: 'BottomTab item type looks correct' };
+        }
+    },
+];

package/.claude/skills/momo-native-kits-skills/scripts/rules/button.js

@@ -0,0 +1,32 @@
+/**
+ * Button validation rules
+ */
+
+module.exports = [
+    {
+        id: 'button-no-text',
+        category: 'Button',
+        name: 'Button uses "title" (not "text")',
+        severity: 'error',
+        applies: (content) => /\bButton\s*\(/.test(content) && /vn\.momo\.kits/.test(content),
+        validate(content) {
+            if (/Button\s*\([^)]*\btext\s*=/s.test(content)) {
+                return { passed: false, evidence: 'Button uses "text" — should be "title"' };
+            }
+            return { passed: true, evidence: 'Button uses correct param name' };
+        }
+    },
+    {
+        id: 'button-no-enabled',
+        category: 'Button',
+        name: 'Button has no "enabled" param',
+        severity: 'error',
+        applies: (content) => /\bButton\s*\(/.test(content) && /vn\.momo\.kits/.test(content),
+        validate(content) {
+            if (/Button\s*\([^)]*\benabled\s*=/s.test(content)) {
+                return { passed: false, evidence: 'Button has no "enabled" — use type = ButtonType.DISABLED instead' };
+            }
+            return { passed: true, evidence: 'No invalid "enabled" param on Button' };
+        }
+    },
+];

package/.claude/skills/momo-native-kits-skills/scripts/rules/card.js

@@ -0,0 +1,32 @@
+/**
+ * Card validation rules
+ */
+
+module.exports = [
+    {
+        id: 'card-no-material-card',
+        category: 'Card',
+        name: 'Card from vn.momo.kits (not Material)',
+        severity: 'error',
+        applies: (content) => /\bCard\s*\(/.test(content) && /vn\.momo\.kits/.test(content),
+        validate(content) {
+            if (/import\s+androidx\.compose\.material[3]?\.Card/.test(content)) {
+                return { passed: false, evidence: 'Import Material Card — use vn.momo.kits layout Card instead' };
+            }
+            return { passed: true, evidence: 'Card import looks correct' };
+        }
+    },
+    {
+        id: 'card-cornerRadius',
+        category: 'Card',
+        name: 'Card uses cornerRadius (not shape)',
+        severity: 'error',
+        applies: (content) => /\bCard\s*\(/.test(content) && /vn\.momo\.kits/.test(content),
+        validate(content) {
+            if (/Card\s*\([^)]*\bshape\s*=/s.test(content)) {
+                return { passed: false, evidence: 'Card has no "shape" — use "cornerRadius = Radius.M" instead' };
+            }
+            return { passed: true, evidence: 'No invalid "shape" param on Card' };
+        }
+    },
+];

package/.claude/skills/momo-native-kits-skills/scripts/rules/checkbox.js

@@ -0,0 +1,32 @@
+/**
+ * CheckBox validation rules
+ */
+
+module.exports = [
+    {
+        id: 'checkbox-no-enabled',
+        category: 'CheckBox',
+        name: 'CheckBox uses "disabled" (not "enabled")',
+        severity: 'error',
+        applies: (content) => /\bCheckBox\s*\(/.test(content) && /vn\.momo\.kits/.test(content),
+        validate(content) {
+            if (/CheckBox\s*\([^)]*\benabled\s*=/s.test(content)) {
+                return { passed: false, evidence: 'CheckBox has no "enabled" — use "disabled = true" instead' };
+            }
+            return { passed: true, evidence: 'CheckBox uses correct "disabled" param' };
+        }
+    },
+    {
+        id: 'checkbox-no-modifier',
+        category: 'CheckBox',
+        name: 'CheckBox has no modifier param',
+        severity: 'warning',
+        applies: (content) => /\bCheckBox\s*\(/.test(content) && /vn\.momo\.kits/.test(content),
+        validate(content) {
+            if (/CheckBox\s*\([^)]*\bmodifier\s*=/s.test(content)) {
+                return { passed: false, evidence: 'CheckBox has no "modifier" param — wrap in Box with modifier instead' };
+            }
+            return { passed: true, evidence: 'No invalid modifier on CheckBox' };
+        }
+    },
+];