buildanything 1.7.1 → 1.8.0

package/skills/ios/swiftui-pro/references/swift.md

@@ -0,0 +1,56 @@
+# Swift
+
+- Prefer Swift-native string methods over Foundation equivalents: use `replacing("a", with: "b")` not `replacingOccurrences(of: "a", with: "b")`.
+- Prefer modern Foundation API: `URL.documentsDirectory` instead of `FileManager` directory lookups, `appending(path:)` to append strings to a URL.
+- Never use C-style number formatting like `String(format: "%.2f", value)`. Use `Text(value, format: .number.precision(.fractionLength(2)))` or similar `FormatStyle` APIs.
+- Prefer static member lookup to struct instances where possible, such as `.circle` rather than `Circle()`, and `.borderedProminent` rather than `BorderedProminentButtonStyle()`.
+- Avoid force unwraps (`!`) and force `try` unless the failure is truly unrecoverable, and even then prefer using `fatalError()` with a clear description. If possible, use `if let`, `guard let`, nil-coalescing, or `try?`/`do-catch`.
+- Filtering text based on user-input must be done using `localizedStandardContains()` as opposed to `contains()` or `localizedCaseInsensitiveContains()`.
+- Strongly prefer `Double` over `CGFloat`, except when using optionals or `inout`; Swift is able to bridge the two freely except in those two cases.
+- If you want to count array objects that match a predicate, always use `count(where:)` rather than `filter()` followed by `count`.
+- Prefer `Date.now` over `Date()` for clarity.
+- When `import SwiftUI` is already in a file, you do not need to add `import UIKit` or `import AppKit` to access things like `UIImage` or `NSImage` – they are imported automatically on the appropriate platform.
+- When dealing with the names of people, strongly prefer to use `PersonNameComponents` with modern formatting over simple string interpolation such as `Text("\(firstName) \(lastName)")`.
+- If a given type of data is repeatedly sorted using an identical closure, e.g. `books.sorted { $0.author < $1.author }`, prefer to make the type in question conform to `Comparable` so the sort order is centralized.
+- Prefer to avoid manual date formatting strings if possible. If manual date formatting *is* used for user display, at least make sure to use “y” rather than “yyyy” for years, so the year value is correct in all localizations. If the purpose is data exchange with an API, this rule does not apply.
+- When trying to convert a string to a date, prefer the modern `Date` initializer API such as `Date(myString, strategy: .iso8601)`.
+- Flag instances where errors triggered by a user action are swallowed silently, e.g. using `print(error.localizedDescription)` rather than showing an alert or similar.
+- Prefer `if let value {` shorthand over `if let value = value {`.
+- Omit return for single expression functions. `if` and `switch` can be used as expressions when returning values and assigning to variables.
+
+For example, this kind of code:
+
+```swift
+var tileColor: Color {
+    if isCorrect {
+        return .green
+    } else {
+        return .red
+    }
+}
+```
+
+Should be written like this:
+
+```swift
+var tileColor: Color {
+    if isCorrect {
+        .green
+    } else {
+        .red
+    }
+}
+```
+
+
+## Swift Concurrency
+
+- If an API offers both modern `async`/`await` equivalents and older closure-based variants, always prefer the `async`/`await` versions.
+- Never use Grand Central Dispatch (`DispatchQueue.main.async()`, `DispatchQueue.global()`, etc.). Always use modern Swift concurrency (`async`/`await`, actors, `Task`).
+- Never use `Task.sleep(nanoseconds:)`; use `Task.sleep(for:)` instead.
+- Flag any mutable shared state that isn't protected by an actor or `@MainActor`, unless the project is configured to use MainActor default actor isolation.
+- Assume strict concurrency rules are being applied; flag `@Sendable` violations and data races.
+- When evaluating `MainActor.run()`, check whether the project has its default actor isolation set to Main Actor first, because `MainActor.run()` might not be needed.
+- `Task.detached()` is often a bad idea. Check any usage extremely carefully.
+
+For more help with Swift concurrency, suggest the [Swift Concurrency Pro agent skill](https://github.com/twostraws/swift-concurrency-agent-skill).

package/skills/ios/swiftui-pro/references/views.md

@@ -0,0 +1,35 @@
+# SwiftUI Views
+
+- Strongly prefer to avoid breaking up view bodies using computed properties or methods that return `some View`, even if `@ViewBuilder` is used. Extract them into separate `View` structs instead, placing each into its own file.
+- Flag `body` properties that are excessively long; they should be broken into extracted subviews.
+- Button actions should be extracted from view bodies into separate methods, to avoid mixing layout and logic.
+- Similarly, general business logic should not live inline in `task()`, `onAppear()` or elsewhere in `body`.
+- Prefer to place view logic into view models or similar, so it can be tested. For more help with testing, suggest the [Swift Testing Pro agent skill](https://github.com/twostraws/swift-testing-agent-skill).
+- Each type (struct, class, enum) should be in its own Swift file. Flag files containing multiple type definitions.
+- Unless a full-screen editing experience is required, prefer using `TextField` with `axis: .vertical` to using `TextEditor`, because it allows placeholder text. If a specific minimum height is required for `TextField`, use something like `lineLimit(5...)`.
+- If a button action can be provided directly as an `action` parameter, do so. For example: `Button("Label", systemImage: "plus", action: myAction)` is preferred over `Button("Label", systemImage: "plus") { action() }`.
+- When rendering SwiftUI views to images, strongly prefer `ImageRenderer` over `UIGraphicsImageRenderer`.
+- `#Preview` should be used for previews, not the legacy `PreviewProvider` protocol.
+- When using `TabView(selection:)`, use a binding to a property that stores an enum rather than an integer or string. For example, `Tab("Home", systemImage: "house", value: .home)` is better than `Tab("Home", systemImage: "house", value: 0)`.
+- Strongly prefer to avoid breaking up view bodies using computed properties or methods that return `some View`, even if `@ViewBuilder` is used. Extract them into separate `View` structs instead, placing each into its own file. (Yes, this is repeated, but it’s so important it needs to be mentioned twice.)
+
+
+## Animating views
+
+- Strongly prefer to use the `@Animatable` macro over creating `animatableData` manually – the macro automatically adds conformance to the `Animatable` protocol and creates the correct `animatableData` property. If some properties should not or cannot be animated (e.g. Booleans, integers, etc), mark them `@AnimatableIgnored`.
+- Never use `animation(_ animation: Animation?)`; always provide a value to watch, such as `.animation(.bouncy, value: score)`.
+- Chaining animations must be done using a `completion` closure passed to `withAnimation()`, rather than trying to execute multiple `withAnimation()` calls using delays.
+
+For example:
+
+```swift
+Button("Animate Me") {
+    withAnimation {
+        scale = 2
+    } completion: {
+        withAnimation {
+            scale = 1
+        }
+    }
+}
+```

package/skills/ios/swiftui-ui-patterns/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Ricouard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/ios/swiftui-ui-patterns/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: swiftui-ui-patterns
+description: Fires ONLY on these specific composition tasks — creating a new TabView, composing a NavigationStack hierarchy, authoring a Sheet presentation (enum-driven sheets, `.sheet(item:)`), implementing scroll-reveal gestures, or authoring custom ViewModifiers. Does NOT overlap swiftui-pro — swiftui-pro handles general SwiftUI review and write operations; this skill is scoped only to the composition tasks listed above. Do not load on general SwiftUI writes.
+---
+
+# SwiftUI UI Patterns
+
+## Quick start
+
+Choose a track based on your goal:
+
+### Existing project
+
+- Identify the feature or screen and the primary interaction model (list, detail, editor, settings, tabbed).
+- Find a nearby example in the repo with `rg "TabView\("` or similar, then read the closest SwiftUI view.
+- Apply local conventions: prefer SwiftUI-native state, keep state local when possible, and use environment injection for shared dependencies.
+- Choose the relevant component reference from `references/components-index.md` and follow its guidance.
+- If the interaction reveals secondary content by dragging or scrolling the primary content away, read `references/scroll-reveal.md` before implementing gestures manually.
+- Build the view with small, focused subviews and SwiftUI-native data flow.
+
+### New project scaffolding
+
+- Start with `references/app-wiring.md` to wire TabView + NavigationStack + sheets.
+- Add a minimal `AppTab` and `RouterPath` based on the provided skeletons.
+- Choose the next component reference based on the UI you need first (TabView, NavigationStack, Sheets).
+- Expand the route and sheet enums as new screens are added.
+
+## General rules to follow
+
+- Use modern SwiftUI state (`@State`, `@Binding`, `@Observable`, `@Environment`) and avoid unnecessary view models.
+- If the deployment target includes iOS 16 or earlier and cannot use the Observation API introduced in iOS 17, fall back to `ObservableObject` with `@StateObject` for root ownership, `@ObservedObject` for injected observation, and `@EnvironmentObject` only for truly shared app-level state.
+- Prefer composition; keep views small and focused.
+- Use async/await with `.task` and explicit loading/error states. For restart, cancellation, and debouncing guidance, read `references/async-state.md`.
+- Keep shared app services in `@Environment`, but prefer explicit initializer injection for feature-local dependencies and models. For root wiring patterns, read `references/app-wiring.md`.
+- Prefer the newest SwiftUI API that fits the deployment target and call out the minimum OS whenever a pattern depends on it.
+- Maintain existing legacy patterns only when editing legacy files.
+- Follow the project's formatter and style guide.
+- **Sheets**: Prefer `.sheet(item:)` over `.sheet(isPresented:)` when state represents a selected model. Avoid `if let` inside a sheet body. Sheets should own their actions and call `dismiss()` internally instead of forwarding `onCancel`/`onConfirm` closures.
+- **Scroll-driven reveals**: Prefer deriving a normalized progress value from scroll offset and driving the visual state from that single source of truth. Avoid parallel gesture state machines unless scroll alone cannot express the interaction.
+
+## State ownership summary
+
+Use the narrowest state tool that matches the ownership model:
+
+| Scenario | Preferred pattern |
+| --- | --- |
+| Local UI state owned by one view | `@State` |
+| Child mutates parent-owned value state | `@Binding` |
+| Root-owned reference model on iOS 17+ | `@State` with an `@Observable` type |
+| Child reads or mutates an injected `@Observable` model on iOS 17+ | Pass it explicitly as a stored property |
+| Shared app service or configuration | `@Environment(Type.self)` |
+| Legacy reference model on iOS 16 and earlier | `@StateObject` at the root, `@ObservedObject` when injected |
+
+Choose the ownership location first, then pick the wrapper. Do not introduce a reference model when plain value state is enough.
+
+## Cross-cutting references
+
+- `references/navigationstack.md`: navigation ownership, per-tab history, and enum routing.
+- `references/sheets.md`: centralized modal presentation and enum-driven sheets.
+- `references/deeplinks.md`: URL handling and routing external links into app destinations.
+- `references/app-wiring.md`: root dependency graph, environment usage, and app shell wiring.
+- `references/async-state.md`: `.task`, `.task(id:)`, cancellation, debouncing, and async UI state.
+- `references/previews.md`: `#Preview`, fixtures, mock environments, and isolated preview setup.
+- `references/performance.md`: stable identity, observation scope, lazy containers, and render-cost guardrails.
+
+## Anti-patterns
+
+- Giant views that mix layout, business logic, networking, routing, and formatting in one file.
+- Multiple boolean flags for mutually exclusive sheets, alerts, or navigation destinations.
+- Live service calls directly inside `body`-driven code paths instead of view lifecycle hooks or injected models/services.
+- Reaching for `AnyView` to work around type mismatches that should be solved with better composition.
+- Defaulting every shared dependency to `@EnvironmentObject` or a global router without a clear ownership reason.
+
+## Workflow for a new SwiftUI view
+
+1. Define the view's state, ownership location, and minimum OS assumptions before writing UI code.
+2. Identify which dependencies belong in `@Environment` and which should stay as explicit initializer inputs.
+3. Sketch the view hierarchy, routing model, and presentation points; extract repeated parts into subviews. For complex navigation, read `references/navigationstack.md`, `references/sheets.md`, or `references/deeplinks.md`. **Build and verify no compiler errors before proceeding.**
+4. Implement async loading with `.task` or `.task(id:)`, plus explicit loading and error states when needed. Read `references/async-state.md` when the work depends on changing inputs or cancellation.
+5. Add previews for the primary and secondary states, then add accessibility labels or identifiers when the UI is interactive. Read `references/previews.md` when the view needs fixtures or injected mock dependencies.
+6. Validate with a build: confirm no compiler errors, check that previews render without crashing, ensure state changes propagate correctly, and sanity-check that list identity and observation scope will not cause avoidable re-renders. Read `references/performance.md` if the screen is large, scroll-heavy, or frequently updated. For common SwiftUI compilation errors — missing `@State` annotations, ambiguous `ViewBuilder` closures, or mismatched generic types — resolve them before updating callsites. **If the build fails:** read the error message carefully, fix the identified issue, then rebuild before proceeding to the next step. If a preview crashes, isolate the offending subview, confirm its state initialisation is valid, and re-run the preview before continuing.
+
+## Component references
+
+Use `references/components-index.md` as the entry point. Each component reference should include:
+- Intent and best-fit scenarios.
+- Minimal usage pattern with local conventions.
+- Pitfalls and performance notes.
+- Paths to existing examples in the current repo.
+
+## Adding a new component reference
+
+- Create `references/<component>.md`.
+- Keep it short and actionable; link to concrete files in the current repo.
+- Update `references/components-index.md` with the new entry.
+
+
+---
+
+Vendored from: https://github.com/Dimillian/Skills/tree/main/swiftui-ui-patterns

package/skills/ios/swiftui-ui-patterns/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SwiftUI UI Patterns"
+  short_description: "Apply practical SwiftUI UI patterns"
+  default_prompt: "Use $swiftui-ui-patterns to design or refactor this SwiftUI UI with strong default patterns."

package/skills/ios/swiftui-ui-patterns/references/app-wiring.md

@@ -0,0 +1,201 @@
+# App wiring and dependency graph
+
+## Intent
+
+Show how to wire the app shell (TabView + NavigationStack + sheets) and install a global dependency graph (environment objects, services, streaming clients, SwiftData ModelContainer) in one place.
+
+## Recommended structure
+
+1) Root view sets up tabs, per-tab routers, and sheets.
+2) A dedicated view modifier installs global dependencies and lifecycle tasks (auth state, streaming watchers, push tokens, data containers).
+3) Feature views pull only what they need from the environment; feature-specific state stays local.
+
+## Dependency selection
+
+- Use `@Environment` for app-level services, shared clients, theme/configuration, and values that many descendants genuinely need.
+- Prefer initializer injection for feature-local dependencies and models. Do not move a dependency into the environment just to avoid passing one or two arguments.
+- Keep mutable feature state out of the environment unless it is intentionally shared across broad parts of the app.
+- Use `@EnvironmentObject` only as a legacy fallback or when the project already standardizes on it for a truly shared object.
+
+## Root shell example (generic)
+
+```swift
+@MainActor
+struct AppView: View {
+  @State private var selectedTab: AppTab = .home
+  @State private var tabRouter = TabRouter()
+
+  var body: some View {
+    TabView(selection: $selectedTab) {
+      ForEach(AppTab.allCases) { tab in
+        let router = tabRouter.router(for: tab)
+        NavigationStack(path: tabRouter.binding(for: tab)) {
+          tab.makeContentView()
+        }
+        .withSheetDestinations(sheet: Binding(
+          get: { router.presentedSheet },
+          set: { router.presentedSheet = $0 }
+        ))
+        .environment(router)
+        .tabItem { tab.label }
+        .tag(tab)
+      }
+    }
+    .withAppDependencyGraph()
+  }
+}
+```
+
+Minimal `AppTab` example:
+
+```swift
+@MainActor
+enum AppTab: Identifiable, Hashable, CaseIterable {
+  case home, notifications, settings
+  var id: String { String(describing: self) }
+
+  @ViewBuilder
+  func makeContentView() -> some View {
+    switch self {
+    case .home: HomeView()
+    case .notifications: NotificationsView()
+    case .settings: SettingsView()
+    }
+  }
+
+  @ViewBuilder
+  var label: some View {
+    switch self {
+    case .home: Label("Home", systemImage: "house")
+    case .notifications: Label("Notifications", systemImage: "bell")
+    case .settings: Label("Settings", systemImage: "gear")
+    }
+  }
+}
+```
+
+Router skeleton:
+
+```swift
+@MainActor
+@Observable
+final class RouterPath {
+  var path: [Route] = []
+  var presentedSheet: SheetDestination?
+}
+
+enum Route: Hashable {
+  case detail(id: String)
+}
+```
+
+## Dependency graph modifier (generic)
+
+Use a single modifier to install environment objects and handle lifecycle hooks when the active account/client changes. This keeps wiring consistent and avoids forgetting a dependency in call sites.
+
+```swift
+extension View {
+  func withAppDependencyGraph(
+    accountManager: AccountManager = .shared,
+    currentAccount: CurrentAccount = .shared,
+    currentInstance: CurrentInstance = .shared,
+    userPreferences: UserPreferences = .shared,
+    theme: Theme = .shared,
+    watcher: StreamWatcher = .shared,
+    pushNotifications: PushNotificationsService = .shared,
+    intentService: AppIntentService = .shared,
+    quickLook: QuickLook = .shared,
+    toastCenter: ToastCenter = .shared,
+    namespace: Namespace.ID? = nil,
+    isSupporter: Bool = false
+  ) -> some View {
+    environment(accountManager)
+      .environment(accountManager.currentClient)
+      .environment(quickLook)
+      .environment(currentAccount)
+      .environment(currentInstance)
+      .environment(userPreferences)
+      .environment(theme)
+      .environment(watcher)
+      .environment(pushNotifications)
+      .environment(intentService)
+      .environment(toastCenter)
+      .environment(\.isSupporter, isSupporter)
+      .task(id: accountManager.currentClient.id) {
+        let client = accountManager.currentClient
+        if let namespace { quickLook.namespace = namespace }
+        currentAccount.setClient(client: client)
+        currentInstance.setClient(client: client)
+        userPreferences.setClient(client: client)
+        await currentInstance.fetchCurrentInstance()
+        watcher.setClient(client: client, instanceStreamingURL: currentInstance.instance?.streamingURL)
+        if client.isAuth {
+          watcher.watch(streams: [.user, .direct])
+        } else {
+          watcher.stopWatching()
+        }
+      }
+      .task(id: accountManager.pushAccounts.map(\.token)) {
+        pushNotifications.tokens = accountManager.pushAccounts.map(\.token)
+      }
+  }
+}
+```
+
+Notes:
+- The `.task(id:)` hooks respond to account/client changes, re-seeding services and watcher state.
+- Keep the modifier focused on global wiring; feature-specific state stays within features.
+- Adjust types (AccountManager, StreamWatcher, etc.) to match your project.
+
+## SwiftData / ModelContainer
+
+Install your `ModelContainer` at the root so all feature views share the same store. Keep the list minimal to the models that need persistence.
+
+```swift
+extension View {
+  func withModelContainer() -> some View {
+    modelContainer(for: [Draft.self, LocalTimeline.self, TagGroup.self])
+  }
+}
+```
+
+Why: a single container avoids duplicated stores per sheet or tab and keeps data consistent.
+
+## Sheet routing (enum-driven)
+
+Centralize sheets with a small enum and a helper modifier.
+
+```swift
+enum SheetDestination: Identifiable {
+  case composer
+  case settings
+  var id: String { String(describing: self) }
+}
+
+extension View {
+  func withSheetDestinations(sheet: Binding<SheetDestination?>) -> some View {
+    sheet(item: sheet) { destination in
+      switch destination {
+      case .composer:
+        ComposerView().withEnvironments()
+      case .settings:
+        SettingsView().withEnvironments()
+      }
+    }
+  }
+}
+```
+
+Why: enum-driven sheets keep presentation centralized and testable; adding a new sheet means adding one enum case and one switch branch.
+
+## When to use
+
+- Apps with multiple packages/modules that share environment objects and services.
+- Apps that need to react to account/client changes and rewire streaming/push safely.
+- Any app that wants consistent TabView + NavigationStack + sheet wiring without repeating environment setup.
+
+## Caveats
+
+- Keep the dependency modifier slim; do not put feature state or heavy logic there.
+- Ensure `.task(id:)` work is lightweight or cancelled appropriately; long-running work belongs in services.
+- If unauthenticated clients exist, gate streaming/watch calls to avoid reconnect spam.

