redo main example to work in screen reader love instead of putting it in a callout

1 files changed, 15 insertions, 7 deletions

diff --git a/docs/components/pagination.md b/docs/components/pagination.md
index dadc73bd2..e23c25720 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.