6482 a11y documentation (#6680)

Author: nlhkabu

docs/ui-principles.rst

@@ -21,7 +21,10 @@ code, which will make Warehouse easier to maintain in the long term.
 ---------------------------------------
 
 Ensuring Warehouse follows usability and accessibility best practices will make
-the site easier to use for everybody. At a minimum:
+the site easier to use for everybody.
+
+Warehouse follows the `WCAG 2.0 AA standard <https://www.w3.org/TR/WCAG20/>`_.
+When working on the UI:
 
 - Ensure contrast is high, particularly on text. This can be checked:
    - On Chrome by installing `Accessibility Developer Tools

warehouse/static/js/warehouse/index.js

@@ -95,15 +95,14 @@ docReady(() => {
 
   new Clipboard(".copy-tooltip").on("success", setCopiedTooltip);
 
-  // Get all elements with class "tooltipped" and bind to focousout and
-  // mouseout events. Change the "aria-label" to "original-label" attribute
-  // value.
   let setOriginalLabel = (element) => {
     element.setAttribute("data-tooltip-label", "Copy to clipboard");
     element.removeAttribute("role");
     element.blur();
   };
+
   let tooltippedElems = Array.from(document.querySelectorAll(".copy-tooltip"));
+
   tooltippedElems.forEach((element) => {
     element.addEventListener("focusout",
       setOriginalLabel.bind(undefined, element),

warehouse/static/sass/blocks/_applied-filters.scss

@@ -19,7 +19,9 @@
   <div class="applied-filters">
     // Filters go here (see filter-badge for details)
     <span class="applied-filters__add-button">
-      // Button to toggle sidebar goes here
+      <button type="button" class="-js-add-filter button button--small">
+        Add filter
+      </button>
     </div>
   </div>
 */

warehouse/static/sass/blocks/_callout-block.scss

@@ -15,12 +15,23 @@
 /*
   A block for highlighting important information:
 
+  // Basic component
   <div class="callput-block">
     <h3 class="callout-block__heading">Optional Heading</h3>
     // Any important message here.
   </div>
 
-  By default this component is styled with the primary color.
+  // Dismissable
+    - Add data attributes to connect to JS script
+    - Add ARIA labels to close button
+
+  <div class="callout-block" data-controller="dismissable" data-dismissable-identifier="releases">
+    <button type="button" title="Dismiss" data-action="click->dismissable#dismiss" class="callout-block__dismiss" aria-label="Close">
+      <i class="fa fa-times" aria-hidden="true"></i>
+    </button>
+    <h3 class="callout-block__heading">Optional Heading</h3>
+    // Any important message here.
+  </div>
 
   Modifiers:
     - danger: Makes border red

warehouse/static/sass/blocks/_checkbox-tree.scss

@@ -18,8 +18,8 @@
   <div class="checkbox-tree">
     <ul>
       <li>
-        <input class="checkbox-tree__checkbox">
-        <label class="checkbox-tree__label"></label>
+        <input class="checkbox-tree__checkbox" id="mycheckbox">
+        <label class="checkbox-tree__label" for="mycheckbox"></label>
         <!-- more tree here -->
       </li>
     </ul>

warehouse/static/sass/blocks/_copy-tooltip.scss

@@ -1,6 +1,25 @@
-// The following is derived from https://github.com/primer/tooltips
+// The following is modified from https://github.com/primer/tooltips
 // The MIT License (MIT)
-// Copyright (c) 2016 GitHub Inc.
+// Copyright (c) 2016 GitHub Inc
+
+/*
+  A tooltip that is attached to a button, incidacting that clicking the button will cause something to be copied:
+
+  <button type="button" class="copy-tooltip copy-tooltip-s" data-clipboard-target="#target" data-tooltip-label="Copy to clipboard">
+    // Text or icon
+  </button>
+
+  Data:
+    - data-clipboard-target: the content that will be copied to the clipboard
+    - data-tooltip-label: the label of the tooltip (before the button is clicked)
+
+  Modifiers:
+    - copy-tooltip-s: Tooltip appears below the button (south)
+    - copy-tooltip-n: Tooltip appears above the button (north)
+    - copy-tooltip-e: Tooltip appears to the right of the button (east)
+    - copy-tooltip-w: Tooltip appears to the left of the button (west)
+*/
+
 
 $tooltip-max-width: 250px !default;
 $tooltip-background-color: transparentize($black, 0.3) !default;

warehouse/static/sass/blocks/_dropdown.scss

@@ -14,14 +14,28 @@
 
 /*
   A dropdown - containing a trigger and dropdown content, which may include
-  links. Styled to match the banner.
-
-  <div class="dropdown">
-    <button class="dropdown__trigger">
-    <div class="dropdown__content">
-      <a class="dropdown__link">Link Here</a>
-    </div>
-  </div>
+  links.
+
+  <nav class="dropdown" aria-label="Dropdown label">
+    <button type="button" class="dropdown__trigger" aria-haspopup="true" aria-expanded="false" aria-label="button label">
+      // Button text or icon
+    </button>
+    <ul class="dropdown__content" aria-hidden="true" aria-label="Main menu">
+      <li>
+        <a class="dropdown__link" href="url">
+          // Link text
+        </a>
+      </li>
+    </ul>
+  </nav>
+
+  Accessbility:
+    - .dropdown - aria-label: label the entire dropdown. E.g. "Main navigation"
+    - .dropdown__trigger - aria-label: label the button. E.g. "Show menu"
+    - .dropdown__trigger - aria-haspopup: indicates that the button has a popup element attached
+    - .dropdown__trigger - aria-expended: indicates whether or not the popup is expanded
+    - .dropdown__content - aria-hidden: indicates whether or not list is hidden
+    - .dropdown__content - aria-label: labels the content. E.g. "Main menu"
 
   Modifiers:
     - on-menu: Styles the dropdown to match the site header

warehouse/static/sass/blocks/_filter-badge.scss

@@ -23,9 +23,9 @@
     <span class="filter-badge__description">
       // filter description here
     </span>
-    <a class="filter-badge__remove-button">
+    <button type="button" class="filter-badge__remove-button">
       // close icon here
-    </a>
+    </button>
   </div>
 */
 

warehouse/static/sass/blocks/_filter-panel.scss

@@ -20,9 +20,9 @@
     - shown over other content after being launched by a button
 
   <div class="filter-panel">
-    <a class="filter-panel__close">
-      // close button
-    </a>
+    <button type="button" class="filter-panel__close -js-close-panel" aria-label="Close panel">
+      <i class="fa fa-times" aria-hidden="true"></i>
+    </button>
     // Panel content here
   </div>
 */

warehouse/static/sass/blocks/_footer.scss

@@ -20,10 +20,14 @@
       // footer icon image goes here
     </div>
     <div class="footer__menus"> // menu wrapper
-      <ul class="footer__menu"> // 3 of these!
-        <li><h3>Menu Title</h3></li>
-        <li><a>Menu Link</a></li>
-      </ul>
+      <div class="footer__menu">
+        // H2: Menu title
+        <nav aria-label="menu label">
+          <ul>
+            <li><a>Menu Link</a></li>
+          </ul>
+        </nav>
+      </div>
     </div>
 
     <hr class="footer__divider">

warehouse/static/sass/blocks/_form-errors.scss

@@ -15,10 +15,18 @@
 /*
   A list of form errors:
 
-  <ul class="form-errors">
-    <li>This is a form error</li>
-    <li>This is another error</li>
-  </ul>
+  <input aria-describedby="my-field-errors">
+
+  <div id="my-field-errors">
+    <ul class="form-errors" role="alert">
+      <li>This is a form error</li>
+      <li>This is another error</li>
+    </ul>
+  </div>
+
+  Accessibility:
+    - Wrap the error in a div associated with the field via 'aria-describedby' 
+    - Add 'role=alert'to notify screen readers
 
   Modifiers:
     - full-width: makes error take entire available horizontal space

warehouse/static/sass/blocks/_horizontal-menu.scss

@@ -15,14 +15,17 @@
 /*
   A menu where the links stack horizontally.
 
-  <nav class="horizontal-menu">
+  <nav class="horizontal-menu" aria-label="my label">
     <ul>
       <li class="horizontal-menu__item">
         <a class="horizontal-menu__link">A horizontal link</a>
       </li>
     </ul>
   </nav>
 
+  Accessibility:
+    - Describe the menu with aria-label
+
   Modifiers:
     - tall: Adds extra padding to the menu items
     - light: Makes the links white. Use on a dark background.

warehouse/static/sass/blocks/_search-form.scss

@@ -16,7 +16,8 @@
   A horizontal search form, with an input on the left and a button on the right.
 
   <form class="search-form" role="search">
-    <input class="search-form__search">
+    <label for="my-search" class="sr-only">Search PyPI</label>
+    <input class="search-form__search" id="my-search">
     <button type="submit" class="search-form__button">
       <i class="fa fa-search" aria-hidden="true"></i>
       <span class="sr-only">Search</span>

warehouse/static/sass/blocks/_table.scss

@@ -15,14 +15,16 @@
 /*
   Tables for displaying data about a project, release or file.
 
-  <table>
+  <table class="table">
+    <caption class="sr-only">Caption for table</caption>
     <thead>
       <tr>
-        <th>Heading</th>
+        <th scope="col">Heading</th>
       </tr>
     </thead>
     <tbody>
       <tr>
+        <th scope="row">Row title</th>
         <td>Data</td>
       </tr>
     </tbody>
@@ -33,6 +35,11 @@
     e.g. the downloads table will contain 'table__upload-date' to represent the
     upload column on that table.
 
+  Accessibility:
+    - label the table with caption (for screen reader users)
+    - Add 'scope="col"' to column headings
+    - Use a th and add 'scope="row"' for row headings
+
    Modifiers:
      - downloads: specific styles for downloads table on project detail page
      - releases: specific styles for releases table on manage project page