Update documentation to clarify SwiftUI transition usage

- Add Important note to KingfisherOptionsInfoItem.transition indicating it's for UIKit/AppKit
- Enhance loadTransition documentation to emphasize it's the recommended approach for SwiftUI
- Update CommonTasks.md with separate examples for UIKit and SwiftUI transitions
- Add cross-references between UIKit transition option and SwiftUI loadTransition method
- Clarify that loadTransition provides better SwiftUI integration and access to native transitions

Sources/Documentation.docc/CommonTasks/CommonTasks.md

@@ -91,10 +91,21 @@ This shows a `UIActivityIndicatorView` in center of image view while downloading
 
 ### Fading in Downloaded Image
 
+For UIKit/AppKit:
 ```swift
 imageView.kf.setImage(with: url, options: [.transition(.fade(0.2))])
 ```
 
+For SwiftUI (recommended):
+```swift
+KFImage(url)
+    .fade(duration: 0.2)
+    // Or use native SwiftUI transitions:
+    .loadTransition(.opacity, animation: .easeInOut(duration: 0.2))
+```
+
+> Note: In SwiftUI applications, use `loadTransition` for native SwiftUI transitions instead of the options-based `transition`. This provides better integration with the SwiftUI animation system.
+
 ### Completion Handler
 
 ```swift

Sources/General/KingfisherOptionsInfo.swift

@@ -72,6 +72,9 @@ public enum KingfisherOptionsInfoItem: Sendable {
     /// By default, the transition does not occur when the image is retrieved from either memory or disk cache. To
     /// force the transition even when the image is retrieved from the cache, also set
     /// ``KingfisherOptionsInfoItem/forceTransition``.
+    ///
+    /// - Important: This option is designed for UIKit/AppKit transitions. For SwiftUI applications, use the
+    /// ``KFImageProtocol/loadTransition(_:animation:)`` method instead, which provides native SwiftUI transition support.
     case transition(ImageTransition)
     
     /// The associated `Float` value to be set as the priority of the image download task.

Sources/SwiftUI/KFImageOptions.swift

@@ -215,7 +215,11 @@ extension KFImageProtocol {
     ///   - animation: The animation to use with the transition. Defaults to `.default`.
     /// - Returns: A Kingfisher-compatible image view with the applied transition.
     ///
-    /// This method allows you to use native SwiftUI transitions like `.slide`, `.scale`, `.opacity`, etc.
+    /// This is the recommended way to apply transitions in SwiftUI applications. Unlike the UIKit-based
+    /// ``KingfisherOptionsInfoItem/transition(_:)`` option, this method uses native SwiftUI transitions,
+    /// providing better integration with the SwiftUI animation system and access to all SwiftUI transition types.
+    ///
+    /// Available transitions include `.slide`, `.scale`, `.opacity`, `.move`, `.offset`, and custom transitions.
     /// The transition will be applied when the image is loaded from the network, following the same
     /// rules as the fade transition regarding cache behavior and `forceTransition`.
     /// 
@@ -226,6 +230,8 @@ extension KFImageProtocol {
     /// KFImage(url)
     ///     .loadTransition(.slide, animation: .easeInOut(duration: 0.5))
     /// ```
+    ///
+    /// - Note: For UIKit/AppKit applications, use ``KingfisherOptionsInfoItem/transition(_:)`` instead.
     public func loadTransition(_ transition: AnyTransition, animation: Animation? = .default) -> Self {
         context.swiftUITransition = transition
         context.swiftUIAnimation = animation
@@ -240,7 +246,8 @@ extension KFImageProtocol {
     /// - Returns: A Kingfisher-compatible image view with the applied transition.
     ///
     /// This method provides access to newer SwiftUI transitions available in iOS 17.0+,
-    /// such as `BlurReplaceTransition` and other transitions conforming to the `Transition` protocol.
+    /// such as `BlurReplaceTransition`, `PushTransition`, and other transitions conforming to the `Transition` protocol.
+    /// This is the recommended approach for SwiftUI applications on iOS 17.0+.
     /// 
     /// When both `loadTransition` and `fade` are set, `loadTransition` takes precedence.
     ///
@@ -249,6 +256,8 @@ extension KFImageProtocol {
     /// KFImage(url)
     ///     .loadTransition(.blurReplace(.downUp), animation: .bouncy)
     /// ```
+    ///
+    /// - Note: For UIKit/AppKit applications, use ``KingfisherOptionsInfoItem/transition(_:)`` instead.
     @available(iOS 17.0, macOS 14.0, tvOS 17.0, watchOS 10.0, *)
     public func loadTransition<T: Transition>(_ transition: T, animation: Animation? = .default) -> Self {
         context.swiftUITransition = AnyTransition(transition)