diff --git a/docs/platforms/apple/common/snapshots/snapshotpreviews-metadata.mdx b/docs/platforms/apple/common/snapshots/snapshotpreviews-metadata.mdx
index 6f39e668f54c3..083b94aecc131 100644
--- a/docs/platforms/apple/common/snapshots/snapshotpreviews-metadata.mdx
+++ b/docs/platforms/apple/common/snapshots/snapshotpreviews-metadata.mdx
@@ -35,6 +35,7 @@ import SnapshotPreferences
       ],
     ])
     .snapshotDiffThreshold(0.01)
+    .snapshotCanvasTheme(.dark)
 }
 ```
 
@@ -45,6 +46,7 @@ import SnapshotPreferences
 | `.snapshotTags([String: String])`           | Adds top-level `tags` to the sidecar for filtering or grouping snapshots.                                                                             |
 | `.snapshotAdditionalContext([String: Any])` | Adds arbitrary key-value context to the sidecar `context` object. Values can be strings, numbers, booleans, or nested objects.                        |
 | `.snapshotDiffThreshold(Float?)`            | Adds a local `diff_threshold` for this preview. Sentry reports the image as changed only when the share of changed pixels is greater than this value. |
+| `.snapshotCanvasTheme(SnapshotCanvasTheme)` | Sets the top-level `canvas_theme` (`.light` or `.dark`) used behind the image in Sentry's web UI. Display metadata only; it doesn't change the rendered snapshot image. |
 
 ## Generated Sidecar Metadata
 
@@ -59,6 +61,7 @@ SnapshotPreviews generates default sidecar metadata for each preview. The exact
     "team": "growth"
   },
   "diff_threshold": 0.01,
+  "canvas_theme": "dark",
   "context": {
     "test_name": "-[YourAppSnapshotTest portrait-Checkout Preview-1-6]",
     "accessibility_enabled": false,
diff --git a/docs/product/snapshots/uploading-snapshots/index.mdx b/docs/product/snapshots/uploading-snapshots/index.mdx
index 5a6eee8153fa8..4d29e5fefb893 100644
--- a/docs/product/snapshots/uploading-snapshots/index.mdx
+++ b/docs/product/snapshots/uploading-snapshots/index.mdx
@@ -53,6 +53,7 @@ You can include an optional JSON file to add metadata to each image:
     "team": "growth"
   },
   "diff_threshold": 0.01,
+  "canvas_theme": "dark",
   "context": {
     "component": "BillingPage",
     "variant": {
@@ -69,6 +70,7 @@ You can include an optional JSON file to add metadata to each image:
 | `group`          | string | Groups related snapshots in the UI sidebar.                                                                                                                            |
 | `tags`           | object | Key-value string labels attached to the snapshot. Use them to filter and group snapshots in the viewer, for example by theme, viewport, or component variant.          |
 | `diff_threshold` | number | Value from `0.0` to `1.0`. Sentry reports the image as changed only when the share of changed pixels is greater than this value. `0.01` ignores changes of 1% or less. |
+| `canvas_theme`   | string | `"light"` or `"dark"`. Controls the background canvas Sentry renders behind the snapshot image in the web UI. Display metadata only; it doesn't change the rendered image. |
 | `context`        | object | Arbitrary key-value context that tools and LLMs can use to help diagnose changes. Values can be strings, numbers, booleans, or nested objects.                         |
 
 ![Example of how metadata impacts the Sentry UI](../img/sentry_ui_metadata.png)