docs: add <rh-back-to-top> content

elements/rh-back-to-top/docs/10-overview.md → elements/rh-back-to-top/docs/00-overview.md

@@ -2,8 +2,16 @@
 
 {{ tagName | getElementDescription }}
 
+{% example palette="light",
+           alt="Example of a back to top button",
+           src="back-to-top.svg" %}
+
 {% repoStatusList %}
 
+## Sample
+
+View a demo below.
+
 ## Demos
   View a live version of this component and see how it can be customized.
   {% playground tagName=tagName %}{% endplayground %}
@@ -13,7 +21,8 @@
 
 
 ## When to use
-  - 
+  - When content fills up more than two screens in length at medium and large breakpoints
+  - When content fills up more than four screens in length at small breakpoints
 
 {% repoStatusChecklist %}
 

elements/rh-back-to-top/docs/10-style.md

@@ -0,0 +1,72 @@
+## Style
+
+A back to top is a pill-shaped button that is anchored to the bottom right corner of a page.
+
+###  Anatomy
+
+{% example palette="light",
+            alt="A back to top button with numerical annotations",
+            src="../back-to-top-anatomy.svg" %}
+
+1. Container
+2. Text
+3. Icon
+{.example-notes}
+
+## Theme
+
+The back to top button looks the same in light and dark themes.
+
+<div class="multi-column--min-400-wide">
+{% example palette="light",
+           class="centered",
+           alt="Back to top button with a blue background and white text against a white surface color",
+           src="../back-to-top.svg" %}
+
+{% example palette="darkest",
+           class="centered",
+           alt="Back to top buttons that have a blue background and white text against a black surface color",
+           src="../back-to-top.svg" %}
+</div>
+
+
+## Space
+
+A back to top button has 4px of padding on the left and right, 8px of padding on the top and bottom, and a 4px gap between text and icon. The amount of space remains the same on all breakpoints.
+
+{% example palette="light",
+          class="centered",
+          alt="A back to top button with block padding of 4px, inline padding of 8px, and a 4px gap between text and icon",
+          src="../back-to-top-space.svg" %}
+
+## Interaction states
+
+Interaction states are visual representations used to communicate the status of an element or pattern.
+
+### Hover
+
+The background color of the button turns to a darker blue on hover. It also has a white border adjacent to the button and a dark blue outline adjacent to the border. This ensures contrast against all surface colors.
+
+{% example palette="light",
+          alt="A back to top button with a dark blue background when a cursor hovers over it",
+          src="../back-to-top-focus-hover-active.svg" %}
+
+### Focus
+
+{% alert title="Helpful tip" %}
+The Focus state has the same styles as the Hover state.
+{% endalert %}
+
+{% example palette="light",
+          alt="A back to top button with a dark blue background and a blue focus ring around it",
+          src="../back-to-top-focus-hover-active.svg" %}
+
+### Active
+
+{% alert title="Helpful tip" %}
+The Active state has the same styles as the Hover state.
+{% endalert %}
+
+{% example palette="light",
+          alt="A back to top button with a dark blue background and a blue focus ring around it",
+          src="../back-to-top-focus-hover-active.svg" %}

elements/rh-back-to-top/docs/20-guidelines.md

