From bb89657bcb53a60d579d8fd9bbea56dde05dad8c Mon Sep 17 00:00:00 2001 From: "Patrick H. Lauke" Date: Thu, 30 Oct 2014 16:45:33 +0000 Subject: Assorted accessibility (and some consistency) fixes for documentation Closes #14951 by merging it. --- docs/_includes/css/buttons.html | 14 +++++- docs/_includes/css/forms.html | 104 +++++++++++++++++++++++----------------- docs/_includes/css/grid.html | 2 +- docs/_includes/css/helpers.html | 8 ++++ docs/_includes/css/tables.html | 5 +- 5 files changed, 86 insertions(+), 47 deletions(-) (limited to 'docs/_includes/css') diff --git a/docs/_includes/css/buttons.html b/docs/_includes/css/buttons.html index ee03c1d65..1b3f46416 100644 --- a/docs/_includes/css/buttons.html +++ b/docs/_includes/css/buttons.html @@ -35,6 +35,11 @@ {% endhighlight %} +
+

Conveying meaning to assistive technologies

+

Using color to add meaning to a button only provides a visual indication, which will not be conveyed to users of assistive technologies – such as screen readers. Ensure that information denoted by the color is either obvious from the content itself (the visible text of the button), or is included through alternative means, such as additional text hidden with the sr-only class.

+
+

Sizes

Fancy larger or smaller buttons? Add .btn-lg, .btn-sm, or .btn-xs for additional sizes.

@@ -88,7 +93,7 @@

Active state

-

Buttons will appear pressed (with a darker background, darker border, and inset shadow) when active. For <button> elements, this is done via :active. For <a> elements, it's done with .active. However, you may use .active on <button>s should you need to replicate the active state programmatically.

+

Buttons will appear pressed (with a darker background, darker border, and inset shadow) when active. For <button> elements, this is done via :active. For <a> elements, it's done with .active. However, you may use .active on <button>s (and include the aria-pressed="true" attribute) should you need to replicate the active state programmatically.

Button element

No need to add :active as it's a pseudo-class, but if you need to force the same appearance, go ahead and add .active.

@@ -147,7 +152,7 @@

Link functionality caveat

-

This class uses pointer-events: none to try to disable the link functionality of <a>s, but that CSS property is not yet standardized and isn't fully supported in Opera 18 and below, or in Internet Explorer 11. So to be safe, use custom JavaScript to disable such links.

+

This class uses pointer-events: none to try to disable the link functionality of <a>s, but that CSS property is not yet standardized and isn't fully supported in Opera 18 and below, or in Internet Explorer 11. In addition, even in browsers that do support pointer-events: none, keyboard navigation remains unaffected, meaning that sighted keyboard users and users of assistive technologies will still be able to activate these links. So to be safe, use custom JavaScript to disable such links.

Context-specific usage

@@ -170,6 +175,11 @@ {% endhighlight %} +
+

Links acting as buttons

+

If the <a> elements are used to act as buttons – triggering in-page functionality, rather than navigating to another document or section within the current page – they should also be given an appropriate role="button".

+
+

Cross-browser rendering

As a best practice, we highly recommend using the <button> element whenever possible to ensure matching cross-browser rendering.

diff --git a/docs/_includes/css/forms.html b/docs/_includes/css/forms.html index 33e0befb1..6fabb4c78 100644 --- a/docs/_includes/css/forms.html +++ b/docs/_includes/css/forms.html @@ -63,7 +63,7 @@

Always add labels

-

Screen readers will have trouble with your forms if you don't include a label for every input. For these inline forms, you can hide the labels using the .sr-only class.

+

Screen readers will have trouble with your forms if you don't include a label for every input. For these inline forms, you can hide the labels using the .sr-only class. There are further alternative methods of providing a label for assistive technologies, such as the aria-label, aria-labelledby or title attribute. If none of these is present, screen readers may resort to using the placeholder attribute, if present, but note that use of placeholder as a replacement for other labelling methods is not advised.

@@ -91,14 +91,11 @@
{% highlight html %} -
- - -
+
@
- +
@@ -205,7 +202,7 @@

Form control which supports multiple lines of text. Change rows attribute as necessary.

- +
{% highlight html %} @@ -334,18 +331,18 @@ {% endhighlight %} -

Checkboxes and radios without labels

-

Should you have no text within the <label>, the input is positioned as you'd expect. Currently only works on non-inline checkboxes and radios.

+

Checkboxes and radios without label text

+

Should you have no text within the <label>, the input is positioned as you'd expect. Currently only works on non-inline checkboxes and radios. Remember to still provide some form of label for assistive technologies (for instance, using aria-label).

@@ -353,12 +350,12 @@ {% highlight html %}
{% endhighlight %} @@ -464,7 +461,7 @@ {% endhighlight %} -

Input focus

+

Focus state

We remove the default outline styles on some form controls and apply a box-shadow in its place for :focus.

@@ -477,7 +474,7 @@
-

Disabled inputs

+

Disabled state

Add the disabled boolean attribute on an input to prevent user input and trigger a slightly different look.

@@ -547,7 +544,7 @@ {% endhighlight %} -

Readonly inputs

+

Readonly state

Add the readonly boolean attribute on an input to prevent user input and style the input as disabled.

@@ -562,6 +559,12 @@

Validation states

Bootstrap includes validation styles for error, warning, and success states on form controls. To use, add .has-warning, .has-error, or .has-success to the parent element. Any .control-label, .form-control, and .help-block within that element will receive the validation styles.

