Add .show-for-sr and .show-on-focus classes and update docs, closes #6366

Author: gakimball

doc/includes/visibility/examples_accessibility_hideforsr.html

@@ -0,0 +1,14 @@
+<div class="row">
+  <div class="large-6 columns">
+    <h4>HTML</h4>
+{{#markdown}}
+```html
+<p aria-hidden="true">This text can be seen, but won't be read by a screen reader.</p>
+```
+{{/markdown}}
+  </div>
+  <div class="large-6 columns">
+    <h4>Rendered HTML</h4>
+    <p aria-hidden="true">This text can be seen, but won't be read by a screen reader.</p>
+  </div>
+</div>

doc/includes/visibility/examples_accessibility_showforsr.html

@@ -0,0 +1,16 @@
+<div class="row">
+  <div class="large-6 columns">
+    <h4>HTML</h4>
+{{#markdown}}
+```html
+<p class="show-for-sr">This text can only be read by a screen reader.</p>
+<p>There's a line of text above this one, you just can't see it.</p>
+```
+{{/markdown}}
+  </div>
+  <div class="large-6 columns">
+    <h4>Rendered HTML</h4>
+    <p class="show-for-sr">This text can only be read by a screen reader.</p>
+    <p>There's a line of text above this one, you just can't see it.</p>
+  </div>
+</div>

doc/includes/visibility/examples_accessibility_skiplinks.html

@@ -0,0 +1,15 @@
+<div class="row">
+  <div class="large-6 columns">
+    <h4>HTML</h4>
+{{#markdown}}
+```html
+<p><a class="show-on-focus" href="#mainContent">Skip to Content</a></p>
+<div id="mainContent"></div>
+```
+{{/markdown}}
+  </div>
+  <div class="large-6 columns">
+    <h4>Rendered HTML</h4>
+    <p><a class="show-on-focus" href="#">Skip to Content</a></p>
+  </div>
+</div>

doc/pages/components/visibility.html

@@ -39,6 +39,30 @@ <h3 class="subheader">Visibility classes let you show or hide elements based on
 
 ## Accessibility
 
+Adding `display: none` to an element will prevent screen readers from reading it. However, there are techniques to hide content while still making it readable by screen readers.
+
+### Show for Screen Readers Only
+
+To visually hide content, while still allowing assistive technology to read it, add the class `show-for-sr`.
+
+{{> examples_accessibility_showforsr}}
+
+### Hide for Screen Readers Only
+
+To hide text from assistive technology, while still keeping it visible, add the attribute `aria-hidden="true"`. This doesn't affect how the element looks, but screen readers will skip over it.
+
+{{> examples_accessibility_hideforsr}}
+
+### Creating Skip Links
+
+If your site has a lot of navigation, a screen reader will have to read through the entire navigation to get to your site's content. To remedy this, you can add a "skip link" at the very top of your page, which will send the user farther down the page, past the navigation when clicked on.
+
+Use the class `show-on-focus` to hide an element, *except* when it has focus.
+
+{{> examples_accessibility_skiplinks}}
+
+### Responsive Visibility
+
 Finally, if you want to hide some content but still make it accessible for screen readers, use the **hidden** visibility classes. Do not confuse these classes with **hide** visibility classes. Use these classes in conjunction with the **hide** and **show** visibility classes to control complex layouts while offering accessibility for those using screen readers.
 
 {{> examples_accessibility_hidden}}

scss/foundation/components/_visibility.scss

@@ -390,6 +390,19 @@ $visibility-breakpoint-queries:
   th.hide-for-touch { display: table-cell !important; }
   .touch th.show-for-touch { display: table-cell !important; }
 
+  /* Screen reader-specific classes */
+  .show-for-sr {
+    @include element-invisible;
+  }
+  .show-on-focus {
+    @include element-invisible;
+
+    &:focus,
+    &:active {
+      @include element-invisible-off;
+    }
+  }
+
   // Only include these styles if you want them.
     @if $include-print-styles {
       /*