From c91e4f5162af55c2e616f429767d6e328855471b Mon Sep 17 00:00:00 2001
From: Chris Rebert <code@chrisrebert.com>
Date: Wed, 23 Sep 2015 18:57:21 -0700
Subject: [PATCH] Clarify [hidden] attr docs; closes #17169

[ci skip]
---
 docs/components/utilities.md | 26 ++++++++++++++++----------
 docs/migration.md            |  2 +-
 2 files changed, 17 insertions(+), 11 deletions(-)

diff --git a/docs/components/utilities.md b/docs/components/utilities.md
index 4ee1d46f31..f3c68463aa 100644
--- a/docs/components/utilities.md
+++ b/docs/components/utilities.md
@@ -232,16 +232,6 @@ Easily clear `float`s by adding `.clearfix` **to the parent element**. Utilizes
 }
 {% endhighlight %}
 
-## Hidden content
-
-Hide any HTML element with the `[hidden]` attribute. It's taken from [PureCSS](http://purecss.io). While `[hidden]` isn't natively supported by IE9-10, declaring it `display: none` in our CSS gets around that problem.
-
-Furthermore, `.invisible` can be used to toggle the visibility of an element, meaning its `display` is not modified and the element can still affect the flow of the document.
-
-{% highlight html %}
-<input type="text" hidden>
-{% endhighlight %}
-
 ## Invisible content
 
 The `.invisible` class can be used to toggle only the visibility of an element, meaning its `display` is not modified and the element can still affect the flow of the document.
@@ -329,3 +319,19 @@ Aspect ratios can be customized with modifier classes.
   <iframe class="embed-responsive-item" src="..."></iframe>
 </div>
 {% endhighlight %}
+
+## HTML5 `[hidden]` attribute
+
+HTML5 adds [a new global attribute named `[hidden]`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/hidden), which is styled as `display: none` by default. Borrowing an idea from [PureCSS](http://purecss.io), we improve upon this default by making `[hidden] { display: none !important; }` to help prevent its `display` from getting accidentally overridden. While `[hidden]` isn't natively supported by IE9-10, the explicit declaration in our CSS gets around that problem.
+
+{% highlight html %}
+<input type="text" hidden>
+{% endhighlight %}
+
+{% callout warning %}
+#### jQuery incompatibility
+
+`[hidden]` is not compatible with jQuery's `$(...).hide()` and `$(...).show()` methods. This could potentially change in jQuery 3, but we're not holding our breath. Therefore, we don't currently especially endorse `[hidden]` over other techniques for managing the `display` of elements.
+{% endcallout %}
+
+To merely toggle the visibility of an element, meaning its `display` is not modified and the element can still affect the flow of the document, use [the `.invisible` class](#invisible-content) instead.
diff --git a/docs/migration.md b/docs/migration.md
index 6f060c397c..d1b8c33750 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -179,7 +179,7 @@ Note that the changes to the grid breakpoints in v4 means that you'll need to go
 ## Misc notes to prioritize
 
 - Removed the `min--moz-device-pixel-ratio` typo hack for retina media queries
-- Dropped `.hidden` and `.show` because they conflict with jQuery's `$(...).hide()` function.
+- Dropped `.hidden` and `.show` because they conflict with jQuery's `$(...).hide()` and `$(...).show()` methods.
 - Change buttons' `[disabled]` to `:disabled` as IE9+ supports `:disabled`. However `fieldset[disabled]` is still necessary because [native disabled fieldsets are still buggy in IE11](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset#Browser_compatibility).
 
 TODO: audit list of stuff in v3 that was marked as deprecated