swiftui

Files (60)

• SKILL.md
• accessibility.md · references/
• animation-advanced.md · references/
• animation-basics.md · references/
• animation-transitions.md · references/
• api.md · references/
• app-wiring.md · references/components/
• async-state.md · references/components/
• components-index.md · references/components/
• controls.md · references/components/
• deeplinks.md · references/components/
• focus.md · references/components/
• form.md · references/components/
• grids.md · references/components/
• haptics.md · references/components/
• input-toolbar.md · references/components/
• lightweight-clients.md · references/components/
• list.md · references/components/
• loading-placeholders.md · references/components/
• macos-settings.md · references/components/
• matched-transitions.md · references/components/
• media.md · references/components/
• menu-bar.md · references/components/
• navigationstack.md · references/components/
• overlay.md · references/components/
• previews.md · references/components/
• scroll-reveal.md · references/components/
• scrollview.md · references/components/
• searchable.md · references/components/
• sheets.md · references/components/
• split-views.md · references/components/
• tabview.md · references/components/
• theming.md · references/components/
• title-menus.md · references/components/
• top-bar.md · references/components/
• data.md · references/
• design-principles.md · references/
• design.md · references/
• focus-patterns.md · references/
• hygiene.md · references/
• image-optimization.md · references/
• layout-best-practices.md · references/
• liquid-glass.md · references/
• list-patterns.md · references/
• localization.md · references/
• macos-scenes.md · references/
• macos-views.md · references/
• macos-window-styling.md · references/
• modern-apis.md · references/
• mv-patterns.md · references/
• navigation.md · references/
• performance-patterns.md · references/
• performance.md · references/
• scroll-patterns.md · references/
• sheet-navigation-patterns.md · references/
• state-management.md · references/
• swift.md · references/
• text-formatting.md · references/
• view-structure.md · references/
• views.md · references/

SKILL.md (first lines)

Write and review SwiftUI code for correctness, modern API usage, state-flow correctness, performance, accessibility, and adherence to Apple's Human Interface Guidelines. Report only genuine problems — do not nitpick or invent issues.


## Review process

1. Check for deprecated API using [references/api.md](references/api.md) and [references/modern-apis.md](references/modern-apis.md).
2. Check that views, modifiers, and animations have been written optimally using [references/views.md](references/views.md), [references/view-structure.md](references/view-structure.md), [references/animation-basics.md](references/animation-basics.md), [references/animation-transitions.md](references/animation-transitions.md), and [references/animation-advanced.md](references/animation-advanced.md).
3. Validate state management and data flow using [references/data.md](references/data.md) and [references/state-management.md](references/state-management.md).
4. Ensure navigation is updated and performant using [references/navigation.md](references/navigation.md) and [references/sheet-navigation-patterns.md](references/sheet-navigation-patterns.md).
5. Validate list behavior using [references/list-patterns.md](references/list-patterns.md).
6. Validate scroll behavior using [references/scroll-patterns.md](references/scroll-patterns.md).
7. Validate text formatting using [references/text-formatting.md](references/text-formatting.md).
8. Validate image handling using [references/image-optimization.md](references/image-optimization.md).
9. Ensure the code uses designs that are accessible and compliant with Apple's Human Interface Guidelines using [references/design.md](references/design.md) and [references/design-principles.md](references/design-principles.md).
10. Validate accessibility compliance (Dynamic Type, VoiceOver, Reduce Motion) using [references/accessibility.md](references/accessibility.md).
11. Ensure the code runs efficiently using [references/performance.md](references/performance.md) and [references/performance-patterns.md](references/performance-patterns.md).
12. Check layout best practices using [references/layout-best-practices.md](references/layout-best-practices.md).
13. For view-file refactoring (ordering, extracting sections, MV pattern), use [references/mv-patterns.md](references/mv-patterns.md).
14. If adopting Liquid Glass (iOS 26+), use [references/liquid-glass.md](references/liquid-glass.md).
15. For component-specific patterns (TabView, NavigationStack, sheets, forms, grids, menus, split views, theming, etc.), use the files under `references/components/`. Start with [references/components/components-index.md](references/components/components-index.md).
16. For macOS apps, validate scenes, window/toolbar styling, and macOS-specific views/AppKit interop using [references/macos-scenes.md](references/macos-scenes.md), [references/macos-window-styling.md](references/macos-window-styling.md), and [references/macos-views.md](references/macos-views.md).
17. Validate localization of user-facing text using [references/localization.md](references/localization.md). Ducko's SwiftUI views live in the `DuckoUI` library target. SwiftPM compiles each target's String Catalog into that target's own bundle, the `DuckoApp` executable's included (`Ducko_DuckoApp.bundle`). Once localization exists, every user-facing string in every target must pin the bundle (`Text("…", bundle: #bundle)` / `String(localized:bundle:)`), because the bare overloads silently miss the catalog.
18. Validate focus handling (`@FocusState`, `@FocusedValue` command wiring, focusable interactions, focus scope) using [references/focus-patterns.md](references/focus-patterns.md).
19. Quick validation of Swift code using [references/swift.md](references/swift.md).
20. Final code hygiene check using [references/hygiene.md](references/hygiene.md).

If doing a partial review, load only the relevant reference files.


## Core Instructions

- iOS 27 and macOS 27 exist, and Xcode 27 is available. Do not dismiss their APIs as speculative.
- Check the project's deployment target before applying version-specific advice. Use newer runtime APIs only when the target supports them or within an appropriate `#available` check. Keep the existing target unchanged. Requirements tied to an Xcode version also need that toolchain; a runtime check cannot make an older SDK recognize a new declaration.
- Ducko targets macOS 26 and builds with Xcode 27. A macOS 26.1 or macOS 27 API therefore needs a matching `#available` branch that keeps the existing behavior on macOS 26.0 (and `@available` on any helper declaration that names such a type), while a rule tied to Xcode 27 alone (`@State` as a macro, `@ContentBuilder`) applies as it stands.
- Target Swift 6.2 or later, using modern Swift concurrency.
- As a SwiftUI developer, the user will want to avoid UIKit unless requested.
- Do not introduce third-party frameworks without asking first.
- Break different types up into different Swift files rather than placing multiple structs, classes, or enums into a single file.
- Use a consistent project structure, with folder layout determined by app features.


## Quick start (new SwiftUI view)

1. Define the view's state and its ownership location (`@State`, `@Binding`, `@Environment`, injected `@Observable`, etc.).
2. Identify dependencies to inject via `@Environment`.
3. Sketch the view hierarchy and extract repeated parts into subviews early.
4. Implement async loading with `.task` and explicit loading/error states.
5. Add accessibility labels or identifiers when the UI is interactive.
6. Validate with a build and update callsites if needed.


## View file structure (refactor/review guidance)

When laying out or reviewing a SwiftUI view file, prefer this top-to-bottom order:

1. `@Environment`
2. `private` / `public` `let`
3. `@State` / other stored properties
4. computed `var` (non-view)
5. `init`
6. `body`
7. computed view builders / other view helpers
8. helper / async functions

### Prefer Model-View (MV) patterns by default

- Views are lightweight state expressions; models/services own business logic.
- Favor `@State`, `@Environment`, `@Query`, `.task`, and `.onChange` for orchestration.
- Inject services and shared models via `@Environment`; keep views small and composable.
- Split large views into subviews rather than introducing a view model.
- If a view model already exists, make it non-optional when possible and initialize it in the view's `init`. Avoid `bootstrapIfNeeded` patterns.

See [references/mv-patterns.md](references/mv-patterns.md) for the rationale.

### Keep a stable view tree

Avoid returning completely different root branches from `body` or a computed view via `if/else`. Prefer a single stable base view and place conditions inside sections/modifiers (`overlay`, `opacity`, `disabled`, `toolbar`, row content). Top-level branch swapping causes identity churn and broader invalidation.

```swift
// Prefer
var body: some View {
    List { documentsListContent }
        .toolbar { if canEdit { editToolbar } }
}

// Avoid
var documentsListView: some View {
    if canEdit { editableDocumentsList } else { readOnlyDocumentsList }
}
```

### Split large bodies (>~300 lines)

When a SwiftUI view file grows past ~300 lines, split it using `private` extensions grouped with `// MARK: - Actions`, `// MARK: - Subviews`, `// MARK: - Helpers`, etc. Keep the main `struct` focused on stored properties, `init`, and `body`.


## State management

- **Always prefer `@Observable` over `ObservableObject`** for new code.
- **Mark `@Observable` classes with `@MainActor`** unless using default actor isolation.
- **Always mark `@State` and `@StateObject` as `private`.** With Xcode 27, a non-private `@State` runs its initial expression again whenever the parent reconstructs the view.
- **Initialize each `@State` property in exactly one place**: at the declaration or in `init()`, never both.
- **Never declare passed values as `@State` or `@StateObject`** — they only accept initial values.
- Use `@State` with `@Observable` classes (not `@StateObject`).
- `@Binding` only when a child needs to **modify** parent state.
- `@Bindable` for injected `@Observable` objects that need bindings.
- Use `let` for read-only values; `var` + `.onChange()` for reactive reads.
- Legacy: `@StateObject` for owned `ObservableObject`; `@ObservedObject` for injected.
- Nested `ObservableObject` doesn't observe properly — pass nested objects directly; `@Observable` handles nesting fine.

### Property wrapper selection (modern)

| Wrapper | Use when |
|---------|----------|
| `@State` | Internal view state (must be `private`), or owned `@Observable` class |
| `@Binding` | Child modifies parent's state |
| `@Bindable` | Injected `@Observable` needing bindings |
| `let` | Read-only value from parent |
| `var` | Read-only value watched via `.onChange()` |

From ducko-im/ducko, MIT.

More from ducko-im/ducko