+
+

Conveying validation state to assistive technologies

+

Using these validation styles to denote the state of a form control only provides a visual indication, which will not be conveyed to users of assistive technologies – such as screen readers.

+

Ensure that an alternative indication of state is also provided. For instance, you can include a hint about state in the form control's <label> text itself (as is the case in the following code example), or associate an additional element with textual information about the validation state with the form control using aria-describedby (see the example in the following section). In the case of an error, you could also use the aria-invalid="true" attribute on the form control.

+
+
@@ -648,40 +651,45 @@

Icons, labels, and input groups

Manual positioning of feedback icons is required for inputs without a label and for input groups with an add-on on the right. You are strongly encouraged to provide labels for all inputs for accessibility reasons. If you wish to prevent labels from being displayed, hide them with the sr-only class. If you must do without labels, adjust the top value of the feedback icon. For input groups, adjust the right value to an appropriate pixel value depending on the width of your addon.

+
+

Conveying the icon's meaning to assistive technologies

+

To ensure that assistive technologies – such as screen readers – correctly convey the meaning of an icon, additional hidden text should be included with the sr-only class, and the icon itself explicitly associated with the form control it relates to using aria-describedby. Alternatively, ensure that the meaning (for instance, the fact that there is a warning for a particular text entry field) is conveyed in some other form, such as changing the text of the actual <label> associated with the form control.

+

Although the following examples already mention the validation state of their respective form controls in the <label> text itself, the above technique (using sr-only text and aria-describedby) has been included for illustrative purposes.

+
- - + +
- - + +
- - + +
{% highlight html %}
- - + +
- - + +
- - + +
{% endhighlight %} @@ -691,8 +699,8 @@
- - + +
@@ -702,8 +710,8 @@
- - + +
@@ -713,8 +721,8 @@
- - + +
@@ -722,8 +730,8 @@
- - + +
{% endhighlight %} @@ -733,15 +741,15 @@
- - + +
{% highlight html %}
- - + +
{% endhighlight %} @@ -849,13 +857,23 @@

Help text

Block level help text for form controls.

+
+

Associating help text with form controls

+

Help text should be explicitly associated with the form control it relates to using the aria-describedby attribute. This will ensure that assistive technologies – such as screen readers – will announce this help text when the user focuses or enters the control.

+
- - A block of help text that breaks onto a new line and may extend beyond one line. +
+ + +
+ A block of help text that breaks onto a new line and may extend beyond one line.
{% highlight html %} -A block of help text that breaks onto a new line and may extend beyond one line. + + +... +A block of help text that breaks onto a new line and may extend beyond one line. {% endhighlight %}
diff --git a/docs/_includes/css/grid.html b/docs/_includes/css/grid.html index 429ef90f9..cea5b17ee 100644 --- a/docs/_includes/css/grid.html +++ b/docs/_includes/css/grid.html @@ -226,7 +226,7 @@
{% endhighlight %} -

Example: Mobile, tablet, desktops

+

Example: Mobile, tablet, desktop

Build on the previous example by creating even more dynamic and powerful layouts with tablet .col-sm-* classes.

diff --git a/docs/_includes/css/helpers.html b/docs/_includes/css/helpers.html index 9b7223740..a661ded22 100644 --- a/docs/_includes/css/helpers.html +++ b/docs/_includes/css/helpers.html @@ -23,6 +23,10 @@

Dealing with specificity

Sometimes emphasis classes cannot be applied due to the specificity of another selector. In most cases, a sufficient workaround is to wrap your text in a <span> with the class.

+
+

Conveying meaning to assistive technologies

+

Using color to add meaning only provides a visual indication, which will not be conveyed to users of assistive technologies – such as screen readers. Ensure that information denoted by the color is either obvious from the content itself (the contextual colors are only used to reinforce meaning that is already present in the text/markup), or is included through alternative means, such as additional text hidden with the .sr-only class.

+

Contextual backgrounds

Similar to the contextual text color classes, easily set the background of an element to any contextual class. Anchor components will darken on hover, just like the text classes.

@@ -44,6 +48,10 @@

Dealing with specificity

Sometimes contextual background classes cannot be applied due to the specificity of another selector. In some cases, a sufficient workaround is to wrap your element's content in a <div> with the class.

+
+

Conveying meaning to assistive technologies

+

As with contextual colors, ensure that any meaning conveyed through color is also conveyed in a format that is not purely presentational.

+

Close icon

Use the generic close icon for dismissing content like modals and alerts.

diff --git a/docs/_includes/css/tables.html b/docs/_includes/css/tables.html index 011a4dbba..d09c34068 100644 --- a/docs/_includes/css/tables.html +++ b/docs/_includes/css/tables.html @@ -346,7 +346,10 @@ ... {% endhighlight %} - +
+

Conveying meaning to assistive technologies

+

Using color to add meaning to a table row or individual cell only provides a visual indication, which will not be conveyed to users of assistive technologies – such as screen readers. Ensure that information denoted by the color is either obvious from the content itself (the visible text in the relevant table row/cell), or is included through alternative means, such as additional text hidden with the sr-only class.

+

Responsive tables

Create responsive tables by wrapping any .table in .table-responsive to make them scroll horizontally on small devices (under 768px). When viewing on anything larger than 768px wide, you will not see any difference in these tables.

-- cgit v1.2.3