ios-swift-skill 1.0.0

package/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: ios-swift-skill
+description: iOS Swift and SwiftUI product-engineering guidance for HIG-aligned mobile design systems, view specs, and maintainable code. Use when designing or implementing iPhone/iPad screens, creating Apple HIG component inventories, applying semantic color, Dynamic Type, Liquid Glass/materials, motion, accessibility, SwiftUI Observation, structured concurrency, dependency injection, testing, or reviewing Swift code quality.
+---
+
+# iOS Swift Skill
+
+## Overview
+
+Use this skill to design and implement iOS app surfaces that feel native, accessible, and maintainable. Start with Apple Human Interface Guidelines component names and native SwiftUI/UIKit behavior, then add app-specific composites only when they clarify product behavior.
+
+## Workflow
+
+1. Identify the task mode:
+   - For mobile UI design, view specs, HIG inventories, design-system tokens, layout, motion, typography, accessibility, or Liquid Glass/material decisions, read `references/mobile-design-system.md`.
+   - For Swift, SwiftUI, architecture, state, concurrency, dependencies, tests, or code-review work, read `references/swiftui-clean-code.md`.
+   - For a feature that includes both UI and implementation, read both references before editing or generating code.
+2. Prefer native platform primitives first: `NavigationStack`, `List`, `Button`, `Label`, `LabeledContent`, `ToolbarItem`, `TabView`, `Sheet`, `Menu`, `Picker`, `Toggle`, `ProgressView`, semantic colors, Dynamic Type, and system materials.
+3. Keep app-specific naming at the composite layer. Use HIG names for components and descriptive product-agnostic names for combinations, such as "profile card", "activity row", "onboarding prompt", or "upgrade sheet".
+4. Treat loading, empty, error, modal, and permission states as part of the closest primary view unless the product flow needs a distinct route.
+5. Verify accessibility and maintainability before finishing: Dynamic Type, VoiceOver labels, Reduce Motion, Increase Contrast, dark mode, actor isolation, dependency injection, deterministic tests, and explicit state modeling.
+
+## View Spec Shape
+
+When creating or revising an iOS view spec, include these sections when relevant:
+
+- `Labels and Copy`
+- `HIG Component Inventory`
+- `Layout and Position`
+- `Color and Typography`
+- `Functionality`
+- `States`
+- `Data Dependencies`
+
+In `HIG Component Inventory`, name Apple HIG components first, then explain how the app composes them. Avoid inventing custom component names for native controls.
+
+## Implementation Defaults
+
+- Keep SwiftUI views declarative. Put side effects in explicit actions, `.task(id:)`, observable models, clients, repositories, or actors.
+- Use `@Observable` models with `@State` for new SwiftUI screen state unless existing code requires `ObservableObject`.
+- Model mutually exclusive screen states with an enum instead of boolean combinations.
+- Inject networking, persistence, clocks, UUID generation, feature flags, analytics, and notification scheduling.
+- Make async work cancellable and actor isolation explicit. Use `@MainActor` for UI models unless isolation is deliberately elsewhere.
+- Use the design system for semantic color, typography, spacing, motion, materials, and HIG component naming. Do not hard-code one-off fonts, colors, or corner radii when a token or native component applies.
+
+## Review Checklist
+
+- Does the UI use native HIG components and semantic system behavior before custom composition?
+- Does the view body read as layout rather than business logic?
+- Are state transitions explicit, testable, and accessible?
+- Are colors, fonts, spacing, materials, and motion aligned with the design system reference?
+- Are Dynamic Type, VoiceOver, Reduce Motion, Increase Contrast, dark mode, loading, empty, and error states covered?
+- Are async tasks cancellable, dependencies injected, and cross-task values safely `Sendable` or actor-isolated?
+- Are tests deterministic and focused on user-visible or domain behavior?
+
+## References
+
+- `references/mobile-design-system.md`: iOS design-system tokens, HIG component taxonomy, motion map, layout zones, and view-spec guidance.
+- `references/swiftui-clean-code.md`: SwiftUI architecture, Observation state, reusable UI, concurrency, dependencies, naming, accessibility, localization, testing, and review guidance.

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "iOS Swift Skill"
+  short_description: "iOS design and Swift code guidance"
+  default_prompt: "Use $ios-swift-skill to design and implement an iOS SwiftUI feature with HIG-aligned UI and maintainable code."