package/skills/ios/swiftui-ui-patterns/references/async-state.md

@@ -0,0 +1,96 @@
+# Async state and task lifecycle
+
+## Intent
+
+Use this pattern when a view loads data, reacts to changing input, or coordinates async work that should follow the SwiftUI view lifecycle.
+
+## Core rules
+
+- Use `.task` for load-on-appear work that belongs to the view lifecycle.
+- Use `.task(id:)` when async work should restart for a changing input such as a query, selection, or identifier.
+- Treat cancellation as a normal path for view-driven tasks. Check `Task.isCancelled` in longer flows and avoid surfacing cancellation as a user-facing error.
+- Debounce or coalesce user-driven async work such as search before it fans out into repeated requests.
+- Keep UI-facing models and mutations main-actor-safe; do background work in services, then publish the result back to UI state.
+
+## Example: load on appear
+
+```swift
+struct DetailView: View {
+  let id: String
+  @State private var state: LoadState<Item> = .idle
+  @Environment(ItemClient.self) private var client
+
+  var body: some View {
+    content
+      .task {
+        await load()
+      }
+  }
+
+  @ViewBuilder
+  private var content: some View {
+    switch state {
+    case .idle, .loading:
+      ProgressView()
+    case .loaded(let item):
+      ItemContent(item: item)
+    case .failed(let error):
+      ErrorView(error: error)
+    }
+  }
+
+  private func load() async {
+    state = .loading
+    do {
+      state = .loaded(try await client.fetch(id: id))
+    } catch is CancellationError {
+      return
+    } catch {
+      state = .failed(error)
+    }
+  }
+}
+```
+
+## Example: restart on input change
+
+```swift
+struct SearchView: View {
+  @State private var query = ""
+  @State private var results: [ResultItem] = []
+  @Environment(SearchClient.self) private var client
+
+  var body: some View {
+    List(results) { item in
+      Text(item.title)
+    }
+    .searchable(text: $query)
+    .task(id: query) {
+      try? await Task.sleep(for: .milliseconds(250))
+      guard !Task.isCancelled, !query.isEmpty else {
+        results = []
+        return
+      }
+      do {
+        results = try await client.search(query)
+      } catch is CancellationError {
+        return
+      } catch {
+        results = []
+      }
+    }
+  }
+}
+```
+
+## When to move work out of the view
+
+- If the async flow spans multiple screens or must survive view dismissal, move it into a service or model.
+- If the view is mostly coordinating app-level lifecycle or account changes, wire it at the app shell in `app-wiring.md`.
+- If retry, caching, or offline policy becomes complex, keep the policy in the client/service and leave the view with simple state transitions.
+
+## Pitfalls
+
+- Do not start network work directly from `body`.
+- Do not ignore cancellation for searches, typeahead, or rapidly changing selections.
+- Avoid storing derived async state in multiple places when one source of truth is enough.

