From 2b6276f6856c5d1198e951ac75407d2919784a61 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Wed, 28 Dec 2016 14:43:06 -0800
Subject: [PATCH] redo main example to work in screen reader love instead of
 putting it in a callout

---
 docs/components/pagination.md | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/docs/components/pagination.md b/docs/components/pagination.md
index dadc73bd29..e23c257205 100644
--- a/docs/components/pagination.md
+++ b/docs/components/pagination.md
@@ -14,7 +14,21 @@ Pagination links indicate a series of related content exists across multiple pag
 
 ## Overview
 
-Simple pagination inspired by Rdio, great for apps and search results. The large block is hard to miss, easily scalable, and provides large click areas.
+We use a large block of connected links for our pagination, making links hard to miss and easily scalable—all while providing large hit areas. Pagination is built with list HTML elements so screen readers can announce the number of available links. Use a wrapping `<nav>` element to identify it as a navigation section to screen readers and other assistive technologies.
+
+In addition, as pages likely have more than one such navigation section, it's advisable to provide a descriptive `aria-label` for the `<nav>` to reflect its purpose. For example, if the pagination component is used to navigate between a set of search results, an appropriate label could be `aria-label="Search results pages"`.
+
+{% example html %}
+<nav aria-label="Page navigation example">
+  <ul class="pagination">
+    <li class="page-item"><a class="page-link" href="#">Previous</a></li>
+    <li class="page-item"><a class="page-link" href="#">1</a></li>
+    <li class="page-item"><a class="page-link" href="#">2</a></li>
+    <li class="page-item"><a class="page-link" href="#">3</a></li>
+    <li class="page-item"><a class="page-link" href="#">Next</a></li>
+  </ul>
+</nav>
+{% endexample %}
 
 {% example html %}
 <nav aria-label="Page navigation">
@@ -40,12 +54,6 @@ Simple pagination inspired by Rdio, great for apps and search results. The large
 </nav>
 {% endexample %}
 
-{% callout info %}
-### Labelling the pagination component
-
-The pagination component should be wrapped in a `<nav>` element to identify it as a navigation section to screen readers and other assistive technologies. In addition, as a page is likely to have more than one such navigation section already (such as the primary navigation in the header, or a sidebar navigation), it is advisable to provide a descriptive `aria-label` for the `<nav>` which reflects its purpose. For example, if the pagination component is used to navigate between a set of search results, an appropriate label could be `aria-label="Search results pages"`.
-{% endcallout %}
-
 ## Disabled and active states
 
 Links are customizable for different circumstances. Use `.disabled` for unclickable links and `.active` to indicate the current page.