package/bin/install.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const packageRoot = path.resolve(__dirname, "..");
+const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+const destination = path.join(codexHome, "skills", "ios-swift-skill");
+const force = process.argv.includes("--force");
+const help = process.argv.includes("--help") || process.argv.includes("-h");
+
+if (help) {
+  console.log(`Install the iOS Swift skill for Codex.
+
+Usage:
+  npx ios-swift-skill [--force]
+
+Options:
+  --force  Replace an existing installation
+  -h, --help  Show this help`);
+  process.exit(0);
+}
+
+if (fs.existsSync(destination)) {
+  if (!force) {
+    console.error(`Already installed at ${destination}`);
+    console.error("Run again with --force to replace it.");
+    process.exit(1);
+  }
+  fs.rmSync(destination, { recursive: true, force: true });
+}
+
+fs.mkdirSync(destination, { recursive: true });
+
+for (const entry of ["SKILL.md", "agents", "references"]) {
+  fs.cpSync(path.join(packageRoot, entry), path.join(destination, entry), {
+    recursive: true,
+  });
+}
+
+console.log(`Installed ios-swift-skill to ${destination}`);
+console.log("Restart Codex to load the skill.");

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "ios-swift-skill",
+  "version": "1.0.0",
+  "description": "Install an iOS Swift and SwiftUI engineering skill for Codex",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DongkuKim/ios-swift-skill.git"
+  },
+  "homepage": "https://github.com/DongkuKim/ios-swift-skill#readme",
+  "bugs": "https://github.com/DongkuKim/ios-swift-skill/issues",
+  "bin": {
+    "ios-swift-skill": "bin/install.js"
+  },
+  "files": [
+    "SKILL.md",
+    "agents",
+    "references",
+    "bin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "codex",
+    "skill",
+    "ios",
+    "swift",
+    "swiftui"
+  ]
+}

package/references/mobile-design-system.md

