From 2f7508929f49dd37848d8901abd77073fadcd311 Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Thu, 1 May 2014 07:54:29 -0700
Subject: [PATCH] Document the `aural` attribute and `__aural__` preview mode

Summary:
Ref T4843. Document the new assistive features in the developer docs.

(Also use the recommended mode to set them. They're equivalent for `aural=true` (but not for `aural=false`), so this doesn't actually change anything.)

Test Plan: Read documentation.

Reviewers: btrahan, chad

Reviewed By: chad

Subscribers: epriestley

Maniphest Tasks: T4843

Differential Revision: https://secure.phabricator.com/D8926
---
 .../assistive_technologies.diviner            | 76 +++++++++++++++++++
 .../control/PhabricatorRemarkupControl.php    |  4 +-
 src/view/phui/PHUIListItemView.php            |  4 +-
 3 files changed, 80 insertions(+), 4 deletions(-)
 create mode 100644 src/docs/contributor/assistive_technologies.diviner

diff --git a/src/docs/contributor/assistive_technologies.diviner b/src/docs/contributor/assistive_technologies.diviner
new file mode 100644
index 0000000000..a519bde881
--- /dev/null
+++ b/src/docs/contributor/assistive_technologies.diviner
@@ -0,0 +1,76 @@
+@title Assistive Technologies
+@group developer
+
+Information about making Phabricator accessible to assistive technologies.
+
+Overview
+========
+
+Assistive technologies help people with disabilities use the web. For example,
+screen readers can assist people with limited or no eyesight by reading the
+contents of pages aloud.
+
+Phabricator has some support for assistive technologies, and we'd like to have
+more support. This document describes how to use the currently available
+features to improve the accessibility of Phabricator.
+
+
+Aural-Only Elements
+===================
+
+The most common issue assistive technologies encounter is buttons, links, or
+other elements which only convey information visually (usually through an icon
+or image).
+
+These elements can be made more accessible by providing an aural-only label.
+This label will not be displayed by visual browsers, but will be read by screen
+readers.
+
+To add an aural-only label to an element, use `javelin_tag()` with the
+`aural` attribute:
+
+  javelin_tag(
+    'span',
+    array(
+      'aural' => true,
+    ),
+    pht('Aural Label Here'));
+
+This label should be placed inside the button or link that you are labeling.
+
+You can also use `aural` on a container to provide an entirely different
+replacement element, but should be cautious about doing this.
+
+NOTE: You must use `javelin_tag()`, not `phutil_tag()`, to get support for
+this attribute.
+
+
+Visual-Only Elements
+====================
+
+Occasionally, a visual element should be hidden from screen readers. This should
+be rare, but some textual elements convey very little information or are
+otherwise disruptive for aural users.
+
+This technique can also be used to offer a visual alternative of an element
+and a different aural alternative element. However, this should be rare: it is
+usually better to adapt a single element to work well for both visual and aural
+users.
+
+You can mark an element as visual-only by using `javelin_tag()` with the
+`aural` attribute:
+
+  javelin_tag(
+    'span',
+    array(
+      'aural' => false,
+    ),
+    $ascii_art);
+
+
+Previewing Aural Pages
+======================
+
+To verify aural markup, you can add `?__aural__=1` to any page URI. This will
+make Phabricator render the page with styles that reveal aural-only elements and
+mute visual-only elements.
diff --git a/src/view/form/control/PhabricatorRemarkupControl.php b/src/view/form/control/PhabricatorRemarkupControl.php
index b4dc6fb09e..1f98ad6da7 100644
--- a/src/view/form/control/PhabricatorRemarkupControl.php
+++ b/src/view/form/control/PhabricatorRemarkupControl.php
@@ -138,10 +138,10 @@ final class PhabricatorRemarkupControl extends AphrontFormTextAreaControl {
       $tip = idx($spec, 'tip');
       if ($tip) {
         $meta['tip'] = $tip;
-        $content = phutil_tag(
+        $content = javelin_tag(
           'span',
           array(
-            'class' => 'aural-only',
+            'aural' => true,
           ),
           $tip);
       }
diff --git a/src/view/phui/PHUIListItemView.php b/src/view/phui/PHUIListItemView.php
index 5360771e3c..399b27ac98 100644
--- a/src/view/phui/PHUIListItemView.php
+++ b/src/view/phui/PHUIListItemView.php
@@ -205,10 +205,10 @@ final class PHUIListItemView extends AphrontTagView {
 
     $aural = null;
     if ($this->aural !== null) {
-      $aural = phutil_tag(
+      $aural = javelin_tag(
         'span',
         array(
-          'class' => 'aural-only',
+          'aural' => true,
         ),
         $this->aural);
     }