@heyai-rules/pilo-masterkit 2.1.0 → 3.1.0

package/.agent/skills/mobile-design/mobile-navigation.md

@@ -1,458 +1,458 @@
-# Mobile Navigation Reference
-
-> Navigation patterns, deep linking, back handling, and tab/stack/drawer decisions.
-> **Navigation is the skeleton of your app—get it wrong and everything feels broken.**
-
----
-
-## 1. Navigation Selection Decision Tree
-
-```
-WHAT TYPE OF APP?
-        │
-        ├── 3-5 top-level sections (equal importance)
-        │   └── ✅ Tab Bar / Bottom Navigation
-        │       Examples: Social, E-commerce, Utility
-        │
-        ├── Deep hierarchical content (drill down)
-        │   └── ✅ Stack Navigation
-        │       Examples: Settings, Email folders
-        │
-        ├── Many destinations (>5 top-level)
-        │   └── ✅ Drawer Navigation
-        │       Examples: Gmail, complex enterprise
-        │
-        ├── Single linear flow
-        │   └── ✅ Stack only (wizard/onboarding)
-        │       Examples: Checkout, Setup flow
-        │
-        └── Tablet/Foldable
-            └── ✅ Navigation Rail + List-Detail
-                Examples: Mail, Notes on iPad
-```
-
----
-
-## 2. Tab Bar Navigation
-
-### When to Use
-
-```
-✅ USE Tab Bar when:
-├── 3-5 top-level destinations
-├── Destinations are of equal importance
-├── User frequently switches between them
-├── Each tab has independent navigation stack
-└── App is used in short sessions
-
-❌ AVOID Tab Bar when:
-├── More than 5 destinations
-├── Destinations have clear hierarchy
-├── Tabs would be used very unequally
-└── Content flows in a sequence
-```
-
-### Tab Bar Best Practices
-
-```
-iOS Tab Bar:
-├── Height: 49pt (83pt with home indicator)
-├── Max items: 5
-├── Icons: SF Symbols, 25×25pt
-├── Labels: Always show (accessibility)
-├── Active indicator: Tint color
-
-Android Bottom Navigation:
-├── Height: 80dp
-├── Max items: 5 (3-5 ideal)
-├── Icons: Material Symbols, 24dp
-├── Labels: Always show
-├── Active indicator: Pill shape + filled icon
-```
-
-### Tab State Preservation
-
-```
-RULE: Each tab maintains its own navigation stack.
-
-User journey:
-1. Home tab → Drill into item → Add to cart
-2. Switch to Profile tab
-3. Switch back to Home tab
-→ Should return to "Add to cart" screen, NOT home root
-
-Implementation:
-├── React Navigation: Each tab has own navigator
-├── Flutter: IndexedStack for state preservation
-└── Never reset tab stack on switch
-```
-
----
-
-## 3. Stack Navigation
-
-### Core Concepts
-
-```
-Stack metaphor: Cards stacked on top of each other
-
-Push: Add screen on top
-Pop: Remove top screen (back)
-Replace: Swap current screen
-Reset: Clear stack, set new root
-
-Visual: New screen slides in from right (LTR)
-Back: Screen slides out to right
-```
-
-### Stack Navigation Patterns
-
-| Pattern | Use Case | Implementation |
-|---------|----------|----------------|
-| **Simple Stack** | Linear flow | Push each step |
-| **Nested Stack** | Sections with sub-navigation | Stack inside tab |
-| **Modal Stack** | Focused tasks | Present modally |
-| **Auth Stack** | Login vs Main | Conditional root |
-
-### Back Button Handling
-
-```
-iOS:
-├── Edge swipe from left (system)
-├── Back button in nav bar (optional)
-├── Interactive pop gesture
-└── Never override swipe back without good reason
-
-Android:
-├── System back button/gesture
-├── Up button in toolbar (optional, for drill-down)
-├── Predictive back animation (Android 14+)
-└── Must handle back correctly (Activity/Fragment)
-
-Cross-Platform Rule:
-├── Back ALWAYS navigates up the stack
-├── Never hijack back for other purposes
-├── Confirm before discarding unsaved data
-└── Deep links should allow full back traversal
-```
-
----
-
-## 4. Drawer Navigation
-
-### When to Use
-
-```
-✅ USE Drawer when:
-├── More than 5 top-level destinations
-├── Less frequently accessed destinations
-├── Complex app with many features
-├── Need for branding/user info in nav
-└── Tablet/large screen with persistent drawer
-
-❌ AVOID Drawer when:
-├── 5 or fewer destinations (use tabs)
-├── All destinations equally important
-├── Mobile-first simple app
-└── Discoverability is critical (drawer is hidden)
-```
-
-### Drawer Patterns
-
-```
-Modal Drawer:
-├── Opens over content (scrim behind)
-├── Swipe to open from edge
-├── Hamburger icon ( ☰ ) triggers
-└── Most common on mobile
-
-Permanent Drawer:
-├── Always visible (large screens)
-├── Content shifts over
-├── Good for productivity apps
-└── Tablets, desktops
-
-Navigation Rail (Android):
-├── Narrow vertical strip
-├── Icons + optional labels
-├── For tablets in portrait
-└── 80dp width
-```
-
----
-
-## 5. Modal Navigation
-
-### Modal vs Push
-
-```
-PUSH (Stack):                    MODAL:
-├── Horizontal slide             ├── Vertical slide up (sheet)
-├── Part of hierarchy            ├── Separate task
-├── Back returns                 ├── Dismiss (X) returns
-├── Same navigation context      ├── Own navigation context
-└── "Drill in"                   └── "Focus on task"
-
-USE MODAL for:
-├── Creating new content
-├── Settings/preferences
-├── Completing a transaction
-├── Self-contained workflows
-├── Quick actions
-```
-
-### Modal Types
-
-| Type | iOS | Android | Use Case |
-|------|-----|---------|----------|
-| **Sheet** | `.sheet` | Bottom Sheet | Quick tasks |
-| **Full Screen** | `.fullScreenCover` | Full Activity | Complex forms |
-| **Alert** | Alert | Dialog | Confirmations |
-| **Action Sheet** | Action Sheet | Menu/Bottom Sheet | Choose from options |
-
-### Modal Dismissal
-
-```
-Users expect to dismiss modals by:
-├── Tapping X / Close button
-├── Swiping down (sheet)
-├── Tapping scrim (non-critical)
-├── System back (Android)
-├── Hardware back (old Android)
-
-RULE: Only block dismissal for unsaved data.
-```
-
----
-
-## 6. Deep Linking
-
-### Why Deep Links from Day One
-
-```
-Deep links enable:
-├── Push notification navigation
-├── Sharing content
-├── Marketing campaigns
-├── Spotlight/Search integration
-├── Widget navigation
-├── External app integration
-
-Building later is HARD:
-├── Requires navigation refactor
-├── Screen dependencies unclear
-├── Parameter passing complex
-└── Always plan deep links at start
-```
-
-### URL Structure
-
-```
-Scheme://host/path?params
-
-Examples:
-├── myapp://product/123
-├── https://myapp.com/product/123 (Universal/App Link)
-├── myapp://checkout?promo=SAVE20
-├── myapp://tab/profile/settings
-
-Hierarchy should match navigation:
-├── myapp://home
-├── myapp://home/product/123
-├── myapp://home/product/123/reviews
-└── URL path = navigation path
-```
-
-### Deep Link Navigation Rules
-
-```
-1. FULL STACK CONSTRUCTION
-   Deep link to myapp://product/123 should:
-   ├── Put Home at root of stack
-   ├── Push Product screen on top
-   └── Back button returns to Home
-
-2. AUTHENTICATION AWARENESS
-   If deep link requires auth:
-   ├── Save intended destination
-   ├── Redirect to login
-   ├── After login, navigate to destination
-
-3. INVALID LINKS
-   If deep link target doesn't exist:
-   ├── Navigate to fallback (home)
-   ├── Show error message
-   └── Never crash or blank screen
-
-4. STATEFUL NAVIGATION
-   Deep link during active session:
-   ├── Don't blow away current stack
-   ├── Push on top OR
-   ├── Ask user if should navigate away
-```
-
----
-
-## 7. Navigation State Persistence
-
-### What to Persist
-
-```
-SHOULD persist:
-├── Current tab selection
-├── Scroll position in lists
-├── Form draft data
-├── Recent navigation stack
-└── User preferences
-
-SHOULD NOT persist:
-├── Modal states (dialogs)
-├── Temporary UI states
-├── Stale data (refresh on return)
-├── Authentication state (use secure storage)
-```
-
-### Implementation
-
-```javascript
-// React Navigation - State Persistence
-const [isReady, setIsReady] = useState(false);
-const [initialState, setInitialState] = useState();
-
-useEffect(() => {
-  const loadState = async () => {
-    const savedState = await AsyncStorage.getItem('NAV_STATE');
-    if (savedState) setInitialState(JSON.parse(savedState));
-    setIsReady(true);
-  };
-  loadState();
-}, []);
-
-const handleStateChange = (state) => {
-  AsyncStorage.setItem('NAV_STATE', JSON.stringify(state));
-};
-
-<NavigationContainer
-  initialState={initialState}
-  onStateChange={handleStateChange}
->
-```
-
----
-
-## 8. Transition Animations
-
-### Platform Defaults
-
-```
-iOS Transitions:
-├── Push: Slide from right
-├── Modal: Slide from bottom (sheet) or fade
-├── Tab switch: Cross-fade
-├── Interactive: Swipe to go back
-
-Android Transitions:
-├── Push: Fade + slide from right
-├── Modal: Slide from bottom
-├── Tab switch: Cross-fade or none
-├── Shared element: Hero animations
-```
-
-### Custom Transitions
-
-```
-When to custom:
-├── Brand identity requires it
-├── Shared element connections
-├── Special reveal effects
-└── Keep it subtle, <300ms
-
-When to use default:
-├── Most of the time
-├── Standard drill-down
-├── Platform consistency
-└── Performance critical paths
-```
-
-### Shared Element Transitions
-
-```
-Connect elements between screens:
-
-Screen A: Product card with image
-            ↓ (tap)
-Screen B: Product detail with same image (expanded)
-
-Image animates from card position to detail position.
-
-Implementation:
-├── React Navigation: shared element library
-├── Flutter: Hero widget
-├── SwiftUI: matchedGeometryEffect
-└── Compose: Shared element transitions
-```
-
----
-
-## 9. Navigation Anti-Patterns
-
-### ❌ Navigation Sins
-
-| Anti-Pattern | Problem | Solution |
-|--------------|---------|----------|
-| **Inconsistent back** | User confused, can't predict | Always pop stack |
-| **Hidden navigation** | Features undiscoverable | Visible tabs/drawer trigger |
-| **Deep nesting** | User gets lost | Max 3-4 levels, breadcrumbs |
-| **Breaking swipe back** | iOS users frustrated | Never override gesture |
-| **No deep links** | Can't share, bad notifications | Plan from start |
-| **Tab stack reset** | Work lost on switch | Preserve tab states |
-| **Modal for primary flow** | Can't back track | Use stack navigation |
-
-### ❌ AI Navigation Mistakes
-
-```
-AI tends to:
-├── Use modals for everything (wrong)
-├── Forget tab state preservation (wrong)
-├── Skip deep linking (wrong)
-├── Override platform back behavior (wrong)
-├── Reset stack on tab switch (wrong)
-└── Ignore predictive back (Android 14+)
-
-RULE: Use platform navigation patterns.
-Don't reinvent navigation.
-```
-
----
-
-## 10. Navigation Checklist
-
-### Before Navigation Architecture
-
-- [ ] App type determined (tabs/drawer/stack)
-- [ ] Number of top-level destinations counted
-- [ ] Deep link URL scheme planned
-- [ ] Auth flow integrated with navigation
-- [ ] Tablet/large screen considered
-
-### Before Every Screen
-
-- [ ] Can user navigate back? (not dead end)
-- [ ] Deep link to this screen planned
-- [ ] State preserved on navigate away/back
-- [ ] Transition appropriate for relationship
-- [ ] Auth required? Handled?
-
-### Before Release
-
-- [ ] All deep links tested
-- [ ] Back button works everywhere
-- [ ] Tab states preserved correctly
-- [ ] Edge swipe back works (iOS)
-- [ ] Predictive back works (Android 14+)
-- [ ] Universal/App links configured
-- [ ] Push notification deep links work
-
----
-
-> **Remember:** Navigation is invisible when done right. Users shouldn't think about HOW to get somewhere—they just get there. If they notice navigation, something is wrong.
+# Mobile Navigation Reference
+
+> Navigation patterns, deep linking, back handling, and tab/stack/drawer decisions.
+> **Navigation is the skeleton of your app—get it wrong and everything feels broken.**
+
+---
+
+## 1. Navigation Selection Decision Tree
+
+```
+WHAT TYPE OF APP?
+        │
+        ├── 3-5 top-level sections (equal importance)
+        │   └── ✅ Tab Bar / Bottom Navigation
+        │       Examples: Social, E-commerce, Utility
+        │
+        ├── Deep hierarchical content (drill down)
+        │   └── ✅ Stack Navigation
+        │       Examples: Settings, Email folders
+        │
+        ├── Many destinations (>5 top-level)
+        │   └── ✅ Drawer Navigation
+        │       Examples: Gmail, complex enterprise
+        │
+        ├── Single linear flow
+        │   └── ✅ Stack only (wizard/onboarding)
+        │       Examples: Checkout, Setup flow
+        │
+        └── Tablet/Foldable
+            └── ✅ Navigation Rail + List-Detail
+                Examples: Mail, Notes on iPad
+```
+
+---
+
+## 2. Tab Bar Navigation
+
+### When to Use
+
+```
+✅ USE Tab Bar when:
+├── 3-5 top-level destinations
+├── Destinations are of equal importance
+├── User frequently switches between them
+├── Each tab has independent navigation stack
+└── App is used in short sessions
+
+❌ AVOID Tab Bar when:
+├── More than 5 destinations
+├── Destinations have clear hierarchy
+├── Tabs would be used very unequally
+└── Content flows in a sequence
+```
+
+### Tab Bar Best Practices
+
+```
+iOS Tab Bar:
+├── Height: 49pt (83pt with home indicator)
+├── Max items: 5
+├── Icons: SF Symbols, 25×25pt
+├── Labels: Always show (accessibility)
+├── Active indicator: Tint color
+
+Android Bottom Navigation:
+├── Height: 80dp
+├── Max items: 5 (3-5 ideal)
+├── Icons: Material Symbols, 24dp
+├── Labels: Always show
+├── Active indicator: Pill shape + filled icon
+```
+
+### Tab State Preservation
+
+```
+RULE: Each tab maintains its own navigation stack.
+
+User journey:
+1. Home tab → Drill into item → Add to cart
+2. Switch to Profile tab
+3. Switch back to Home tab
+→ Should return to "Add to cart" screen, NOT home root
+
+Implementation:
+├── React Navigation: Each tab has own navigator
+├── Flutter: IndexedStack for state preservation
+└── Never reset tab stack on switch
+```
+
+---
+
+## 3. Stack Navigation
+
+### Core Concepts
+
+```
+Stack metaphor: Cards stacked on top of each other
+
+Push: Add screen on top
+Pop: Remove top screen (back)
+Replace: Swap current screen
+Reset: Clear stack, set new root
+
+Visual: New screen slides in from right (LTR)
+Back: Screen slides out to right
+```
+
+### Stack Navigation Patterns
+
+| Pattern | Use Case | Implementation |
+|---------|----------|----------------|
+| **Simple Stack** | Linear flow | Push each step |
+| **Nested Stack** | Sections with sub-navigation | Stack inside tab |
+| **Modal Stack** | Focused tasks | Present modally |
+| **Auth Stack** | Login vs Main | Conditional root |
+
+### Back Button Handling
+
+```
+iOS:
+├── Edge swipe from left (system)
+├── Back button in nav bar (optional)
+├── Interactive pop gesture
+└── Never override swipe back without good reason
+
+Android:
+├── System back button/gesture
+├── Up button in toolbar (optional, for drill-down)
+├── Predictive back animation (Android 14+)
+└── Must handle back correctly (Activity/Fragment)
+
+Cross-Platform Rule:
+├── Back ALWAYS navigates up the stack
+├── Never hijack back for other purposes
+├── Confirm before discarding unsaved data
+└── Deep links should allow full back traversal
+```
+
+---
+
+## 4. Drawer Navigation
+
+### When to Use
+
+```
+✅ USE Drawer when:
+├── More than 5 top-level destinations
+├── Less frequently accessed destinations
+├── Complex app with many features
+├── Need for branding/user info in nav
+└── Tablet/large screen with persistent drawer
+
+❌ AVOID Drawer when:
+├── 5 or fewer destinations (use tabs)
+├── All destinations equally important
+├── Mobile-first simple app
+└── Discoverability is critical (drawer is hidden)
+```
+
+### Drawer Patterns
+
+```
+Modal Drawer:
+├── Opens over content (scrim behind)
+├── Swipe to open from edge
+├── Hamburger icon ( ☰ ) triggers
+└── Most common on mobile
+
+Permanent Drawer:
+├── Always visible (large screens)
+├── Content shifts over
+├── Good for productivity apps
+└── Tablets, desktops
+
+Navigation Rail (Android):
+├── Narrow vertical strip
+├── Icons + optional labels
+├── For tablets in portrait
+└── 80dp width
+```
+
+---
+
+## 5. Modal Navigation
+
+### Modal vs Push
+
+```
+PUSH (Stack):                    MODAL:
+├── Horizontal slide             ├── Vertical slide up (sheet)
+├── Part of hierarchy            ├── Separate task
+├── Back returns                 ├── Dismiss (X) returns
+├── Same navigation context      ├── Own navigation context
+└── "Drill in"                   └── "Focus on task"
+
+USE MODAL for:
+├── Creating new content
+├── Settings/preferences
+├── Completing a transaction
+├── Self-contained workflows
+├── Quick actions
+```
+
+### Modal Types
+
+| Type | iOS | Android | Use Case |
+|------|-----|---------|----------|
+| **Sheet** | `.sheet` | Bottom Sheet | Quick tasks |
+| **Full Screen** | `.fullScreenCover` | Full Activity | Complex forms |
+| **Alert** | Alert | Dialog | Confirmations |
+| **Action Sheet** | Action Sheet | Menu/Bottom Sheet | Choose from options |
+
+### Modal Dismissal
+
+```
+Users expect to dismiss modals by:
+├── Tapping X / Close button
+├── Swiping down (sheet)
+├── Tapping scrim (non-critical)
+├── System back (Android)
+├── Hardware back (old Android)
+
+RULE: Only block dismissal for unsaved data.
+```
+
+---
+
+## 6. Deep Linking
+
+### Why Deep Links from Day One
+
+```
+Deep links enable:
+├── Push notification navigation
+├── Sharing content
+├── Marketing campaigns
+├── Spotlight/Search integration
+├── Widget navigation
+├── External app integration
+
+Building later is HARD:
+├── Requires navigation refactor
+├── Screen dependencies unclear
+├── Parameter passing complex
+└── Always plan deep links at start
+```
+
+### URL Structure
+
+```
+Scheme://host/path?params
+
+Examples:
+├── myapp://product/123
+├── https://myapp.com/product/123 (Universal/App Link)
+├── myapp://checkout?promo=SAVE20
+├── myapp://tab/profile/settings
+
+Hierarchy should match navigation:
+├── myapp://home
+├── myapp://home/product/123
+├── myapp://home/product/123/reviews
+└── URL path = navigation path
+```
+
+### Deep Link Navigation Rules
+
+```
+1. FULL STACK CONSTRUCTION
+   Deep link to myapp://product/123 should:
+   ├── Put Home at root of stack
+   ├── Push Product screen on top
+   └── Back button returns to Home
+
+2. AUTHENTICATION AWARENESS
+   If deep link requires auth:
+   ├── Save intended destination
+   ├── Redirect to login
+   ├── After login, navigate to destination
+
+3. INVALID LINKS
+   If deep link target doesn't exist:
+   ├── Navigate to fallback (home)
+   ├── Show error message
+   └── Never crash or blank screen
+
+4. STATEFUL NAVIGATION
+   Deep link during active session:
+   ├── Don't blow away current stack
+   ├── Push on top OR
+   ├── Ask user if should navigate away
+```
+
+---
+
+## 7. Navigation State Persistence
+
+### What to Persist
+
+```
+SHOULD persist:
+├── Current tab selection
+├── Scroll position in lists
+├── Form draft data
+├── Recent navigation stack
+└── User preferences
+
+SHOULD NOT persist:
+├── Modal states (dialogs)
+├── Temporary UI states
+├── Stale data (refresh on return)
+├── Authentication state (use secure storage)
+```
+
+### Implementation
+
+```javascript
+// React Navigation - State Persistence
+const [isReady, setIsReady] = useState(false);
+const [initialState, setInitialState] = useState();
+
+useEffect(() => {
+  const loadState = async () => {
+    const savedState = await AsyncStorage.getItem('NAV_STATE');
+    if (savedState) setInitialState(JSON.parse(savedState));
+    setIsReady(true);
+  };
+  loadState();
+}, []);
+
+const handleStateChange = (state) => {
+  AsyncStorage.setItem('NAV_STATE', JSON.stringify(state));
+};
+
+<NavigationContainer
+  initialState={initialState}
+  onStateChange={handleStateChange}
+>
+```
+
+---
+
+## 8. Transition Animations
+
+### Platform Defaults
+
+```
+iOS Transitions:
+├── Push: Slide from right
+├── Modal: Slide from bottom (sheet) or fade
+├── Tab switch: Cross-fade
+├── Interactive: Swipe to go back
+
+Android Transitions:
+├── Push: Fade + slide from right
+├── Modal: Slide from bottom
+├── Tab switch: Cross-fade or none
+├── Shared element: Hero animations
+```
+
+### Custom Transitions
+
+```
+When to custom:
+├── Brand identity requires it
+├── Shared element connections
+├── Special reveal effects
+└── Keep it subtle, <300ms
+
+When to use default:
+├── Most of the time
+├── Standard drill-down
+├── Platform consistency
+└── Performance critical paths
+```
+
+### Shared Element Transitions
+
+```
+Connect elements between screens:
+
+Screen A: Product card with image
+            ↓ (tap)
+Screen B: Product detail with same image (expanded)
+
+Image animates from card position to detail position.
+
+Implementation:
+├── React Navigation: shared element library
+├── Flutter: Hero widget
+├── SwiftUI: matchedGeometryEffect
+└── Compose: Shared element transitions
+```
+
+---
+
+## 9. Navigation Anti-Patterns
+
+### ❌ Navigation Sins
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| **Inconsistent back** | User confused, can't predict | Always pop stack |
+| **Hidden navigation** | Features undiscoverable | Visible tabs/drawer trigger |
+| **Deep nesting** | User gets lost | Max 3-4 levels, breadcrumbs |
+| **Breaking swipe back** | iOS users frustrated | Never override gesture |
+| **No deep links** | Can't share, bad notifications | Plan from start |
+| **Tab stack reset** | Work lost on switch | Preserve tab states |
+| **Modal for primary flow** | Can't back track | Use stack navigation |
+
+### ❌ AI Navigation Mistakes
+
+```
+AI tends to:
+├── Use modals for everything (wrong)
+├── Forget tab state preservation (wrong)
+├── Skip deep linking (wrong)
+├── Override platform back behavior (wrong)
+├── Reset stack on tab switch (wrong)
+└── Ignore predictive back (Android 14+)
+
+RULE: Use platform navigation patterns.
+Don't reinvent navigation.
+```
+
+---
+
+## 10. Navigation Checklist
+
+### Before Navigation Architecture
+
+- [ ] App type determined (tabs/drawer/stack)
+- [ ] Number of top-level destinations counted
+- [ ] Deep link URL scheme planned
+- [ ] Auth flow integrated with navigation
+- [ ] Tablet/large screen considered
+
+### Before Every Screen
+
+- [ ] Can user navigate back? (not dead end)
+- [ ] Deep link to this screen planned
+- [ ] State preserved on navigate away/back
+- [ ] Transition appropriate for relationship
+- [ ] Auth required? Handled?
+
+### Before Release
+
+- [ ] All deep links tested
+- [ ] Back button works everywhere
+- [ ] Tab states preserved correctly
+- [ ] Edge swipe back works (iOS)
+- [ ] Predictive back works (Android 14+)
+- [ ] Universal/App links configured
+- [ ] Push notification deep links work
+
+---
+
+> **Remember:** Navigation is invisible when done right. Users shouldn't think about HOW to get somewhere—they just get there. If they notice navigation, something is wrong.