Merge pull request #10100 from twbs/document_hide_text

Fixes #10076: Document hide text

_includes/nav-css.html

@@ -81,6 +81,7 @@
     <li><a href="#helper-classes-floats">Quick floats</a></li>
     <li><a href="#helper-classes-clearfix">Clearfix</a></li>
     <li><a href="#helper-classes-screen-readers">Screen reader content</a></li>
+    <li><a href="#helper-classes-image-replacement">Image replacement</a></li>
   </ul>
 </li>
 <li>

css.html

@@ -2292,6 +2292,18 @@ <h3 id="helper-classes-screen-readers">Screen reader content</h3>
 }
 {% endhighlight %}
 
+
+    <h3 id="helper-classes-image-replacement">Image replacement</h3>
+    <p>Utilize the <code>.text-hide</code> class or mixin to help replace an element's text content with a background image.</p>
+{% highlight html %}
+<h1 class="text-hide">Custom heading</h1>
+{% endhighlight %}
+  {% highlight css %}
+// Usage as a Mixin
+.heading {
+  .text-hide();
+}
+{% endhighlight %}
   </div>
 
 

less/mixins.less

@@ -69,14 +69,30 @@
 }
 
 // CSS image replacement
+//
+// Heads up! v3 launched with with only `.hide-text()`, but per our pattern for
+// mixins being reused as classes with the same name, this doesn't hold up. As
+// of v3.0.1 we have added `.text-hide()` and deprecated `.hide-text()`. Note
+// that we cannot chain the mixins together in Less, so they are repeated.
+//
 // Source: https://github.com/h5bp/html5-boilerplate/commit/aa0396eae757
+
+// Deprecated as of v3.0.1 (will be removed in v4)
 .hide-text() {
   font: ~"0/0" a;
   color: transparent;
   text-shadow: none;
   background-color: transparent;
   border: 0;
 }
+// New mixin to use as of v3.0.1
+.text-hide() {
+  font: ~"0/0" a;
+  color: transparent;
+  text-shadow: none;
+  background-color: transparent;
+  border: 0;
+}
 
 
 

less/utilities.less

@@ -30,7 +30,7 @@
   visibility: hidden;
 }
 .text-hide {
-  .hide-text();
+  .text-hide();
 }