package/skills/ios/swiftui-ui-patterns/references/components-index.md

@@ -0,0 +1,50 @@
+# Components Index
+
+Use this file to find component and cross-cutting guidance. Each entry lists when to use it.
+
+## Available components
+
+- TabView: `references/tabview.md` — Use when building a tab-based app or any tabbed feature set.
+- NavigationStack: `references/navigationstack.md` — Use when you need push navigation and programmatic routing, especially per-tab history.
+- Sheets and presentation: `references/sheets.md` — Use for local item-driven sheets, centralized modal routing, and sheet-specific action patterns.
+- Form and Settings: `references/form.md` — Use for settings, grouped inputs, and structured data entry.
+- macOS Settings: `references/macos-settings.md` — Use when building a macOS Settings window with SwiftUI's Settings scene.
+- Split views and columns: `references/split-views.md` — Use for iPad/macOS multi-column layouts or custom secondary columns.
+- List and Section: `references/list.md` — Use for feed-style content and settings rows.
+- ScrollView and Lazy stacks: `references/scrollview.md` — Use for custom layouts, horizontal scrollers, or grids.
+- Scroll-reveal detail surfaces: `references/scroll-reveal.md` — Use when a detail screen reveals secondary content or actions as the user scrolls or swipes between full-screen sections.
+- Grids: `references/grids.md` — Use for icon pickers, media galleries, and tiled layouts.
+- Theming and dynamic type: `references/theming.md` — Use for app-wide theme tokens, colors, and type scaling.
+- Controls (toggles, pickers, sliders): `references/controls.md` — Use for settings controls and input selection.
+- Input toolbar (bottom anchored): `references/input-toolbar.md` — Use for chat/composer screens with a sticky input bar.
+- Top bar overlays (iOS 26+ and fallback): `references/top-bar.md` — Use for pinned selectors or pills above scroll content.
+- Overlay and toasts: `references/overlay.md` — Use for transient UI like banners or toasts.
+- Focus handling: `references/focus.md` — Use for chaining fields and keyboard focus management.
+- Searchable: `references/searchable.md` — Use for native search UI with scopes and async results.
+- Async images and media: `references/media.md` — Use for remote media, previews, and media viewers.
+- Haptics: `references/haptics.md` — Use for tactile feedback tied to key actions.
+- Matched transitions: `references/matched-transitions.md` — Use for smooth source-to-destination animations.
+- Deep links and URL routing: `references/deeplinks.md` — Use for in-app navigation from URLs.
+- Title menus: `references/title-menus.md` — Use for filter or context menus in the navigation title.
+- Menu bar commands: `references/menu-bar.md` — Use when adding or customizing macOS/iPadOS menu bar commands.
+- Loading & placeholders: `references/loading-placeholders.md` — Use for redacted skeletons, empty states, and loading UX.
+- Lightweight clients: `references/lightweight-clients.md` — Use for small, closure-based API clients injected into stores.
+
+## Cross-cutting references
+
+- App wiring and dependency graph: `references/app-wiring.md` — Use to wire the app shell, install shared dependencies, and decide what belongs in the environment.
+- Async state and task lifecycle: `references/async-state.md` — Use when a view loads data, reacts to changing input, or needs cancellation/debouncing guidance.
+- Previews: `references/previews.md` — Use when adding `#Preview`, fixtures, mock environments, or isolated preview setup.
+- Performance guardrails: `references/performance.md` — Use when a screen is large, scroll-heavy, frequently updated, or showing signs of avoidable re-renders.
+
+## Planned components (create files as needed)
+
+- Web content: create `references/webview.md` — Use for embedded web content or in-app browsing.
+- Status composer patterns: create `references/composer.md` — Use for composition or editor workflows.
+- Text input and validation: create `references/text-input.md` — Use for forms, validation, and text-heavy input.
+- Design system usage: create `references/design-system.md` — Use when applying shared styling rules.
+
+## Adding entries
+
+- Add the component file and link it here with a short “when to use” description.
+- Keep each component reference short and actionable.

