diff --git a/doc/migrating-libhandy-1-4-to-libadwaita.md b/doc/migrating-libhandy-1-4-to-libadwaita.md
index 3f73923a56fadee69f24fe10fe57f8b8361d8956..32aa81ac407adb6f7c26cdc6e9aca4b757e3e1db 100644
--- a/doc/migrating-libhandy-1-4-to-libadwaita.md
+++ b/doc/migrating-libhandy-1-4-to-libadwaita.md
@@ -458,6 +458,14 @@ style.
 The same rules are also used for the [`.toolbar`](style-classes.html#toolbars)
 style class now, instead of making every button appear flat.
 
+#### Adapt to Selection Mode Changes
+
+The `.selection-mode` style class no longer recolors headerbars. Instead
+of using the old styling, rework your selection modes to follow
+[the new pattern for selection modes](https://developer.gnome.org/hig/patterns/containers/selection-mode.html)
+and the [`.selection-mode`](style-classes.html#selection-mode-check-buttons)
+style class on [class@Gtk.CheckButton].
+
 ### Adapt to List Style Changes
 
 For boxed lists we now have the