diff --git a/src/docs/preflight.mdx b/src/docs/preflight.mdx
index 7224e5c2e..4d687f03c 100644
--- a/src/docs/preflight.mdx
+++ b/src/docs/preflight.mdx
@@ -181,6 +181,17 @@ This prevents them from overflowing their containers and makes them responsive b
 <img class="max-w-none" src="..." alt="..." />
 ```
 
+#### Elements with a `hidden` attribute stay hidden
+
+```css
+/* [!code filename:CSS] */
+[hidden]:where(:not([hidden='until-found'])) {
+  display: none !important;
+}
+```
+
+This enfoces that elements with a `hidden` attribute stay invisible unless using `hidden="until-found"`. The should *remove* the `hidden` attribute if you want an element to be visible to the user.
+
 ## Extending Preflight
 
 If you'd like to add your own base styles on top of Preflight, add them to the `base` CSS layer in your CSS using `@layer base`:
diff --git a/src/docs/upgrade-guide.mdx b/src/docs/upgrade-guide.mdx
index c03e4ef8e..f97644a71 100644
--- a/src/docs/upgrade-guide.mdx
+++ b/src/docs/upgrade-guide.mdx
@@ -564,6 +564,10 @@ If you still want dialogs to be centered by default, add this CSS to your projec
 }
 ```
 
+#### Hidden attribute takes priority
+
+Display classes like `block` or `flex` no longer take priority over the `hidden` attribute on an element. You should *remove* the `hidden` attribute if you want an element to be visible to the user. Note that this does not apply to `hidden="until-found"`.
+
 ### Using a prefix
 
 Prefixes now look like variants and are always at the beginning of the class name: