@heyai-rules/pilo-masterkit 1.2.2 → 2.2.0

package/.agent/skills/mobile-design/platform-ios.md

@@ -1,561 +1,561 @@
-# iOS Platform Guidelines
-
-> Human Interface Guidelines (HIG) essentials, iOS design conventions, SF Pro typography, and native patterns.
-> **Read this file when building for iPhone/iPad.**
-
----
-
-## 1. Human Interface Guidelines Philosophy
-
-### Core Apple Design Principles
-
-```
-CLARITY:
-├── Text is legible at every size
-├── Icons are precise and lucid
-├── Adornments are subtle and appropriate
-└── Focus on functionality drives design
-
-DEFERENCE:
-├── UI helps people understand and interact
-├── Content fills the screen
-├── UI never competes with content
-└── Translucency hints at more content
-
-DEPTH:
-├── Distinct visual layers convey hierarchy
-├── Transitions provide sense of depth
-├── Touch reveals functionality
-└── Content is elevated over UI
-```
-
-### iOS Design Values
-
-| Value | Implementation |
-|-------|----------------|
-| **Aesthetic Integrity** | Design matches function (game ≠ productivity) |
-| **Consistency** | Use system controls, familiar patterns |
-| **Direct Manipulation** | Touch directly affects content |
-| **Feedback** | Actions are acknowledged |
-| **Metaphors** | Real-world comparisons aid understanding |
-| **User Control** | User initiates actions, can cancel |
-
----
-
-## 2. iOS Typography
-
-### SF Pro Font Family
-
-```
-iOS System Fonts:
-├── SF Pro Text: Body text (< 20pt)
-├── SF Pro Display: Large titles (≥ 20pt)
-├── SF Pro Rounded: Friendly contexts
-├── SF Mono: Code, tabular data
-└── SF Compact: Apple Watch, smaller screens
-```
-
-### iOS Type Scale (Dynamic Type)
-
-| Style | Default Size | Weight | Usage |
-|-------|--------------|--------|-------|
-| **Large Title** | 34pt | Bold | Navigation bar (scroll collapse) |
-| **Title 1** | 28pt | Bold | Page titles |
-| **Title 2** | 22pt | Bold | Section headers |
-| **Title 3** | 20pt | Semibold | Subsection headers |
-| **Headline** | 17pt | Semibold | Emphasized body |
-| **Body** | 17pt | Regular | Primary content |
-| **Callout** | 16pt | Regular | Secondary content |
-| **Subhead** | 15pt | Regular | Tertiary content |
-| **Footnote** | 13pt | Regular | Caption, timestamps |
-| **Caption 1** | 12pt | Regular | Annotations |
-| **Caption 2** | 11pt | Regular | Fine print |
-
-### Dynamic Type Support (MANDATORY)
-
-```swift
-// ❌ WRONG: Fixed font size
-Text("Hello")
-    .font(.system(size: 17))
-
-// ✅ CORRECT: Dynamic Type
-Text("Hello")
-    .font(.body) // Scales with user settings
-
-// React Native equivalent
-<Text style={{ fontSize: 17 }}> // ❌ Fixed
-<Text style={styles.body}> // Use a dynamic scale system
-```
-
-### Font Weight Usage
-
-| Weight | iOS Constant | Use Case |
-|--------|--------------|----------|
-| Regular (400) | `.regular` | Body text |
-| Medium (500) | `.medium` | Buttons, emphasis |
-| Semibold (600) | `.semibold` | Subheadings |
-| Bold (700) | `.bold` | Titles, key info |
-| Heavy (800) | `.heavy` | Rarely, marketing |
-
----
-
-## 3. iOS Color System
-
-### System Colors (Semantic)
-
-```
-Use semantic colors for automatic dark mode:
-
-Primary:
-├── .label → Primary text
-├── .secondaryLabel → Secondary text
-├── .tertiaryLabel → Tertiary text
-├── .quaternaryLabel → Watermarks
-
-Backgrounds:
-├── .systemBackground → Main background
-├── .secondarySystemBackground → Grouped content
-├── .tertiarySystemBackground → Elevated content
-
-Fills:
-├── .systemFill → Large shapes
-├── .secondarySystemFill → Medium shapes
-├── .tertiarySystemFill → Small shapes
-├── .quaternarySystemFill → Subtle shapes
-```
-
-### System Accent Colors
-
-| Color | Light Mode | Dark Mode | Usage |
-|-------|------------|-----------|-------|
-| Blue | #007AFF | #0A84FF | Links, highlights, default tint |
-| Green | #34C759 | #30D158 | Success, positive |
-| Red | #FF3B30 | #FF453A | Errors, destructive |
-| Orange | #FF9500 | #FF9F0A | Warnings |
-| Yellow | #FFCC00 | #FFD60A | Attention |
-| Purple | #AF52DE | #BF5AF2 | Special features |
-| Pink | #FF2D55 | #FF375F | Affection, favorites |
-| Teal | #5AC8FA | #64D2FF | Information |
-
-### Dark Mode Considerations
-
-```
-iOS Dark Mode is not inverted light mode:
-
-LIGHT MODE:              DARK MODE:
-├── White backgrounds    ├── True black (#000) or near-black
-├── High saturation      ├── Desaturated colors
-├── Black text           ├── White/light gray text
-└── Drop shadows         └── Glows or no shadows
-
-RULE: Always use semantic colors for automatic adaptation.
-```
-
----
-
-## 4. iOS Layout & Spacing
-
-### Safe Areas
-
-```
-┌─────────────────────────────────────┐
-│░░░░░░░░░░░ Status Bar ░░░░░░░░░░░░░│ ← Top safe area inset
-├─────────────────────────────────────┤
-│                                     │
-│                                     │
-│         Safe Content Area           │
-│                                     │
-│                                     │
-├─────────────────────────────────────┤
-│░░░░░░░░░ Home Indicator ░░░░░░░░░░░│ ← Bottom safe area inset
-└─────────────────────────────────────┘
-
-RULE: Never place interactive content in unsafe areas.
-```
-
-### Standard Margins & Padding
-
-| Element | Margin | Notes |
-|---------|--------|-------|
-| Screen edge → content | 16pt | Standard horizontal margin |
-| Grouped table sections | 16pt top/bottom | Breathing room |
-| List item padding | 16pt horizontal | Standard cell padding |
-| Card internal padding | 16pt | Content within cards |
-| Button internal padding | 12pt vertical, 16pt horizontal | Minimum |
-
-### iOS Grid System
-
-```
-iPhone Grid (Standard):
-├── 16pt margins (left/right)
-├── 8pt minimum spacing
-├── Content in 8pt multiples
-
-iPhone Grid (Compact):
-├── 8pt margins (when needed)
-├── 4pt minimum spacing
-
-iPad Grid:
-├── 20pt margins (or more)
-├── Consider multi-column layouts
-```
-
----
-
-## 5. iOS Navigation Patterns
-
-### Navigation Types
-
-| Pattern | Use Case | Implementation |
-|---------|----------|----------------|
-| **Tab Bar** | 3-5 top-level sections | Bottom, always visible |
-| **Navigation Controller** | Hierarchical drill-down | Stack-based, back button |
-| **Modal** | Focused task, interruption | Sheet or full-screen |
-| **Sidebar** | iPad, multi-column | Left sidebar (iPad) |
-
-### Tab Bar Guidelines
-
-```
-┌─────────────────────────────────────┐
-│                                     │
-│         Content Area                │
-│                                     │
-├─────────────────────────────────────┤
-│  🏠     🔍     ➕     ❤️     👤    │ ← Tab bar (49pt height)
-│ Home   Search  New   Saved  Profile │
-└─────────────────────────────────────┘
-
-Rules:
-├── 3-5 items maximum
-├── Icons: SF Symbols or custom (25×25pt)
-├── Labels: Always include (accessibility)
-├── Active state: Filled icon + tint color
-└── Tab bar always visible (don't hide on scroll)
-```
-
-### Navigation Bar Guidelines
-
-```
-┌─────────────────────────────────────┐
-│ < Back     Page Title      Edit    │ ← Navigation bar (44pt)
-├─────────────────────────────────────┤
-│                                     │
-│         Content Area                │
-│                                     │
-└─────────────────────────────────────┘
-
-Rules:
-├── Back button: System chevron + previous title (or "Back")
-├── Title: Centered, dynamic font
-├── Right actions: Max 2 items
-├── Large title: Collapses on scroll (optional)
-└── Prefer text buttons over icons (clarity)
-```
-
-### Modal Presentations
-
-| Style | Use Case | Appearance |
-|-------|----------|------------|
-| **Sheet (default)** | Secondary tasks | Card slides up, parent visible |
-| **Full Screen** | Immersive tasks | Covers entire screen |
-| **Popover** | iPad, quick info | Arrow-pointed bubble |
-| **Alert** | Critical interruption | Centered dialog |
-| **Action Sheet** | Choices from context | Bottom sheet with options |
-
-### Gestures
-
-| Gesture | iOS Convention |
-|---------|----------------|
-| **Edge swipe (left)** | Navigate back |
-| **Pull down (sheet)** | Dismiss modal |
-| **Long press** | Context menu |
-| **Deep press** | Peek/Pop (legacy) |
-| **Two-finger swipe** | Scroll in nested scroll |
-
----
-
-## 6. iOS Components
-
-### Buttons
-
-```
-Button Styles (UIKit/SwiftUI):
-
-┌──────────────────────────────┐
-│         Tinted               │ ← Primary action (filled)
-├──────────────────────────────┤
-│         Bordered             │ ← Secondary action (outline)
-├──────────────────────────────┤
-│         Plain                │ ← Tertiary action (text only)
-└──────────────────────────────┘
-
-Sizes:
-├── Mini: Tight spaces
-├── Small: Compact UI
-├── Medium: Inline actions
-├── Large: Primary CTAs (44pt minimum height)
-```
-
-### Lists & Tables
-
-```
-List Styles:
-
-.plain         → No separators, edge-to-edge
-.insetGrouped  → Rounded cards (default iOS 14+)
-.grouped       → Full-width sections
-.sidebar       → iPad sidebar navigation
-
-Cell Accessories:
-├── Disclosure indicator (>) → Navigates to detail
-├── Detail button (i) → Shows info without navigation
-├── Checkmark (✓) → Selection
-├── Reorder (≡) → Drag to reorder
-└── Delete (-) → Swipe/edit mode delete
-```
-
-### Text Fields
-
-```
-iOS Text Field Anatomy:
-
-┌─────────────────────────────────────┐
-│ 🔍 Search...                    ✕  │
-└─────────────────────────────────────┘
-  ↑                               ↑
-  Leading icon                   Clear button
-
-Borders: Rounded rectangle
-Height: 36pt minimum
-Placeholder: Secondary text color
-Clear button: Appears when has text
-```
-
-### Segmented Controls
-
-```
-When to Use:
-├── 2-5 related options
-├── Filter content
-├── Switch views
-
-┌───────┬───────┬───────┐
-│  All  │ Active│ Done  │
-└───────┴───────┴───────┘
-
-Rules:
-├── Equal width segments
-├── Text or icons (not both mixed)
-├── Max 5 segments
-└── Consider tabs if more complex
-```
-
----
-
-## 7. iOS Specific Patterns
-
-### Pull to Refresh
-
-```
-Native UIRefreshControl behavior:
-├── Pull beyond threshold → Spinner appears
-├── Release → Refresh action triggered
-├── Loading state → Spinner spins
-├── Complete → Spinner disappears
-
-RULE: Always use native UIRefreshControl (don't custom build).
-```
-
-### Swipe Actions
-
-```
-iOS swipe actions:
-
-← Swipe Left (Destructive)      Swipe Right (Constructive) →
-┌─────────────────────────────────────────────────────────────┐
-│                    List Item Content                        │
-└─────────────────────────────────────────────────────────────┘
-
-Left swipe reveals: Archive, Delete, Flag
-Right swipe reveals: Pin, Star, Mark as Read
-
-Full swipe: Triggers first action
-```
-
-### Context Menus
-
-```
-Long press → Context menu appears
-
-┌─────────────────────────────┐
-│       Preview Card          │
-├─────────────────────────────┤
-│  📋 Copy                    │
-│  📤 Share                   │
-│  ➕ Add to...               │
-├─────────────────────────────┤
-│  🗑️ Delete          (Red)   │
-└─────────────────────────────┘
-
-Rules:
-├── Preview: Show enlarged content
-├── Actions: Related to content
-├── Destructive: Last, in red
-└── Max ~8 actions (scrollable if more)
-```
-
-### Sheets & Half-Sheets
-
-```
-iOS 15+ Sheets:
-
-┌─────────────────────────────────────┐
-│                                     │
-│        Parent View (dimmed)          │
-│                                     │
-├─────────────────────────────────────┤
-│  ═══  (Grabber)                     │ ← Drag to resize
-│                                     │
-│        Sheet Content                │
-│                                     │
-│                                     │
-└─────────────────────────────────────┘
-
-Detents:
-├── .medium → Half screen
-├── .large → Full screen (with safe area)
-├── Custom → Specific height
-```
-
----
-
-## 8. SF Symbols
-
-### Usage Guidelines
-
-```
-SF Symbols: Apple's icon library (5000+ icons)
-
-Weights: Match text weight
-├── Ultralight / Thin / Light
-├── Regular / Medium / Semibold
-├── Bold / Heavy / Black
-
-Scales:
-├── .small → Inline with small text
-├── .medium → Standard UI
-├── .large → Emphasis, standalone
-```
-
-### Symbol Configurations
-
-```swift
-// SwiftUI
-Image(systemName: "star.fill")
-    .font(.title2)
-    .foregroundStyle(.yellow)
-
-// With rendering mode
-Image(systemName: "heart.fill")
-    .symbolRenderingMode(.multicolor)
-
-// Animated (iOS 17+)
-Image(systemName: "checkmark.circle")
-    .symbolEffect(.bounce)
-```
-
-### Symbol Best Practices
-
-| Guideline | Implementation |
-|-----------|----------------|
-| Match text weight | Symbol weight = font weight |
-| Use standard symbols | Users recognize them |
-| Multicolor when meaningful | Not just decoration |
-| Fallback for older iOS | Check availability |
-
----
-
-## 9. iOS Accessibility
-
-### VoiceOver Requirements
-
-```
-Every interactive element needs:
-├── Accessibility label (what it is)
-├── Accessibility hint (what it does) - optional
-├── Accessibility traits (button, link, etc.)
-└── Accessibility value (current state)
-
-SwiftUI:
-.accessibilityLabel("Play")
-.accessibilityHint("Plays the selected track")
-
-React Native:
-accessibilityLabel="Play"
-accessibilityHint="Plays the selected track"
-accessibilityRole="button"
-```
-
-### Dynamic Type Scaling
-
-```
-MANDATORY: Support Dynamic Type
-
-Users can set text size from:
-├── xSmall → 14pt body
-├── Small → 15pt body
-├── Medium → 16pt body
-├── Large (Default) → 17pt body
-├── xLarge → 19pt body
-├── xxLarge → 21pt body
-├── xxxLarge → 23pt body
-├── Accessibility sizes → up to 53pt
-
-Your app MUST scale gracefully at all sizes.
-```
-
-### Reduce Motion
-
-```
-Respect motion preferences:
-
-@Environment(\.accessibilityReduceMotion) var reduceMotion
-
-if reduceMotion {
-    // Use instant transitions
-} else {
-    // Use animations
-}
-
-React Native:
-import { AccessibilityInfo } from 'react-native';
-AccessibilityInfo.isReduceMotionEnabled()
-```
-
----
-
-## 10. iOS Checklist
-
-### Before Every iOS Screen
-
-- [ ] Using SF Pro or SF Symbols
-- [ ] Dynamic Type supported
-- [ ] Safe areas respected
-- [ ] Navigation follows HIG (back gesture works)
-- [ ] Tab bar items ≤ 5
-- [ ] Touch targets ≥ 44pt
-
-### Before iOS Release
-
-- [ ] Dark mode tested
-- [ ] All text sizes tested (Accessibility Inspector)
-- [ ] VoiceOver tested
-- [ ] Edge swipe back works everywhere
-- [ ] Keyboard avoidance implemented
-- [ ] Notch/Dynamic Island handled
-- [ ] Home indicator area respected
-- [ ] Native components used where possible
-
----
-
-> **Remember:** iOS users have strong expectations from other iOS apps. Deviating from HIG patterns feels "broken" to them. When in doubt, use the native component.
+# iOS Platform Guidelines
+
+> Human Interface Guidelines (HIG) essentials, iOS design conventions, SF Pro typography, and native patterns.
+> **Read this file when building for iPhone/iPad.**
+
+---
+
+## 1. Human Interface Guidelines Philosophy
+
+### Core Apple Design Principles
+
+```
+CLARITY:
+├── Text is legible at every size
+├── Icons are precise and lucid
+├── Adornments are subtle and appropriate
+└── Focus on functionality drives design
+
+DEFERENCE:
+├── UI helps people understand and interact
+├── Content fills the screen
+├── UI never competes with content
+└── Translucency hints at more content
+
+DEPTH:
+├── Distinct visual layers convey hierarchy
+├── Transitions provide sense of depth
+├── Touch reveals functionality
+└── Content is elevated over UI
+```
+
+### iOS Design Values
+
+| Value | Implementation |
+|-------|----------------|
+| **Aesthetic Integrity** | Design matches function (game ≠ productivity) |
+| **Consistency** | Use system controls, familiar patterns |
+| **Direct Manipulation** | Touch directly affects content |
+| **Feedback** | Actions are acknowledged |
+| **Metaphors** | Real-world comparisons aid understanding |
+| **User Control** | User initiates actions, can cancel |
+
+---
+
+## 2. iOS Typography
+
+### SF Pro Font Family
+
+```
+iOS System Fonts:
+├── SF Pro Text: Body text (< 20pt)
+├── SF Pro Display: Large titles (≥ 20pt)
+├── SF Pro Rounded: Friendly contexts
+├── SF Mono: Code, tabular data
+└── SF Compact: Apple Watch, smaller screens
+```
+
+### iOS Type Scale (Dynamic Type)
+
+| Style | Default Size | Weight | Usage |
+|-------|--------------|--------|-------|
+| **Large Title** | 34pt | Bold | Navigation bar (scroll collapse) |
+| **Title 1** | 28pt | Bold | Page titles |
+| **Title 2** | 22pt | Bold | Section headers |
+| **Title 3** | 20pt | Semibold | Subsection headers |
+| **Headline** | 17pt | Semibold | Emphasized body |
+| **Body** | 17pt | Regular | Primary content |
+| **Callout** | 16pt | Regular | Secondary content |
+| **Subhead** | 15pt | Regular | Tertiary content |
+| **Footnote** | 13pt | Regular | Caption, timestamps |
+| **Caption 1** | 12pt | Regular | Annotations |
+| **Caption 2** | 11pt | Regular | Fine print |
+
+### Dynamic Type Support (MANDATORY)
+
+```swift
+// ❌ WRONG: Fixed font size
+Text("Hello")
+    .font(.system(size: 17))
+
+// ✅ CORRECT: Dynamic Type
+Text("Hello")
+    .font(.body) // Scales with user settings
+
+// React Native equivalent
+<Text style={{ fontSize: 17 }}> // ❌ Fixed
+<Text style={styles.body}> // Use a dynamic scale system
+```
+
+### Font Weight Usage
+
+| Weight | iOS Constant | Use Case |
+|--------|--------------|----------|
+| Regular (400) | `.regular` | Body text |
+| Medium (500) | `.medium` | Buttons, emphasis |
+| Semibold (600) | `.semibold` | Subheadings |
+| Bold (700) | `.bold` | Titles, key info |
+| Heavy (800) | `.heavy` | Rarely, marketing |
+
+---
+
+## 3. iOS Color System
+
+### System Colors (Semantic)
+
+```
+Use semantic colors for automatic dark mode:
+
+Primary:
+├── .label → Primary text
+├── .secondaryLabel → Secondary text
+├── .tertiaryLabel → Tertiary text
+├── .quaternaryLabel → Watermarks
+
+Backgrounds:
+├── .systemBackground → Main background
+├── .secondarySystemBackground → Grouped content
+├── .tertiarySystemBackground → Elevated content
+
+Fills:
+├── .systemFill → Large shapes
+├── .secondarySystemFill → Medium shapes
+├── .tertiarySystemFill → Small shapes
+├── .quaternarySystemFill → Subtle shapes
+```
+
+### System Accent Colors
+
+| Color | Light Mode | Dark Mode | Usage |
+|-------|------------|-----------|-------|
+| Blue | #007AFF | #0A84FF | Links, highlights, default tint |
+| Green | #34C759 | #30D158 | Success, positive |
+| Red | #FF3B30 | #FF453A | Errors, destructive |
+| Orange | #FF9500 | #FF9F0A | Warnings |
+| Yellow | #FFCC00 | #FFD60A | Attention |
+| Purple | #AF52DE | #BF5AF2 | Special features |
+| Pink | #FF2D55 | #FF375F | Affection, favorites |
+| Teal | #5AC8FA | #64D2FF | Information |
+
+### Dark Mode Considerations
+
+```
+iOS Dark Mode is not inverted light mode:
+
+LIGHT MODE:              DARK MODE:
+├── White backgrounds    ├── True black (#000) or near-black
+├── High saturation      ├── Desaturated colors
+├── Black text           ├── White/light gray text
+└── Drop shadows         └── Glows or no shadows
+
+RULE: Always use semantic colors for automatic adaptation.
+```
+
+---
+
+## 4. iOS Layout & Spacing
+
+### Safe Areas
+
+```
+┌─────────────────────────────────────┐
+│░░░░░░░░░░░ Status Bar ░░░░░░░░░░░░░│ ← Top safe area inset
+├─────────────────────────────────────┤
+│                                     │
+│                                     │
+│         Safe Content Area           │
+│                                     │
+│                                     │
+├─────────────────────────────────────┤
+│░░░░░░░░░ Home Indicator ░░░░░░░░░░░│ ← Bottom safe area inset
+└─────────────────────────────────────┘
+
+RULE: Never place interactive content in unsafe areas.
+```
+
+### Standard Margins & Padding
+
+| Element | Margin | Notes |
+|---------|--------|-------|
+| Screen edge → content | 16pt | Standard horizontal margin |
+| Grouped table sections | 16pt top/bottom | Breathing room |
+| List item padding | 16pt horizontal | Standard cell padding |
+| Card internal padding | 16pt | Content within cards |
+| Button internal padding | 12pt vertical, 16pt horizontal | Minimum |
+
+### iOS Grid System
+
+```
+iPhone Grid (Standard):
+├── 16pt margins (left/right)
+├── 8pt minimum spacing
+├── Content in 8pt multiples
+
+iPhone Grid (Compact):
+├── 8pt margins (when needed)
+├── 4pt minimum spacing
+
+iPad Grid:
+├── 20pt margins (or more)
+├── Consider multi-column layouts
+```
+
+---
+
+## 5. iOS Navigation Patterns
+
+### Navigation Types
+
+| Pattern | Use Case | Implementation |
+|---------|----------|----------------|
+| **Tab Bar** | 3-5 top-level sections | Bottom, always visible |
+| **Navigation Controller** | Hierarchical drill-down | Stack-based, back button |
+| **Modal** | Focused task, interruption | Sheet or full-screen |
+| **Sidebar** | iPad, multi-column | Left sidebar (iPad) |
+
+### Tab Bar Guidelines
+
+```
+┌─────────────────────────────────────┐
+│                                     │
+│         Content Area                │
+│                                     │
+├─────────────────────────────────────┤
+│  🏠     🔍     ➕     ❤️     👤    │ ← Tab bar (49pt height)
+│ Home   Search  New   Saved  Profile │
+└─────────────────────────────────────┘
+
+Rules:
+├── 3-5 items maximum
+├── Icons: SF Symbols or custom (25×25pt)
+├── Labels: Always include (accessibility)
+├── Active state: Filled icon + tint color
+└── Tab bar always visible (don't hide on scroll)
+```
+
+### Navigation Bar Guidelines
+
+```
+┌─────────────────────────────────────┐
+│ < Back     Page Title      Edit    │ ← Navigation bar (44pt)
+├─────────────────────────────────────┤
+│                                     │
+│         Content Area                │
+│                                     │
+└─────────────────────────────────────┘
+
+Rules:
+├── Back button: System chevron + previous title (or "Back")
+├── Title: Centered, dynamic font
+├── Right actions: Max 2 items
+├── Large title: Collapses on scroll (optional)
+└── Prefer text buttons over icons (clarity)
+```
+
+### Modal Presentations
+
+| Style | Use Case | Appearance |
+|-------|----------|------------|
+| **Sheet (default)** | Secondary tasks | Card slides up, parent visible |
+| **Full Screen** | Immersive tasks | Covers entire screen |
+| **Popover** | iPad, quick info | Arrow-pointed bubble |
+| **Alert** | Critical interruption | Centered dialog |
+| **Action Sheet** | Choices from context | Bottom sheet with options |
+
+### Gestures
+
+| Gesture | iOS Convention |
+|---------|----------------|
+| **Edge swipe (left)** | Navigate back |
+| **Pull down (sheet)** | Dismiss modal |
+| **Long press** | Context menu |
+| **Deep press** | Peek/Pop (legacy) |
+| **Two-finger swipe** | Scroll in nested scroll |
+
+---
+
+## 6. iOS Components
+
+### Buttons
+
+```
+Button Styles (UIKit/SwiftUI):
+
+┌──────────────────────────────┐
+│         Tinted               │ ← Primary action (filled)
+├──────────────────────────────┤
+│         Bordered             │ ← Secondary action (outline)
+├──────────────────────────────┤
+│         Plain                │ ← Tertiary action (text only)
+└──────────────────────────────┘
+
+Sizes:
+├── Mini: Tight spaces
+├── Small: Compact UI
+├── Medium: Inline actions
+├── Large: Primary CTAs (44pt minimum height)
+```
+
+### Lists & Tables
+
+```
+List Styles:
+
+.plain         → No separators, edge-to-edge
+.insetGrouped  → Rounded cards (default iOS 14+)
+.grouped       → Full-width sections
+.sidebar       → iPad sidebar navigation
+
+Cell Accessories:
+├── Disclosure indicator (>) → Navigates to detail
+├── Detail button (i) → Shows info without navigation
+├── Checkmark (✓) → Selection
+├── Reorder (≡) → Drag to reorder
+└── Delete (-) → Swipe/edit mode delete
+```
+
+### Text Fields
+
+```
+iOS Text Field Anatomy:
+
+┌─────────────────────────────────────┐
+│ 🔍 Search...                    ✕  │
+└─────────────────────────────────────┘
+  ↑                               ↑
+  Leading icon                   Clear button
+
+Borders: Rounded rectangle
+Height: 36pt minimum
+Placeholder: Secondary text color
+Clear button: Appears when has text
+```
+
+### Segmented Controls
+
+```
+When to Use:
+├── 2-5 related options
+├── Filter content
+├── Switch views
+
+┌───────┬───────┬───────┐
+│  All  │ Active│ Done  │
+└───────┴───────┴───────┘
+
+Rules:
+├── Equal width segments
+├── Text or icons (not both mixed)
+├── Max 5 segments
+└── Consider tabs if more complex
+```
+
+---
+
+## 7. iOS Specific Patterns
+
+### Pull to Refresh
+
+```
+Native UIRefreshControl behavior:
+├── Pull beyond threshold → Spinner appears
+├── Release → Refresh action triggered
+├── Loading state → Spinner spins
+├── Complete → Spinner disappears
+
+RULE: Always use native UIRefreshControl (don't custom build).
+```
+
+### Swipe Actions
+
+```
+iOS swipe actions:
+
+← Swipe Left (Destructive)      Swipe Right (Constructive) →
+┌─────────────────────────────────────────────────────────────┐
+│                    List Item Content                        │
+└─────────────────────────────────────────────────────────────┘
+
+Left swipe reveals: Archive, Delete, Flag
+Right swipe reveals: Pin, Star, Mark as Read
+
+Full swipe: Triggers first action
+```
+
+### Context Menus
+
+```
+Long press → Context menu appears
+
+┌─────────────────────────────┐
+│       Preview Card          │
+├─────────────────────────────┤
+│  📋 Copy                    │
+│  📤 Share                   │
+│  ➕ Add to...               │
+├─────────────────────────────┤
+│  🗑️ Delete          (Red)   │
+└─────────────────────────────┘
+
+Rules:
+├── Preview: Show enlarged content
+├── Actions: Related to content
+├── Destructive: Last, in red
+└── Max ~8 actions (scrollable if more)
+```
+
+### Sheets & Half-Sheets
+
+```
+iOS 15+ Sheets:
+
+┌─────────────────────────────────────┐
+│                                     │
+│        Parent View (dimmed)          │
+│                                     │
+├─────────────────────────────────────┤
+│  ═══  (Grabber)                     │ ← Drag to resize
+│                                     │
+│        Sheet Content                │
+│                                     │
+│                                     │
+└─────────────────────────────────────┘
+
+Detents:
+├── .medium → Half screen
+├── .large → Full screen (with safe area)
+├── Custom → Specific height
+```
+
+---
+
+## 8. SF Symbols
+
+### Usage Guidelines
+
+```
+SF Symbols: Apple's icon library (5000+ icons)
+
+Weights: Match text weight
+├── Ultralight / Thin / Light
+├── Regular / Medium / Semibold
+├── Bold / Heavy / Black
+
+Scales:
+├── .small → Inline with small text
+├── .medium → Standard UI
+├── .large → Emphasis, standalone
+```
+
+### Symbol Configurations
+
+```swift
+// SwiftUI
+Image(systemName: "star.fill")
+    .font(.title2)
+    .foregroundStyle(.yellow)
+
+// With rendering mode
+Image(systemName: "heart.fill")
+    .symbolRenderingMode(.multicolor)
+
+// Animated (iOS 17+)
+Image(systemName: "checkmark.circle")
+    .symbolEffect(.bounce)
+```
+
+### Symbol Best Practices
+
+| Guideline | Implementation |
+|-----------|----------------|
+| Match text weight | Symbol weight = font weight |
+| Use standard symbols | Users recognize them |
+| Multicolor when meaningful | Not just decoration |
+| Fallback for older iOS | Check availability |
+
+---
+
+## 9. iOS Accessibility
+
+### VoiceOver Requirements
+
+```
+Every interactive element needs:
+├── Accessibility label (what it is)
+├── Accessibility hint (what it does) - optional
+├── Accessibility traits (button, link, etc.)
+└── Accessibility value (current state)
+
+SwiftUI:
+.accessibilityLabel("Play")
+.accessibilityHint("Plays the selected track")
+
+React Native:
+accessibilityLabel="Play"
+accessibilityHint="Plays the selected track"
+accessibilityRole="button"
+```
+
+### Dynamic Type Scaling
+
+```
+MANDATORY: Support Dynamic Type
+
+Users can set text size from:
+├── xSmall → 14pt body
+├── Small → 15pt body
+├── Medium → 16pt body
+├── Large (Default) → 17pt body
+├── xLarge → 19pt body
+├── xxLarge → 21pt body
+├── xxxLarge → 23pt body
+├── Accessibility sizes → up to 53pt
+
+Your app MUST scale gracefully at all sizes.
+```
+
+### Reduce Motion
+
+```
+Respect motion preferences:
+
+@Environment(\.accessibilityReduceMotion) var reduceMotion
+
+if reduceMotion {
+    // Use instant transitions
+} else {
+    // Use animations
+}
+
+React Native:
+import { AccessibilityInfo } from 'react-native';
+AccessibilityInfo.isReduceMotionEnabled()
+```
+
+---
+
+## 10. iOS Checklist
+
+### Before Every iOS Screen
+
+- [ ] Using SF Pro or SF Symbols
+- [ ] Dynamic Type supported
+- [ ] Safe areas respected
+- [ ] Navigation follows HIG (back gesture works)
+- [ ] Tab bar items ≤ 5
+- [ ] Touch targets ≥ 44pt
+
+### Before iOS Release
+
+- [ ] Dark mode tested
+- [ ] All text sizes tested (Accessibility Inspector)
+- [ ] VoiceOver tested
+- [ ] Edge swipe back works everywhere
+- [ ] Keyboard avoidance implemented
+- [ ] Notch/Dynamic Island handled
+- [ ] Home indicator area respected
+- [ ] Native components used where possible
+
+---
+
+> **Remember:** iOS users have strong expectations from other iOS apps. Deviating from HIG patterns feels "broken" to them. When in doubt, use the native component.