diff --git a/TESTING.md b/TESTING.md
index f27419037..56be29113 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -201,6 +201,42 @@ itself is for. If a `group` is doing the work a separate file should be doing,
 [split the file instead](STYLE_GUIDE.md#prefer-more-test-files-avoid-long-test-files).
 Nested groups more than one level deep are almost always a signal to split.
 
+## A failing golden on a local run is not necessarily a regression
+
+Committed goldens are always generated on CI, so they encode that host's font
+hinting and antialiasing. A local `flutter test` renders differently, and will
+report golden failures that have nothing to do with your change. Never conclude
+"my change broke these goldens" from a local run alone, and never conclude the
+opposite either — that a green local run means you changed nothing visually.
+
+To find out what your change actually affected, compare **two local runs** instead
+of comparing against the committed PNGs:
+
+```bash
+# 1. with your change reverted (git stash), regenerate and keep a copy
+GITHUB_ACTIONS=true flutter test --update-goldens
+cp -R <goldens/ci dirs> /tmp/baseline/
+
+# 2. restore your change, regenerate again, and diff the two sets
+GITHUB_ACTIONS=true flutter test --update-goldens
+```
+
+Whatever differs between the two sets is genuinely yours; everything else is host
+drift. Amplifying the pixel diff (e.g. with PIL) makes a subtle change easy to
+confirm.
+
+Two things that make this easy to get wrong:
+
+- Only `goldens/ci/` is committed — `goldens/<platform>/` is gitignored. A local
+  run silently rewrites the platform goldens and `git status` stays clean, so an
+  empty `git status` is not evidence that nothing changed.
+- Alchemist picks CI goldens off the `GITHUB_ACTIONS` environment variable (see
+  `test/flutter_test_config.dart`). Without it you are exercising the gitignored
+  platform goldens, not the ones CI compares against.
+
+Regenerate committed goldens with the `update_goldens` GitHub Action, never from
+your machine — see [Golden tests in STYLE_GUIDE.md](STYLE_GUIDE.md#golden-tests).
+
 ## See also
 
 - [STYLE_GUIDE.md — Testing](STYLE_GUIDE.md#testing) — repo-level testing conventions
diff --git a/packages/stream_chat_flutter/CHANGELOG.md b/packages/stream_chat_flutter/CHANGELOG.md
index 2220c44b4..6fec50ac6 100644
--- a/packages/stream_chat_flutter/CHANGELOG.md
+++ b/packages/stream_chat_flutter/CHANGELOG.md
@@ -24,6 +24,7 @@
 - Fixed the attachment picker throwing a `Tooltip` assertion error when a custom `TabbedAttachmentPickerOption` is added without a `title`; the tooltip is now only shown when a title is provided.
 - Fixed the `StreamBackButton` unread badge including the currently open channel in its total count.
 - Fixed `StreamMessageListView` jumping several screens when selecting text in a message on desktop or web. The `ScrollablePositionedList` viewports now account for their `anchor` in `getOffsetToReveal`, so implicit reveals (`Scrollable.ensureVisible`, `RenderObject.showOnScreen`) no longer overshoot. [#2862](https://github.com/GetStream/stream-chat-flutter/issues/2862)
+- Fixed modal dialogs (message actions, delete/flag confirmation) rendering over a white scrim in light theme; they now use the design system's scrim token.
 
 ## 10.2.0
 
diff --git a/packages/stream_chat_flutter/lib/src/misc/stream_modal.dart b/packages/stream_chat_flutter/lib/src/misc/stream_modal.dart
index ecac364cd..9abf79ef8 100644
--- a/packages/stream_chat_flutter/lib/src/misc/stream_modal.dart
+++ b/packages/stream_chat_flutter/lib/src/misc/stream_modal.dart
@@ -39,7 +39,7 @@ Future<T?> showStreamDialog<T>({
     routeSettings: routeSettings,
     transitionDuration: transitionDuration,
     barrierDismissible: barrierDismissible,
-    barrierColor: barrierColor ?? colorScheme.backgroundOverlayLight,
+    barrierColor: barrierColor ?? colorScheme.backgroundScrim,
     barrierLabel: barrierLabel ?? localizations.modalBarrierDismissLabel,
     transitionBuilder: (context, animation, secondaryAnimation, child) {
       final sigma = 10 * animation.value;