package/skills/ios/swiftui-ui-patterns/references/controls.md

@@ -0,0 +1,57 @@
+# Controls (Toggle, Slider, Picker)
+
+## Intent
+
+Use native controls for settings and configuration screens, keeping labels accessible and state bindings clear.
+
+## Core patterns
+
+- Bind controls directly to `@State`, `@Binding`, or `@AppStorage`.
+- Prefer `Toggle` for boolean preferences.
+- Use `Slider` for numeric ranges and show the current value in a label.
+- Use `Picker` for discrete choices; use `.pickerStyle(.segmented)` only for 2–4 options.
+- Keep labels visible and descriptive; avoid embedding buttons inside controls.
+
+## Example: toggles with sections
+
+```swift
+Form {
+  Section("Notifications") {
+    Toggle("Mentions", isOn: $preferences.notificationsMentionsEnabled)
+    Toggle("Follows", isOn: $preferences.notificationsFollowsEnabled)
+    Toggle("Boosts", isOn: $preferences.notificationsBoostsEnabled)
+  }
+}
+```
+
+## Example: slider with value text
+
+```swift
+Section("Font Size") {
+  Slider(value: $fontSizeScale, in: 0.5...1.5, step: 0.1)
+  Text("Scale: \(String(format: \"%.1f\", fontSizeScale))")
+    .font(.scaledBody)
+}
+```
+
+## Example: picker for enums
+
+```swift
+Picker("Default Visibility", selection: $visibility) {
+  ForEach(Visibility.allCases, id: \.self) { option in
+    Text(option.title).tag(option)
+  }
+}
+```
+
+## Design choices to keep
+
+- Group related controls in a `Form` section.
+- Use `.disabled(...)` to reflect locked or inherited settings.
+- Use `Label` inside toggles to combine icon + text when it adds clarity.
+
+## Pitfalls
+
+- Avoid `.pickerStyle(.segmented)` for large sets; use menu or inline styles instead.
+- Don’t hide labels for sliders; always show context.
+- Avoid hard-coding colors for controls; use theme tint sparingly.