@@ -0,0 +1,235 @@
+# iOS Mobile Design System Reference
+
+Use this reference for iOS-first mobile design systems, HIG component inventories, SwiftUI/UIKit view specs, and design review. Keep product-specific names out of the system layer; describe products through native components and app-level composites.
+
+## Platform Baseline
+
+| Token | Value |
+| --- | --- |
+| Device baseline | iPhone, 390 x 844 pt |
+| Safe areas | Top 47 pt, bottom 34 pt on the baseline device |
+| Grid | 8 pt spacing system |
+| Horizontal margin | 20 pt standard, 16 pt for dense lists |
+| Corner radius | 8 pt for cards and sheets unless a card-style object requires 16 pt |
+| Touch target | 44 x 44 pt minimum |
+| Top chrome | Use `Toolbars` for top actions |
+| Bottom chrome | Use `Tab bars` for primary app navigation |
+| Material system | Implement Liquid Glass through standard system components on supported Apple platform releases |
+| Motion system | Prefer standard system component motion, with Reduce Motion fallbacks for every custom motion |
+
+## Color Tokens
+
+Apple HIG color guidance favors semantic, adaptive colors over hard-coded values. Use system colors for platform-native surfaces, foreground content, controls, and status. Brand and premium moments should come from hierarchy, material, motion, iconography, interaction priority, and carefully scoped accent usage rather than broad custom color systems.
+
+| Token | Apple basis | Usage |
+| --- | --- | --- |
+| `color.backgroundPrimary` | `systemBackground` | Primary app canvas outside grouped list views |
+| `color.backgroundGrouped` | `systemGroupedBackground` | List-heavy and grouped backgrounds |
+| `color.surfacePrimary` | `secondarySystemBackground` | Elevated boxes, field containers, and rows on primary backgrounds |
+| `color.surfaceGrouped` | `secondarySystemGroupedBackground` | Elevated boxes, field containers, and rows on grouped backgrounds |
+| `color.surfaceTertiary` | `tertiarySystemBackground` or `tertiarySystemGroupedBackground` | Nested elements inside secondary surfaces |
+| `color.textPrimary` | `label` | Primary labels, titles, prompts, and body copy |
+| `color.textSecondary` | `secondaryLabel` | Metadata, helper labels, subtitles, and timestamps |
+| `color.textTertiary` | `tertiaryLabel` | De-emphasized counters, quiet placeholders, and supplemental footnotes |
+| `color.placeholder` | `placeholderText` | Empty text-field and text-view placeholder content |
+| `color.separator` | `separator` | Hairlines, list dividers, and subtle card borders |
+| `color.opaqueSeparator` | `opaqueSeparator` | Borders that must not show underlying content |
+| `color.link` | `link` | Text links, secondary actions, and tappable inline copy |
+| `color.tint` | System tint or app accent | Filled primary buttons, selected controls, progress fills, badges, and active gauges |
+| `color.textOnTint` | Prominent control foreground | Text and symbols on filled tinted controls |
+| `color.success` | `systemGreen` | Completed and unlocked states |
+| `color.warning` | `systemOrange` | Urgent but recoverable notices |
+| `color.danger` | `systemRed` | Destructive, failed, blocked, or irreversible states |
+| `color.machineReadableInk` | Fixed high-contrast utility color | QR codes, barcodes, and other marks placed on light scannable surfaces |
+| `color.machineReadableSurface` | Fixed high-contrast utility color | Background wells for machine-readable marks |
+| `color.overlay` | Presentation dimming color | Dim backgrounds behind sheets and alerts when system presentation does not provide one |
+
+### Color Usage Rules
+
+- Do not hard-code system color hex values in implementation; use SwiftUI `Color` or UIKit `UIColor` semantic APIs.
+- Do not redefine semantic color meanings: labels are for text, separators are for dividers, links are for interactive text, and backgrounds are for hierarchy.
+- Do not rely on color alone for status, interactivity, limits, or selection. Pair color with labels, icons, glyph shape, copy, or layout.
+- Test core views in light mode, dark mode, increased contrast, True Tone, and bright outdoor conditions.
+- Reserve tinted control backgrounds for primary actions and status emphasis.
+- Maintain machine-readable contrast for QR and barcode zones. Do not adapt machine-readable marks to dark-mode foreground colors.
+
+## Liquid Glass and Materials
+
+Use Liquid Glass as a system-provided material layer for controls and navigation, not as a decorative page background. Content remains the focus; materials create hierarchy for functional chrome such as bars, controls, sheets, popovers, and high-priority actions.
+
+| Token | Apple basis | Usage |
+| --- | --- | --- |
+| `material.systemGlass` | Standard SwiftUI/UIKit Liquid Glass adoption | Default for toolbars, tab bars, sheets, popovers, standard buttons, segmented controls, sliders, toggles, and native controls |
+| `material.scrollEdgeGlass` | System scroll-edge effect | Navigation and action chrome above scrolling content |
+| `material.contentSurface` | Semantic system background colors | Primary reading surfaces, profile content, rows, and long-form text |
+| `material.customGlass` | SwiftUI `glassEffect`, UIKit `UIGlassEffect` | Rare custom functional controls that must float above content |
+| `material.accessibleFallback` | Reduced transparency, reduced motion, and user-selected material appearance | Fallback to semantic surfaces, standard spacing, and static transitions |
+
+### Material Rules
+
+- Build with the latest SDKs and use standard SwiftUI/UIKit components first so Liquid Glass, control sizing, focus behavior, and platform animation updates are inherited automatically.
+- Remove custom backgrounds from toolbars, tab bars, split views, sheets, popovers, and standard controls unless a product constraint requires them.
+- Do not layer multiple glass controls on top of each other. Keep spacing generous enough that material elements do not crowd, overlap, or fight for focus.
+- Use custom glass effects sparingly and only for functional elements. Do not apply glass to repeated cards, rows, or long reading areas by default.
+- Let scroll containers use the system scroll-edge effect wherever chrome floats above content.
+- Keep machine-readable marks on fixed high-contrast surfaces; never apply translucency to the mark itself.
+
+## Motion Tokens
+
+Apple HIG motion guidance favors purposeful, brief, realistic motion that provides feedback, preserves orientation, and supports continuity without distracting from content. Use standard system component motion first, then add custom motion only when it clarifies a state change, transition, or direct manipulation.
+
+| Token | Apple basis | Applied to | Reduce Motion fallback |
+| --- | --- | --- | --- |
+| `motion.systemDefault` | Standard component motion | Native buttons, toolbars, tab bars, sheets, controls, menus, keyboard, and scroll behavior | Let the system reduce, replace, or remove motion |
+| `motion.pressFeedback` | Brief feedback tied to touch | Primary and secondary buttons, list row taps, selected cards, and explicit actions | Instant highlight plus state label or symbol change |
+| `motion.selectionChange` | Realistic state transition | Segmented controls, pickers, page controls, selected tokens, and filters | Instant selected state with color, label, or checkmark |
+| `motion.presentation` | Context-preserving presentation | Sheets, popovers, alerts, action sheets, menus, context menus, and activity views | Crossfade or instant presentation from the same source context |
+| `motion.navigation` | Orientation-preserving screen transition | Push/pop navigation, tab changes, detail opens, and verification flows | Crossfade while preserving title, back action, and focus order |
+| `motion.scrollContinuity` | System scroll physics and scroll-edge effects | Scroll views, long lists, list chrome, sticky actions, and material bars over content | Standard scrolling with reduced effects and static chrome |
+| `motion.disclosure` | Content expansion and collapse | Disclosure controls and expandable details | Instant expand/collapse while preserving layout order |
+| `motion.listUpdate` | Insert, remove, reorder, and refresh feedback | Lists, tables, collections, unread rows, and activity rows | Non-animated row state change, optional brief fade |
+| `motion.contentReveal` | Lightweight reveal for newly available content | Results, loaded images, generated content, preview cards, and unlocked states | Static content appears with clear status copy |
+| `motion.progress` | Ongoing work or completion feedback | Progress indicators, gauges, readiness, import/export, and background work | Static progress value, percentage, or status label |
+| `motion.statusUpdate` | Attention to important state changes | Notifications, Live Activities, unread badges, warnings, success states, and capacity changes | Static detail state with label and system symbol |
+| `motion.none` | No independent motion | Machine-readable marks, core reading text, dense metadata, and passive rows | No fallback needed |
+
+### Motion Rules
+
+- Use standard SwiftUI/UIKit component motion wherever possible; system components adapt to input methods and accessibility settings.
+- Add motion only when it communicates feedback, continuity, orientation, or state.
+- Keep custom motion brief and precise. Frequent interactions like row taps, tab changes, or option selection should not make people wait.
+- Make motion optional; never use motion as the only cue for success, failure, limits, availability, or unread state.
+- Match motion to user intent and spatial origin. A view that opens from a row should return to that row.
+- Let people interrupt or cancel motion. Do not block navigation, typing, scanning, or contact actions until a nonessential animation finishes.
+- Avoid decorative parallax, looping motion, large background movement, or motion at screen edges.
+- Use animated SF Symbols only for short, meaningful status changes such as success, warning, loading, or unlock confirmation.
+- Keep QR codes, barcodes, and scannable zones static.
+
+## Typography Tokens
+
+Apple HIG typography guidance favors system fonts, built-in text styles, Dynamic Type, and clear hierarchy over fixed custom type scales. Treat the values below as iOS Large reference values, not fixed implementation sizes.
+
+| Token | Apple text style | iOS Large size / leading | Default weight | Emphasized weight | Usage |
+| --- | --- | --- | --- | --- | --- |
+| `type.largeTitle` | Large Title | 34 / 41 pt | Regular | Bold | Welcome and major reveal titles |
+| `type.title1` | Title 1 | 28 / 34 pt | Regular | Bold | Primary screen titles |
+| `type.title2` | Title 2 | 22 / 28 pt | Regular | Bold | Section titles, sheet titles, and large card titles |
+| `type.title3` | Title 3 | 20 / 25 pt | Regular | Semibold | Secondary screen headings and compact modal headings |
+| `type.headline` | Headline | 17 / 22 pt | Semibold | Semibold | Row titles, button labels, and strong labels |
+| `type.body` | Body | 17 / 22 pt | Regular | Semibold | Main copy, prompts, explanations, and multiline text |
+| `type.callout` | Callout | 16 / 21 pt | Regular | Semibold | Secondary explanations and supporting copy |
+| `type.subheadline` | Subhead | 15 / 20 pt | Regular | Semibold | Metadata, row subtitles, and compact secondary labels |
+| `type.footnote` | Footnote | 13 / 18 pt | Regular | Semibold | Constraints, helper text, timestamps, and legal-adjacent notes |
+| `type.caption` | Caption 1 | 12 / 16 pt | Regular | Semibold | Chips, badges, counters, and short status labels |
+| `type.caption2` | Caption 2 | 11 / 13 pt | Regular | Semibold | Lowest-priority metadata only; avoid for essential content |
+
+| Token | Value | Usage |
+| --- | --- | --- |
+| `text.defaultReadableSize.ios` | 17 pt | iOS default readable body size; use `type.body` for ordinary reading |
+| `text.minimumSize.ios` | 11 pt | Absolute iOS minimum for nonessential labels; prefer larger text when space allows |
+| `text.dynamicType.standardRange` | xSmall through xxxLarge | Required support range for normal Dynamic Type |
+| `text.dynamicType.accessibilityRange` | AX1 through AX5 | Required support range for Larger Accessibility Text Sizes |
+| `text.truncationPolicy` | Minimize truncation | Use multiline labels, wrapping, scrolling, or detail views before truncating useful text |
+| `text.iconScaling` | Match text style | SF Symbols and meaningful glyphs scale with adjacent Dynamic Type text |
+
+### Typography Rules
+
+- Use built-in Dynamic Type text styles through SwiftUI `Font` or UIKit preferred font APIs; do not implement these values as fixed sizes.
+- Use SF Pro through system APIs for interface text. Do not embed Apple system font files in the app.
+- Prefer Regular, Medium, Semibold, and Bold. Avoid Ultralight, Thin, and Light weights, especially below `type.body`.
+- Preserve visual hierarchy when Dynamic Type increases: primary content scales first, while lower-priority metadata can wrap, move, or collapse.
+- Keep truncation rare. If useful text does not fit, prefer wrapping, scrolling, or a detail view over ellipsizing.
+- Scale meaningful SF Symbols with adjacent text styles so icons remain readable at larger accessibility sizes.
+
+## Apple HIG Component Taxonomy
+
+Use these exact names in component inventory tables.
+
+| Category | Component names |
+| --- | --- |
+| Content | Charts, Image views, Text views, Web views |
+| Layout and organization | Boxes, Collections, Column views, Disclosure controls, Labels, Lists and tables, Lockups, Outline views, Split views, Tab views |
+| Menus and actions | Activity views, Buttons, Context menus, Dock menus, Edit menus, Home Screen quick actions, Menus, Ornaments, Pop-up buttons, Pull-down buttons, The menu bar, Toolbars |
+| Navigation and search | Path controls, Search fields, Sidebars, Tab bars, Token fields |
+| Presentation | Action sheets, Alerts, Page controls, Panels, Popovers, Scroll views, Sheets, Windows |
+| Selection and input | Color wells, Combo boxes, Digit entry views, Image wells, Pickers, Segmented controls, Sliders, Steppers, Text fields, Toggles, Virtual keyboards |
+| Status | Gauges, Progress indicators, Rating indicators |
+| System experiences | App Shortcuts, Complications, Controls, Live Activities, Notifications, Snippets, Status bars, Top Shelf, Watch faces, Widgets |
+
+## Component Motion Map
+
+Every view-level `HIG Component Inventory` inherits from this table. When a component appears in a view doc, apply the matching motion token unless the view state explicitly says otherwise.
+
+| Apple HIG component | Motion applied | Guidance |
+| --- | --- | --- |
+| Status bars | `motion.systemDefault` | Use system status behavior only; no custom motion |
+| Toolbars | `motion.systemDefault`, `motion.scrollContinuity` | Let material and scroll-edge behavior adapt automatically above scrolling content |
+| Tab bars | `motion.systemDefault`, `motion.selectionChange` | Use native tab selection motion; avoid custom tab icon bounces |
+| Buttons | `motion.pressFeedback` | Brief press response for primary, secondary, contact, and card actions |
+| Pull-down buttons, Pop-up buttons | `motion.pressFeedback`, `motion.presentation` | Button press opens anchored system menu or popover |
+| Menus, Context menus | `motion.presentation` | Reveal from the invoking control or row; preserve source context |
+| Action sheets, Activity views | `motion.presentation` | Present from the current task context; fallback to static system presentation |
+| Sheets, Popovers | `motion.presentation` | Use native presentation and dismissal; avoid custom full-screen motion for scoped tasks |
+| Alerts | `motion.presentation` | Use system alert presentation only for destructive, failure, or irreversible states |
+| Scroll views | `motion.scrollContinuity` | Preserve native scroll physics and scroll-edge effects |
+| Lists and tables | `motion.listUpdate`, `motion.pressFeedback` | Animate inserts/removals only when helpful; avoid decorative row staggering |
+| Collections | `motion.listUpdate`, `motion.selectionChange` | Animate selected cards/options and catalog updates lightly |
+| Disclosure controls | `motion.disclosure` | Expand/collapse content in place; keep source row visible |
+| Tab views, Page controls | `motion.selectionChange`, `motion.navigation` | Use horizontal continuity for user-driven page movement |
+| Search fields | `motion.systemDefault` | Use native focus, keyboard, and cancel-button behavior |
+| Text fields, Token fields, Combo boxes | `motion.systemDefault`, `motion.selectionChange` | Use native keyboard/focus motion; token insert/delete gets brief selection motion |
+| Virtual keyboards | `motion.systemDefault` | Never customize keyboard entrance or dismissal |
+| Segmented controls | `motion.selectionChange` | Use native selected-segment movement and Reduce Motion behavior |
+| Pickers | `motion.selectionChange` | Use native picker motion; selected values update immediately |
+| Sliders, Steppers, Toggles | `motion.systemDefault`, `motion.pressFeedback` | Direct manipulation follows the gesture; no delayed or decorative response |
+| Gauges, Progress indicators | `motion.progress` | Animate progress only while work is active; always show textual state nearby |
+| Notifications, Live Activities | `motion.statusUpdate` | Use system delivery/update motion; detail screens show static state after open |
+| Image views | `motion.contentReveal` | Fade or system-load media previews; keep QR/barcode image views static with `motion.none` |
+| Text views, Labels | `motion.none` | Text updates should be readable first; use static layout changes unless status changes require attention |
+| Web views | `motion.systemDefault` | Use system web loading/navigation behavior only |
+| Boxes, Lockups | `motion.contentReveal` | Use only for newly revealed cards or result groups; repeated rows stay quiet |
+
+## Composite Naming
+
+Use HIG names for base components and product-agnostic names for app composites.
+
+| Composite pattern | HIG composition | Default motion |
+| --- | --- | --- |
+| Feature card | Boxes + Text views + Buttons | `motion.contentReveal` for new content, `motion.pressFeedback` for actions, `motion.none` for passive reading |
+| List hub | Tab bars or segmented controls + Lists and tables + Search fields | `motion.selectionChange` for tabs/segments, `motion.listUpdate` for row changes, `motion.systemDefault` for search |
+| Prompt flow | Text views + Buttons, or Sheets when modal | `motion.contentReveal` for the next prompt, `motion.pressFeedback` for answers, `motion.presentation` when modal |
+| Machine-readable card | Image views + Labels + Buttons | `motion.none` for the mark, `motion.contentReveal` for readiness, `motion.pressFeedback` for actions |
+| Person or item row | Lists and tables + Image views + Labels + Buttons | `motion.pressFeedback` on open, `motion.listUpdate` on unread/read or state changes |
+| Detail header | Toolbars + Labels + Buttons | `motion.systemDefault` toolbar motion, `motion.statusUpdate` for important changes |
+| Limit or upgrade wall | Sheets + Text views + Buttons + Lists and tables | `motion.presentation` for sheet, `motion.progress` for capacity gauge, `motion.pressFeedback` for actions |
+
+## Shared Screen Zones
+
+| Zone | Position on 390 x 844 baseline | Default components |
+| --- | --- | --- |
+| Status area | y 0-47 | Status bars |
+| Top bar | y 47-103 | Toolbars, Labels, Buttons |
+| Content | y 103-742 | Scroll views, Lists and tables, Boxes, Text views |
+| Persistent action | y 742-776 | Buttons, Segmented controls, Progress indicators |
+| Bottom navigation | y 776-844 | Tab bars |
+
+## View Spec Template
+
+Use this structure for reusable iOS view specs:
+
+1. `Labels and Copy`: toolbar title, primary/secondary buttons, empty/error copy, and user-visible strings.
+2. `HIG Component Inventory`: table with Apple HIG component name and app usage.
+3. `Layout and Position`: safe areas, scroll regions, persistent actions, and navigation chrome.
+4. `Color and Typography`: semantic color tokens and Dynamic Type styles.
+5. `Functionality`: user actions, navigation, deep links, and side effects.
+6. `States`: loading, empty, error, disabled, permission, offline, success, modal, and destructive states.
+7. `Data Dependencies`: local state, remote data, persisted preferences, permissions, and route parameters.
+
+## Shared Behavior
+
+- Use native sheets for focused scoped tasks that do not need a full route.
+- Use alerts only for destructive, failure, or irreversible confirmation states.
+- Use progress indicators for onboarding, import/export, matching, generation, and other ongoing work; never leave algorithmic operations visually silent.
+- Use notifications and Live Activities for latent or time-sensitive updates.
+- Prefer lists and tables for repeatable people, items, history, settings, and activity rows.
+- Keep native messaging, payments, wallet, sharing, and notification flows inside platform-provided surfaces whenever available.

