diff --git a/docs/platforms/apple/common/enriching-events/viewhierarchy/index.mdx b/docs/platforms/apple/common/enriching-events/viewhierarchy/index.mdx
index c477ded2b9c36a..ea121b631bc178 100644
--- a/docs/platforms/apple/common/enriching-events/viewhierarchy/index.mdx
+++ b/docs/platforms/apple/common/enriching-events/viewhierarchy/index.mdx
@@ -20,7 +20,15 @@ App hang events will not have view hierarchy because the main thread is blocked
 
 <Alert>
 
-Deobfuscation for view hierarchies is fully supported for native SDKs, and React Native, but is currently not supported for Flutter. View hierarchies are not supported for SwiftUI.
+Deobfuscation for view hierarchies is fully supported for native SDKs and React Native, but is currently not supported for Flutter.
+
+</Alert>
+
+<Alert>
+
+View hierarchy support for SwiftUI is highly limited, due to the SwiftUI rendering engine not backing every view with a UIKit view anymore.
+
+For example, `Text` views may be rendered directly into a graphics render surface rather than creating a corresponding `UILabel`. This is an operating system limitation, not a limitation of the Sentry SDK. As a result, the captured view hierarchy may not fully represent the SwiftUI view tree.
 
 </Alert>
 
diff --git a/docs/platforms/apple/common/session-replay/customredact.mdx b/docs/platforms/apple/common/session-replay/customredact.mdx
index 314ba1422327cf..6b2aff17b187b5 100644
--- a/docs/platforms/apple/common/session-replay/customredact.mdx
+++ b/docs/platforms/apple/common/session-replay/customredact.mdx
@@ -59,6 +59,14 @@ label.sentryReplayUnmask()
 
 ## SwiftUI
 
+<Alert level="info">
+
+Session Replay masking for SwiftUI is best-effort. The SDK relies on view hierarchy information provided by the operating system, which is limited for SwiftUI. The SwiftUI rendering engine does not back every view with a UIKit view anymore. For example, `Text` views may be rendered directly into a graphics render surface rather than creating a corresponding `UILabel`.
+
+This is an operating system limitation, not a limitation of the Sentry SDK. As a result, some views may not be automatically maskable.
+
+</Alert>
+
 Because of the way SwiftUI is transformed into UIKit, it will often be over-masked. A modifier like `background` uses the same element as an `Image`.
 In order to control the SwiftUI masking process, you need to use the `sentryReplayUnmask` and/or `sentryReplayMask` modifiers.
 
diff --git a/docs/platforms/apple/common/session-replay/troubleshooting.mdx b/docs/platforms/apple/common/session-replay/troubleshooting.mdx
index b3300b56d02f63..36a53c2bd6b45a 100644
--- a/docs/platforms/apple/common/session-replay/troubleshooting.mdx
+++ b/docs/platforms/apple/common/session-replay/troubleshooting.mdx
@@ -27,7 +27,9 @@ This issue has been resolved in Sentry Cocoa <strong>9.11.0</strong>. Session Re
 
 <Expandable title="Does Session Replay work with UIKit, SwiftUI or AppKit?" permalink>
 
-Session Replay works with both UIKit and SwiftUI.
+Session Replay works with both UIKit and SwiftUI. However, SwiftUI support has inherent limitations with masking because the SwiftUI rendering engine does not back every view with a UIKit view.
+
+For example, `Text` views may be rendered directly into a graphics render surface rather than creating a corresponding `UILabel`. This is an operating system limitation, not a limitation of the Sentry SDK. As a result, masking for SwiftUI views is best-effort and some views may not be automatically maskable. See <PlatformLink to="/session-replay/customredact/#swiftui">SwiftUI masking</PlatformLink> for details.
 
 </Expandable>
 
@@ -78,6 +80,7 @@ Session Replay cannot capture photo picker interfaces (`PHPickerViewController`
 On physical devices, photo pickers and camera views will not appear in session replays. On simulators, they may appear because simulators don't use the same remote rendering approach, but this behavior should not be relied upon.
 
 This limitation exists at the iOS system level and cannot be worked around by configuring `unmaskedViewClasses` or other Session Replay settings.
+
 </Expandable>
 
 <Expandable title="Session Replay is not recording with custom window setup" permalink>