@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
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
+80
-4
+76
src/docs/contributor/assistive_technologies.diviner
+76
src/docs/contributor/assistive_technologies.diviner
···
1
+
@title Assistive Technologies
2
+
@group developer
3
+
4
+
Information about making Phabricator accessible to assistive technologies.
5
+
6
+
Overview
7
+
========
8
+
9
+
Assistive technologies help people with disabilities use the web. For example,
10
+
screen readers can assist people with limited or no eyesight by reading the
11
+
contents of pages aloud.
12
+
13
+
Phabricator has some support for assistive technologies, and we'd like to have
14
+
more support. This document describes how to use the currently available
15
+
features to improve the accessibility of Phabricator.
16
+
17
+
18
+
Aural-Only Elements
19
+
===================
20
+
21
+
The most common issue assistive technologies encounter is buttons, links, or
22
+
other elements which only convey information visually (usually through an icon
23
+
or image).
24
+
25
+
These elements can be made more accessible by providing an aural-only label.
26
+
This label will not be displayed by visual browsers, but will be read by screen
27
+
readers.
28
+
29
+
To add an aural-only label to an element, use `javelin_tag()` with the
30
+
`aural` attribute:
31
+
32
+
javelin_tag(
33
+
'span',
34
+
array(
35
+
'aural' => true,
36
+
),
37
+
pht('Aural Label Here'));
38
+
39
+
This label should be placed inside the button or link that you are labeling.
40
+
41
+
You can also use `aural` on a container to provide an entirely different
42
+
replacement element, but should be cautious about doing this.
43
+
44
+
NOTE: You must use `javelin_tag()`, not `phutil_tag()`, to get support for
45
+
this attribute.
46
+
47
+
48
+
Visual-Only Elements
49
+
====================
50
+
51
+
Occasionally, a visual element should be hidden from screen readers. This should
52
+
be rare, but some textual elements convey very little information or are
53
+
otherwise disruptive for aural users.
54
+
55
+
This technique can also be used to offer a visual alternative of an element
56
+
and a different aural alternative element. However, this should be rare: it is
57
+
usually better to adapt a single element to work well for both visual and aural
58
+
users.
59
+
60
+
You can mark an element as visual-only by using `javelin_tag()` with the
61
+
`aural` attribute:
62
+
63
+
javelin_tag(
64
+
'span',
65
+
array(
66
+
'aural' => false,
67
+
),
68
+
$ascii_art);
69
+
70
+
71
+
Previewing Aural Pages
72
+
======================
73
+
74
+
To verify aural markup, you can add `?__aural__=1` to any page URI. This will
75
+
make Phabricator render the page with styles that reveal aural-only elements and
76
+
mute visual-only elements.
+2
-2
src/view/form/control/PhabricatorRemarkupControl.php
+2
-2
src/view/form/control/PhabricatorRemarkupControl.php