package/references/swiftui-clean-code.md

@@ -0,0 +1,311 @@
+# SwiftUI Clean Code and Maintainability Reference
+
+Use this reference when implementing, reviewing, or refactoring Swift and SwiftUI app code. It favors current Swift, SwiftUI Observation, structured concurrency, testable boundaries, and reusable UI primitives.
+
+Source references to consult when precision matters:
+
+- Swift API Design Guidelines: https://www.swift.org/documentation/api-design-guidelines/
+- Swift Concurrency: https://docs.swift.org/swift-book/documentation/the-swift-programming-language/concurrency/
+- Observation in SwiftUI: https://developer.apple.com/videos/play/wwdc2023/10149/
+- Swift Testing: https://developer.apple.com/xcode/swift-testing/
+
+## Baseline Rules
+
+- Prefer clarity at the call site over clever compactness.
+- Use SwiftUI and Swift native features before adding custom architecture.
+- Keep views declarative: views describe UI, route user intent, and observe state.
+- Keep side effects outside `body`; use explicit actions, `.task(id:)`, services, repositories, actors, or model methods.
+- Use Swift 6 concurrency checking for new modules when possible; make cross-task dependencies `Sendable`.
+- Prefer `struct` value models for domain data and `@Observable` reference models for view-owned mutable UI state.
+- Avoid force unwraps, implicitly unwrapped optionals, global mutable state, hidden singletons, and magic numbers.
+- Keep access control tight: default to `private`, `fileprivate`, or `internal` before making APIs public.
+
+## Architecture
+
+Use a small, boring feature structure:
+
+```text
+Feature/
+  FeatureView.swift
+  FeatureModel.swift
+  FeatureClient.swift
+  FeatureTypes.swift
+  FeatureTests.swift
+```
+
+Recommended boundaries:
+
+| Layer | Responsibility | Avoid |
+| --- | --- | --- |
+| View | Layout, accessibility, transitions, forwarding actions | Business rules, networking, parsing, date math |
+| Observable model | Screen state, user intents, task orchestration | Direct URLSession code, persistence details |
+| Client or repository | I/O boundary and integration mapping | View-specific labels or layout decisions |
+| Domain types | Stable values and rules | Framework-specific UI state |
+
+Create protocols at boundaries that need mocking, replacement, or concurrency isolation. Do not create a protocol for every concrete type by default.
+
+```swift
+protocol ProfileClient: Sendable {
+    func profile() async throws -> Profile
+}
+```
+
+## SwiftUI State
+
+Use the modern Observation model for new SwiftUI code.
+
+| Need | Preferred tool |
+| --- | --- |
+| View-owned local value | `@State` |
+| View-owned observable model | `@State` with `@Observable` model |
+| Parent-owned editable value | `@Binding` |
+| Bindings into an observable model | `@Bindable` |
+| App-wide dependency or model | `@Environment` |
+| Legacy ObservableObject interoperability | `@StateObject`, `@ObservedObject`, `@EnvironmentObject` only where migration requires it |
+
+```swift
+import Observation
+import SwiftUI
+
+@MainActor
+@Observable
+final class ProfileModel {
+    private let client: ProfileClient
+    private(set) var state: Loadable<Profile> = .idle
+
+    init(client: ProfileClient) {
+        self.client = client
+    }
+
+    func load() async {
+        state = .loading
+        do {
+            state = .loaded(try await client.profile())
+        } catch is CancellationError {
+            state = .idle
+        } catch {
+            state = .failed(DisplayError(error))
+        }
+    }
+}
+
+struct ProfileView: View {
+    @State private var model: ProfileModel
+
+    init(client: ProfileClient) {
+        _model = State(initialValue: ProfileModel(client: client))
+    }
+
+    var body: some View {
+        content
+            .task { await model.load() }
+    }
+
+    @ViewBuilder
+    private var content: some View {
+        switch model.state {
+        case .idle, .loading:
+            ProgressView()
+        case .loaded(let profile):
+            ProfileContent(profile: profile)
+        case .empty:
+            EmptyState()
+        case .failed(let error):
+            ErrorState(error: error, retry: { Task { await model.load() } })
+        }
+    }
+}
+```
+
+## View Composition
+
+- Extract a subview when a block has a separate responsibility, needs its own preview, has local state, is reused, or makes the parent hard to scan.
+- Use private computed `some View` properties for small local pieces that do not need separate identity or testing.
+- Prefer `@ViewBuilder` and generics over `AnyView`; use `AnyView` only at true type-erasure boundaries.
+- Keep list identity stable. Never create `UUID()` inside `body` for `ForEach` identity.
+- Keep layout values named when they encode a product decision.
+- Prefer semantic `Label`, `LabeledContent`, `Button`, `List`, `NavigationStack`, `ToolbarItem`, and native controls before custom compositions.
+
+```swift
+private enum Layout {
+    static let avatarSize: CGFloat = 48
+    static let rowSpacing: CGFloat = 12
+}
+```
+
+## Reusable UI
+
+Choose the lightest reusable primitive that solves the duplication:
+
+| Reuse need | Tool |
+| --- | --- |
+| Repeated control behavior | `ButtonStyle`, `ToggleStyle`, `LabelStyle` |
+| Repeated view decoration | `ViewModifier` |
+| Repeated layout algorithm | Custom `Layout` |
+| Repeated content pattern | Generic `View` with typed inputs |
+| Repeated product state | Domain enum or value object |
+
+Use `mobile-design-system.md` for typography, color, motion, materials, and component naming. Do not hard-code custom colors, fixed fonts, or one-off corner radii when a system token or native component applies.
+
+```swift
+struct PrimaryActionButtonStyle: ButtonStyle {
+    func makeBody(configuration: Configuration) -> some View {
+        configuration.label
+            .font(.headline)
+            .frame(maxWidth: .infinity)
+            .padding(.vertical, 14)
+            .background(.tint, in: RoundedRectangle(cornerRadius: 8))
+            .foregroundStyle(.white)
+            .opacity(configuration.isPressed ? 0.8 : 1)
+    }
+}
+```
+
+## Concurrency
+
+- Mark UI models `@MainActor` unless they are deliberately isolated elsewhere.
+- Use `async`/`await`, `async let`, and task groups for structured asynchronous work.
+- Avoid `Task.detached` unless isolation from the current actor is intentional and documented.
+- Do not block async code with semaphores, sleeps, synchronous waits, or sync-over-async adapters.
+- Check cancellation in long-running work and avoid starting new child tasks after cancellation.
+- Keep CPU-heavy work off the main actor, then return to the main actor for UI state updates.
+- Use actors for shared mutable state that can be touched from multiple tasks.
+- Make services, closures, and data crossing concurrency boundaries `Sendable` where practical.
+
+```swift
+actor ProfileCache {
+    private var profiles: [Profile.ID: Profile] = [:]
+
+    func profile(id: Profile.ID) -> Profile? {
+        profiles[id]
+    }
+
+    func store(_ profile: Profile) {
+        profiles[profile.id] = profile
+    }
+}
+```
+
+## Loading, Errors, and Empty States
+
+Model screen state explicitly. Avoid boolean soup like `isLoading`, `hasError`, `isEmpty`, and `didFinish` when those states are mutually exclusive.
+
+```swift
+enum Loadable<Value> {
+    case idle
+    case loading
+    case loaded(Value)
+    case empty
+    case failed(DisplayError)
+}
+```
+
+Error guidance:
+
+- Convert low-level errors into user-safe `DisplayError` values near the UI boundary.
+- Preserve the underlying error for logging, diagnostics, or retry policy.
+- Always provide a recovery action when the user can do something.
+- Treat cancellation as a normal control-flow outcome, not a user-facing failure.
+
+## Dependencies
+
+- Inject time, UUID generation, networking, persistence, feature flags, analytics, and notification scheduling.
+- Prefer small dependency values or closures for simple capabilities.
+- Prefer protocols for cross-module boundaries, external clients, and services with multiple implementations.
+- Keep dependencies out of SwiftUI previews by providing sample clients and static fixtures.
+
+```swift
+struct AppClock: Sendable {
+    var now: @Sendable () -> Date
+
+    static let live = AppClock(now: Date.init)
+}
+```
+
+## Naming and API Design
+
+- Follow Swift API Design Guidelines: names should make use sites clear.
+- Use nouns for types and values, verbs for side-effecting actions, and assertion-like names for booleans.
+- Name protocols by role or capability, such as `ProfileClient`, `ImageLoading`, or `ProgressReporting`.
+- Avoid abbreviations unless they are standard in the domain.
+- Document non-obvious public APIs and computed properties that are not O(1).
+
+```swift
+// Good
+func removeContact(id: Contact.ID)
+var hasUnreadUpdates: Bool
+
+// Avoid
+func process(_ value: String)
+var flag: Bool
+```
+
+## Accessibility and Localization
+
+- Support Dynamic Type, including larger accessibility sizes.
+- Do not use color as the only signal for state, selection, errors, or limits.
+- Add accessibility labels and values when visible text is insufficient.
+- Keep tappable targets at least 44 x 44 pt.
+- Localize user-facing strings and use `FormatStyle` for dates, numbers, currencies, and lists.
+- Test important screens with VoiceOver, Reduce Motion, Increase Contrast, dark mode, and long localized strings.
+
+```swift
+Text(event.lastUpdatedAt, format: .dateTime.month().day().hour().minute())
+    .font(.subheadline)
+    .foregroundStyle(.secondary)
+```
+
+## Testing
+
+Use Swift Testing for new unit and integration-style tests. Keep XCTest where it already exists, for UI tests, or when a framework still requires it.
+
+Test priority:
+
+1. Domain value behavior and business rules.
+2. Observable model state transitions.
+3. Service mapping, retry, cancellation, and error conversion.
+4. Accessibility labels and critical UI states through previews or UI tests.
+
+```swift
+import Testing
+
+@MainActor
+@Test("Profile load stores loaded state")
+func profileLoadStoresLoadedState() async throws {
+    let client = StubProfileClient(result: .success(.sample))
+    let model = ProfileModel(client: client)
+
+    await model.load()
+
+    #expect(model.state == .loaded(.sample))
+}
+```
+
+Testing rules:
+
+- Make tests deterministic by injecting clocks, IDs, clients, and fixtures.
+- Test cancellation and failure paths, not only success paths.
+- Keep preview data realistic and privacy-safe.
+- Prefer one clear behavior per test.
+- Use parameterized tests for repeated rules.
+
+## File and Module Organization
+
+- Keep one primary type per file unless helper types are private and tiny.
+- Put protocol conformances in focused extensions.
+- Keep generated code, preview fixtures, and test helpers separate from app code.
+- Avoid giant shared utility files. Utilities should have a narrow domain and clear owner.
+- Keep feature modules independent of UI where possible; UI should depend on domain and clients, not the reverse.
+- Use SwiftFormat or SwiftLint only when rules reinforce readability and team consistency.
+
+## Review Checklist
+
+- Does the view body read as layout rather than business logic?
+- Are state transitions modeled with explicit types?
+- Are dependencies injected and testable?
+- Are async tasks cancellable and actor isolation clear?
+- Are cross-task values safely `Sendable` or isolated?
+- Are names clear at the call site?
+- Are colors, fonts, spacing, and motion aligned with the design system?
+- Are accessibility, localization, loading, empty, and error states covered?
+- Are tests deterministic and focused on behavior?