ac-framework 1.9.3 → 1.9.4

package/framework/mobile_development/.codex/skills/mobile-design/platform-ios.md

@@ -0,0 +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.