From 8e843712b51efb52981c545d29621a3312d0bd5f Mon Sep 17 00:00:00 2001 From: Nelson Osacky Date: Wed, 24 Jun 2026 16:15:20 +0200 Subject: [PATCH 1/2] docs(snapshots): Document @Preview group, name, and tag metadata mapping Explain how the @Preview group and name attributes shape the sidecar JSON the Android Gradle Plugin emits per Compose preview, and which @Preview attributes become snapshot tags. Customers previously had no way to tell how to influence snapshot grouping or display names. Also extend the generic snapshot metadata schema with the tags and context objects so the documented schema matches what is emitted. Refs EME-1216 Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/platforms/android/snapshots/index.mdx | 62 ++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/docs/platforms/android/snapshots/index.mdx b/docs/platforms/android/snapshots/index.mdx index 268fabec8c5b0a..2e94614182a626 100644 --- a/docs/platforms/android/snapshots/index.mdx +++ b/docs/platforms/android/snapshots/index.mdx @@ -214,3 +214,65 @@ fun BillingPagePreview() { ``` Per-preview values take precedence over the global `diffThreshold`. See [Diff Thresholds](/product/snapshots/reviewing-snapshots/#diff-thresholds) for other ways to configure thresholds. + +### How Preview Annotations Map to Snapshot Metadata + +When you use the Compose previews path, the plugin renders one image per `@Preview` and writes a JSON metadata file next to it. The attributes you set on `@Preview` shape that metadata, which controls how the snapshot is named and grouped in Sentry. For the full schema, see [Uploading Snapshots](/product/snapshots/uploading-snapshots/#json-metadata). + +Take this preview: + +```kotlin +@Preview(name = "Dark", group = "Checkout") +@Composable +fun BillingPagePreview() { + BillingPage() +} +``` + +It produces the following metadata: + +```json +{ + "display_name": "BillingPagePreview.Dark_Checkout", + "group": "Checkout", + "tags": { + "preview_name": "Dark" + }, + "context": { + "image_file_name": "com.example.billing.BillingScreenKt.BillingPagePreview.Dark_Checkout", + "class_name": "com.example.billing.BillingScreenKt", + "method_name": "BillingPagePreview" + } +} +``` + +#### `group` + +`@Preview(group = "...")` sets the top-level `group` field, which Sentry uses to organize related snapshots in the review UI. Give previews that belong together the same `group` so they're reviewed as a set. The group also becomes part of the generated `display_name`. + +#### `name` + +`@Preview(name = "...")` distinguishes multiple previews of the same composable. It's recorded as the `preview_name` tag and appended to the `display_name`. This matters most when one composable has several previews — either multiple `@Preview` annotations or a multipreview annotation like `@PreviewLightDark` — since each variant becomes its own snapshot and `name` is what tells them apart. + + + Spaces in `name` and `group` are replaced with underscores in the generated + `display_name` and filename, but the `group` field and `preview_name` tag keep + the original value. + + +#### Tags + +The remaining `@Preview` attributes are captured as `tags` describing how the preview was rendered. Each tag is included only when the attribute differs from its default. Tag values are always serialized as strings, even for numeric and boolean attributes: + +| Tag | `@Preview` attribute | Example value | +| ----------------- | -------------------- | -------------- | +| `preview_name` | `name` | `"Dark"` | +| `locale` | `locale` | `"de"` | +| `device` | `device` | `"id:pixel_7"` | +| `font_scale` | `fontScale` | `"1.5"` | +| `api_level` | `apiLevel` | `"34"` | +| `width_dp` | `widthDp` | `"320"` | +| `height_dp` | `heightDp` | `"640"` | +| `show_system_ui` | `showSystemUi` | `"true"` | +| `show_background` | `showBackground` | `"true"` | +| `ui_mode` | `uiMode` (night bit) | `"dark"` | From 03c0491dfc98e8a611dcc8373972d3297fc808a8 Mon Sep 17 00:00:00 2001 From: Nelson Osacky Date: Fri, 26 Jun 2026 08:14:32 +0200 Subject: [PATCH 2/2] Update docs/platforms/android/snapshots/index.mdx Co-authored-by: Alex Krawiec --- docs/platforms/android/snapshots/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/android/snapshots/index.mdx b/docs/platforms/android/snapshots/index.mdx index 2e94614182a626..cadb2e840d774e 100644 --- a/docs/platforms/android/snapshots/index.mdx +++ b/docs/platforms/android/snapshots/index.mdx @@ -219,7 +219,7 @@ Per-preview values take precedence over the global `diffThreshold`. See [Diff Th When you use the Compose previews path, the plugin renders one image per `@Preview` and writes a JSON metadata file next to it. The attributes you set on `@Preview` shape that metadata, which controls how the snapshot is named and grouped in Sentry. For the full schema, see [Uploading Snapshots](/product/snapshots/uploading-snapshots/#json-metadata). -Take this preview: +Look at this example preview: ```kotlin @Preview(name = "Dark", group = "Checkout")