@@ -0,0 +1,78 @@
+## Usage
+
+A back to top button helps users get back to the top of the page quickly. It should be used on pages where a user would have to scroll through two screens worth of content on medium and large screens and four screens worth of content on small screens. If a page is very short and doesn’t require scrolling, a back to top button doesn’t have to be added.
+
+## Layout
+
+### Placement
+
+Users expect to see the back to top button in the bottom right corner. It will overlap any page content in that small area. This placement keeps it out of the way of page content but still discoverable.
+
+On mobile, the element should be positioned 24px from the bottom and from the right of the screen. On screens wider than 768px, it should appear 48px from the bottom and from the right.
+
+{% example palette="none",
+          alt="Back to top buttons in the bottom right corner of a desktop-sized screen",
+          src="../back-to-top-placement-desktop.jpg" %}
+
+{% example palette="none",
+          alt="Back to top buttons in the bottom right corner of a phone-sized screen",
+          src="../back-to-top-placement-phone.jpg" %}
+
+## Behavior
+
+When a user scrolls down the page, the back to top element appears in the bottom right corner. As the user continues to scroll, the element should remain stationary, unless the user has scrolled to the top of the page.
+
+Once the user clicks the back to top button, they will be taken to the top of the page.
+
+## Best practices
+
+### One back to top element per page
+
+Having only one persistent back to top button ensures that users are able to scroll up to the top easily. Having “Back to top” buttons at the bottom of multiple sections adds to visual clutter and may lead to users ignoring the button.
+
+<div class="best-practices-grid">
+    <div>
+        <img slot="header" src="../one-back-to-top-do.svg" alt="Image of wireframe with one back to top button">
+        <h4 class="correct">Do</h4>
+        <p>Have one back to top button in the bottom right corner of the page.</p>
+    </div>
+    <div>
+        <img slot="header" src="../one-back-to-top-dont.svg" alt="Image of wireframe with back to top buttons below each content section">
+        <h4 class="wrong">Don't</h4>
+        <p>Do not use multiple back to top buttons.</p>
+    </div>
+</div>
+
+### “Back to top” text
+
+We recommend retaining the “Back to top” text to ensure that users understand the button’s purpose.
+
+<div class="best-practices-grid">
+    <div>
+        <img slot="header" src="../back-to-top.svg" alt="Image of back to top button with “back to top” text and icon">
+        <h4 class="correct">Do</h4>
+        <p>Keep the descriptive “Back to top” text in the button.</p>
+    </div>
+    <div>
+        <img slot="header" src="../back-to-top-icon-only.svg" alt="Image of back to top button with icon only">
+        <h4 class="wrong">Don't</h4>
+        <p>Do  not use only an up arrow icon.</p>
+    </div>
+</div>
+
+### Spacing
+
+Ensure that there is enough space between the button and the edges of the page for users to click it easily at any screen size. In addition to making it easier for users to click, this will also prevent the scrollbars from overlapping the button.
+
+<div class="best-practices-grid">
+    <div>
+        <img slot="header" src="../back-to-top-spacing-do.svg" alt="Image of back to top button enough spacing from scroll bars">
+        <h4 class="correct">Do</h4>
+        <p>Add ample space between the right and bottom edges.</p>
+    </div>
+    <div>
+        <img slot="header" src="../back-to-top-spacing-dont.svg" alt="Image of back to top button with very little spacing next to scrollbars">
+        <h4 class="wrong">Don't</h4>
+        <p>Do not place the button too close to the edges of the screen.</p>
+    </div>
+</div>

elements/rh-back-to-top/docs/40-accessibility.md

@@ -0,0 +1,29 @@
+## Keyboard navigation
+
+Users should have the ability to navigate to and interact with the back to top button using their keyboard.
+
+{% example palette="light",
+           class="centered",
+           alt="Example of a page with footer links and a back to top button that has keyboard interaction annotations",
+           src="../back-to-top-keyboard-nav.png" %}
+
+| Key {style="width: 33%" } | Result                                                                                         |
+| ------------------------- | ---------------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd>            | Shifts focus to the back to top button                                              |
+| <kbd>Shift + Tab</kbd>    | Shifts focus to a previous interactive element     |
+| <kbd>Enter</kbd>          | Activates the back to top button and moves focus to the first interactive element on the page                                   |
+
+## Focus order
+
+As long as the back to top button is only at the bottom of the page, it should be the last interactive element on the page to receive focus.
+
+{% include 'accessibility/ariaguide.md' %}
+
+{% include 'accessibility/wcag.md' %}
+{% include 'accessibility/1.2.1-A.md' %}
+{% include 'accessibility/1.2.2-A.md' %}
+{% include 'accessibility/1.4.1-A.md' %}
+{% include 'accessibility/2.1.1-A.md' %}
+{% include 'accessibility/2.1.3-AAA.md' %}
+{% include 'accessibility/2.4.3-A.md' %}
+{% include 'accessibility/2.5.5-AAA.md' %}