Add details about hidden attribute preflight rules (#2321)

In v4 we made a change that makes elements with a hidden attribute
`display: none !important`. A consequence of this is that `<div hidden
class="block">test</div>` will be invisible in v4 where it was visible
in v3.

The intent is that you must *remove* this attribute if the element isn't
actually meant to be hidden but we didn't document this in the upgrade
guide or the preflight page.

Closes tailwindlabs/tailwindcss#18653

---------

Co-authored-by: Philipp Spiess <[email protected]>
Co-authored-by: Nicolas <[email protected]>

Author: 3 people

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 enforces that elements with a `hidden` attribute stay invisible unless using `hidden="until-found"`. 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`:

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. 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: