# 29. iOS App — Design System Components Matching Web Theme

meta:
  id: shieldai-unified-restructure-29
  feature: shieldai-unified-restructure
  priority: P1
  depends_on: [shieldai-unified-restructure-28]
  tags: [ios, swiftui, design-system, components, mobile]

objective:
- Build a comprehensive set of reusable SwiftUI components that mirror the web app's UI primitives (Button, Card, Input, Badge, Modal, Toast) using the iOS theme system from task 28. These components should feel native to iOS while maintaining visual consistency with the web app.

deliverables:
- `iOS/ShieldAI/Components/ShieldButton.swift` — Button component:
  - Styles: primary (filled), secondary (outlined), ghost (text only), danger
  - Sizes: small, medium, large
  - States: enabled, disabled, loading (shows `ProgressView`)
  - Supports icons (leading/trailing)
- `iOS/ShieldAI/Components/ShieldCard.swift` — Card container:
  - Gradient background matching web `.gradient-card`
  - Border with corner radius
  - Optional header and footer content
  - Tap gesture support
- `iOS/ShieldAI/Components/ShieldTextField.swift` — Text input:
  - Label, placeholder, validation state
  - Secure text entry toggle for passwords
  - Error message display
  - Focus state styling
- `iOS/ShieldAI/Components/ShieldBadge.swift` — Status badge:
  - Variants: default, success, warning, error, info
  - Small rounded pill shape
  - Icon + text or text only
- `iOS/ShieldAI/Components/ShieldModal.swift` — Modal/sheet presentation:
  - `.sheet` wrapper with consistent styling
  - Title, content, and action buttons
  - Dismiss gesture support
- `iOS/ShieldAI/Components/ShieldToast.swift` — Toast notification:
  - Slide-in from top or bottom
  - Auto-dismiss after 3-4 seconds
  - Variants: success, error, warning, info
  - Tap to dismiss
  - Uses `overlay` modifier on root view
- `iOS/ShieldAI/Components/ShieldAvatar.swift` — User avatar:
  - Displays image or initials fallback
  - Sizes: small, medium, large
  - Online/away status indicator dot
- `iOS/ShieldAI/Components/ShieldProgressBar.swift` — Progress indicator:
  - Linear progress bar with percentage label
  - Color variants
- `iOS/ShieldAI/Components/ShieldEmptyState.swift` — Empty state view:
  - Icon, title, description, action button
- `iOS/ShieldAI/Components/ShieldSkeleton.swift` — Skeleton loading:
  - Shimmer animation using `LinearGradient` mask
  - Text line and rectangle shapes

steps:
1. Create `iOS/ShieldAI/Components/` directory.
2. **ShieldButton**:
   - Use `Button` with custom label
   - Primary: `brandPrimary` background, white text
   - Secondary: transparent with `brandPrimary` border and text
   - Ghost: transparent, `brandPrimary` text
   - Danger: red gradient background
   - Loading: replace label with `ProgressView` + reduce opacity
   - Use `.frame(maxWidth: .infinity)` for full-width buttons
3. **ShieldCard**:
   - `ZStack` with gradient background shape
   - `.overlay` for border
   - `VStack` for content with padding
   - Corner radius: 16pt (matching web `rounded-2xl`)
4. **ShieldTextField**:
   - `VStack` with label + `TextField`/`SecureField` + error text
   - Custom background using `bgSecondary` with border
   - Focus ring using `.overlay` with `brandPrimary` stroke on focus
   - Eye icon button for password visibility toggle
5. **ShieldBadge**:
   - `Text` inside `Capsule()` background
   - Colors from semantic tokens
   - Small padding and font size
6. **ShieldModal**:
   - View extension `.shieldModal(isPresented:content:)`
   - Wraps `.sheet` with consistent header and button bar
   - Uses `ShieldCard` styling for sheet background
7. **ShieldToast**:
   - Create `ToastManager` as `@Observable` class (iOS 17+) or `ObservableObject`
   - `showToast(message, variant, duration)` method
   - Root view applies `.overlay` with `ToastContainer`
   - `ToastContainer` animates toast in/out with `withAnimation`
8. **ShieldAvatar**:
   - `AsyncImage` or `Image` with circular clip
   - Fallback: `Text` with initials on `brandPrimary` circle
   - Status dot overlay
9. **ShieldProgressBar**:
   - `GeometryReader` with filled `Rectangle`
   - Percentage label overlay
10. **ShieldEmptyState**:
    - `VStack` with icon (`Image(systemName:)`), title, description, optional `ShieldButton`
11. **ShieldSkeleton**:
    - `Rectangle` or `RoundedRectangle` with shimmer animation
    - Use `LinearGradient` masked with `mask` modifier
    - Animate gradient position with `withAnimation(.linear(duration: 1.5).repeatForever())`
12. Create a preview/test view showing all components in light and dark mode.

steps:
- Unit: Each component renders correctly in previews
- Unit: ShieldButton action fires on tap
- Unit: ShieldTextField validation shows error state
- Unit: ShieldToast auto-dismisses after specified duration
- Visual: All components match web app appearance in both color schemes
- Visual: Components adapt to Dynamic Type (accessibility font sizes)

acceptance_criteria:
- [ ] All 10 component types exist in `iOS/ShieldAI/Components/`
- [ ] Each component supports light and dark modes
- [ ] Button supports all 4 styles, 3 sizes, and loading state
- [ ] TextField supports validation, secure entry, and focus styling
- [ ] Toast system can queue and auto-dismiss multiple toasts
- [ ] Card uses gradient background matching web theme
- [ ] Skeleton has smooth shimmer animation
- [ ] All components use theme tokens (no hardcoded colors)
- [ ] Components adapt to accessibility font sizes

validation:
- Open preview canvas for each component and verify appearance
- Run app on simulator and navigate to component test screen
- Toggle dark mode and verify all components shift colors
- Enable large text in Accessibility settings and verify layouts don't break
- Run unit tests via Xcode Cmd+U

notes:
- SwiftUI previews are invaluable for component development. Create a `ComponentsPreview.swift` that shows all variants side by side.
- Use `@ViewBuilder` closures for content slots in `ShieldCard`, `ShieldModal`, etc. to allow flexible content.
- For the toast system, consider using the new `@Observable` macro (iOS 17+) instead of `ObservableObject` for better performance.
- The shimmer animation can be implemented using a `LinearGradient` that moves across the view. Reference: https://swiftuirecipes.com/blog/swiftui-shimmer-effect
- Keep components generic — they should not import service-specific types or business logic.
