style-guide(add-a11y): Add accessibility quick wins

angular · Jul 10, 2016 · 298fffa · 298fffa
1 parent 0664a27
commit 298fffa
Show file tree

Hide file tree

Showing 12 changed files with 346 additions and 1 deletion.
diff --git a/public/docs/_examples/style-guide/e2e-spec.ts b/public/docs/_examples/style-guide/e2e-spec.ts
@@ -206,4 +206,5 @@ describe('Style Guide', function () {
     let button = element(by.tagName('sg-app > toh-hero-button > button'));
     expect(button.getText()).toBe('OK');
   });
+
 });
diff --git a/public/docs/_examples/style-guide/ts/10-01/app/app.component.ts b/public/docs/_examples/style-guide/ts/10-01/app/app.component.ts
@@ -0,0 +1,8 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'sg-app',
+  template: `<div>I am a page set to US English</div>`
+})
+export class AppComponent {
+}
diff --git a/public/docs/_examples/style-guide/ts/10-01/app/index.avoid.html b/public/docs/_examples/style-guide/ts/10-01/app/index.avoid.html
@@ -0,0 +1,14 @@
+<!-- avoid -->
+
+<!DOCTYPE html>
+<!-- #docregion page-lang-->
+<html>
+<!-- #enddocregion page-lang-->
+<head>
+    <meta charset="UTF-8">
+    <title>Title</title>
+</head>
+<body>
+<!--Some content-->
+</body>
+</html>
diff --git a/public/docs/_examples/style-guide/ts/10-01/app/index.html b/public/docs/_examples/style-guide/ts/10-01/app/index.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<!-- #docregion page-lang-->
+<html lang="en-US">
+<!-- #enddocregion page-lang -->
+<head>
+  <meta charset="UTF-8">
+  <title>Title</title>
+</head>
+<body>
+<!--Some content-->
+</body>
+</html>
diff --git a/public/docs/_examples/style-guide/ts/10-01/app/index.ts b/public/docs/_examples/style-guide/ts/10-01/app/index.ts
@@ -0,0 +1 @@
+export * from './app.component';
diff --git a/public/docs/_examples/style-guide/ts/10-02/app/app.component.avoid.css b/public/docs/_examples/style-guide/ts/10-02/app/app.component.avoid.css
@@ -0,0 +1,13 @@
+/* #docregion */
+/* avoid */
+
+:focus {
+  outline: 0;
+}
+
+/* or */
+
+:focus {
+  outline: none;
+}
+/* #enddocregion */
diff --git a/public/docs/_examples/style-guide/ts/10-02/app/app.component.html b/public/docs/_examples/style-guide/ts/10-02/app/app.component.html
@@ -0,0 +1,7 @@
+<label>Name:
+  <input [(ngModel)]="name">
+</label>
+<label>Surname:
+  <input [(ngModel)]="surname">
+</label>
+{{name}}{{surname}}
diff --git a/public/docs/_examples/style-guide/ts/10-02/app/app.component.ts b/public/docs/_examples/style-guide/ts/10-02/app/app.component.ts
@@ -0,0 +1,11 @@
+import { Component } from '@angular/core';
+
+@Component({
+  moduleId: module.id,
+  selector: 'sg-app',
+  templateUrl: 'app.component.html'
+})
+export class AppComponent {
+  name: string;
+  surname: string;
+}
diff --git a/public/docs/_examples/style-guide/ts/10-02/app/index.ts b/public/docs/_examples/style-guide/ts/10-02/app/index.ts
@@ -0,0 +1 @@
+export * from './app.component';
diff --git a/public/docs/_examples/style-guide/ts/app/app.routes.ts b/public/docs/_examples/style-guide/ts/app/app.routes.ts
@@ -26,6 +26,8 @@ import { AppComponent as S0701 } from '../07-01/app';
 import { AppComponent as S0703 } from '../07-03/app';
 import { AppComponent as S0704 } from '../07-04/app';
 import { AppComponent as S0901 } from '../09-01/app';
+import { AppComponent as S1001 } from '../10-01/app';
+import { AppComponent as S1002 } from '../10-02/app';
 
 const routes: RouterConfig = [
   { path: '01-01', component: S0101 },
@@ -54,6 +56,8 @@ const routes: RouterConfig = [
   { path: '07-03', component: S0703 },
   { path: '07-04', component: S0704 },
   { path: '09-01', component: S0901 },
+  { path: '10-01', component: S1001 },
+  { path: '10-02', component: S1002 },
 ];
 
 export const APP_ROUTER_PROVIDERS = [

diff --git a/public/docs/_examples/style-guide/ts/systemjs.custom.js b/public/docs/_examples/style-guide/ts/systemjs.custom.js
@@ -29,7 +29,9 @@
     '07-01', '07-01/app', '07-01/app/heroes', '07-01/app/heroes/shared',
     '07-03', '07-03/app', '07-03/app/heroes', '07-03/app/heroes/hero-list', '07-03/app/heroes/shared',
     '07-04', '07-04/app', '07-04/app/heroes', '07-04/app/heroes/shared',
-    '09-01', '09-01/app', '09-01/app/heroes', '09-01/app/heroes/shared', '09-01/app/heroes/shared/hero-button'
+    '09-01', '09-01/app', '09-01/app/heroes', '09-01/app/heroes/shared', '09-01/app/heroes/shared/hero-button',
+    '10-01', '10-01/app',
+    '10-02', '10-02/app'
   ];
 
   var packages = {};

diff --git a/public/docs/ts/latest/guide/style-guide.jade b/public/docs/ts/latest/guide/style-guide.jade
@@ -57,6 +57,7 @@ a(id='toc')
     1. [Data Services](#data-services)
     1. [Lifecycle Hooks](#lifecycle-hooks)
     1. [Routing](#routing)
+    1. [Accessibility](#accessibility)
     1. [Appendix](#appendix)
 
 .l-main-section
@@ -1870,6 +1871,276 @@ a(href="#toc") Back to top
 
 +makeExample('style-guide/ts/09-01/app/heroes/shared/hero-button/hero-button.component.ts', 'example', 'app/heroes/shared/hero-button/hero-button.component.ts')
 :marked
+
+a(href="#toc") Back to top
+
+.l-main-section
+:marked
+  ## Accessibility
+
+  Make your applications accessible to all forms of navigation, including keyboard-only navigation and assistive technologies.  
+
+  ### <a id="10-01"></a>Provide your page language
+  #### <a href="#01-01">Style 10-01</a>
+.s-rule.do
+  :marked
+    **Do** provide a `lang` attribute on your `html` tag.
+
+.s-why
+  :marked
+    **Why?** Assistive technologies, such as screen readers, need to know the language of the page.
+
+.s-why
+  :marked
+    **Why?** Language tools, such as spell checkers and translators adapt to the given language.
+
+.s-why.s-why-last
+  :marked
+    **Why?** This enables styling and font selection based on the page language.    
+
+:marked
+  Never omit the `lang` arrtibute:
+
++makeExample('style-guide/ts/10-01/app/index.avoid.html', 'page-lang', 'index.html')(avoid=1)
+
+:marked
+  Provide the ISO language code as well the country code (where appropriate).
+
++makeExample('style-guide/ts/10-01/app/index.html', 'page-lang', 'index.html')  
+
+.l-main-section
+:marked
+  ### <a id="10-02"></a>Never remove the browser focus outline 
+  #### <a href="#10-02">Style 10-02</a>
+.s-rule.do
+  :marked
+    **Do** keep the `outline` css property intact.
+
+.s-rule.consider
+  :marked
+    **Consider** only removing it if absolutely required and an alternate `:focus` style is provided.
+
+.s-rule.avoid
+  :marked
+    **Avoid** totaly removing the focus outline on your page.
+
+.s-why
+  :marked
+    **Why?** Sighted keyboard-only users fully rely on a visual indication of focus for navigation.
+
+.s-why.s-why-last
+  :marked
+    **Why?** Removing it renders a page immediately inaccessible.
+
+:marked
+  Never add one of the following styles without providing an alternate `:focus` outline style.
+
++makeExample('style-guide/ts/10-02/app/app.component.avoid.css', '', 'app.component.css')(avoid=1)    
+
+:marked
+.l-main-section
+:marked
+  ### <a id="10-03"></a>If you can use a native HTML element, then do so.
+  #### <a href="#10-03">Style 10-03</a>
+.s-rule.do
+  :marked
+    **Do** use native HTML elements where possible.
+
+.s-rule.avoid
+  :marked
+    **Avoid** recreating elements such as `input`, `button` and `a` with `div` and `span`.
+
+.s-why
+  :marked
+    **Why?** Native HTML elements contain a lot of built in functionality.
+
+.s-why
+  :marked
+    **Why?** Native HTML elements are instantly understood by all browsers and assistive technologies, such as screen readers.
+
+.s-why.s-why-last
+  :marked
+    **Why?** Native HTML elements automatically follow expected interaction patterns.   
+
+.l-main-section
+:marked
+  ### <a id="10-04"></a>Always support and test keyboard navigation.
+  #### <a href="#10-04">Style 10-04</a>
+.s-rule.do
+  :marked
+    **Do** unplug your mouse and test if al functionality on your page can be reached and activated with `TAB`, `SHIFT+TAB`, `ENTER`, `SPACE` and the arrow keys alone.
+
+.s-rule.avoid
+  :marked
+    **Avoid** any functional areas that cannot be reached this way.
+
+.s-why
+  :marked
+    **Why?** People who cannot use a mouse due to disability or injury navigate with the keyboard alone or other related technologies.
+
+.s-why.s-why-last
+  :marked
+    **Why?** People with visual disabilities requiring the assistance of screen readers also exclusively navigate with the keyboard alone or other related technologies.
+
+.l-main-section
+:marked
+  ### <a id="10-05"></a>Use `dl` to display the read-only state of interactive controls / form controls.
+  #### <a href="#10-05">Style 10-05</a>
+.s-rule.do
+  :marked
+    **Do** display read only key-value data as a definition list.
+
+.s-rule.avoid
+  :marked
+    **Avoid** using the `label` tag without a related interactive control / form control. 
+
+.s-rule.avoid
+  :marked
+    **Avoid** using only `div` and `span` to display related key-value data.    
+
+.s-why
+  :marked
+    **Why?** Assistive technologies, such as screen readers recognize the `dl` as containing related key-value pairs.
+
+.s-why.s-why-last
+  :marked
+    **Why?** Unrelated `label` tags are considered invalid HTML and not recognized by assistive technologies.    
+
+.l-main-section
+:marked
+  ### <a id="10-06"></a>Provide a label for all interactive controls / form controls and groups of controls.
+  #### <a href="#10-06">Style 10-06</a>
+.s-rule.do
+  :marked
+    **Do** associate a `label` element with every interactive control / form control.
+
+.s-rule.do
+  :marked
+    **Do** place groups of related interactive controls / form controls in a `fieldset` and label with `legend`.    
+
+.s-rule.avoid
+  :marked
+    **Avoid** unlabelled interactive controls / form controls. 
+
+.s-rule.avoid
+  :marked
+    **Avoid** any unassociated labels.    
+
+.s-why
+  :marked
+    **Why?** All users need to know the meaning of each interactive control / form control.
+
+.s-why
+  :marked
+    **Why?** Users with visual disabilities are also unable to assume the meaning based on visual position.
+
+.s-why.s-why-last
+  :marked
+    **Why?** Associated labels also become clickable making it easier to select interactive controls / form controls.    
+
+.l-main-section
+:marked
+  ### <a id="10-07"></a>Use links for navigation and buttons for activation.
+  #### <a href="#10-07">Style 10-07</a>
+.s-rule.do
+  :marked
+    **Do** use `a` tag links to navigate to other pages.
+
+.s-rule.do
+  :marked
+    **Do** use `buttons` to activate user actions requiring a response.    
+
+.s-rule.avoid
+  :marked
+    **Avoid** mixing these elements and functions. 
+
+.s-why
+  :marked
+    **Why?** Links are recognised by assistive technologies, expected to trigger a navigation and to be activated with `ENTER` alone.
+
+.s-why.s-why-last
+  :marked
+    **Why?** Buttons are recognised by assistive technologies, expected to trigger a user action and to be activated with either `ENTER` or `SPACE`.
+
+.l-main-section
+:marked
+  ### <a id="10-08"></a>Provide descriptive text for your HTML elements.
+  #### <a href="#10-08">Style 10-08</a>
+.s-rule.do
+  :marked
+    **Do** provide descriptive text for elements such as `buttons` pertaining to the meaning of the element.
+
+.s-rule.avoid
+  :marked
+    **Avoid** possible repetitive text for your elements as repetition causes confusion.
+
+.s-why
+  :marked
+    **Why?** Due to functionality such as `*ngFor` it is possible to create multiple instances of one HTML partial. A button stating *Save Rubberman* is then clearer than *Save Hero*.    
+
+.s-why.s-why-last
+  :marked
+    **Why?** This severly impacts users relying on screen readers where multiple occurances of elements with the same text can cause the page to become unusable.
+
+.l-main-section
+:marked
+  ### <a id="10-09"></a>Provide alternative text for all your images.
+  #### <a href="#10-09">Style 10-09</a>
+.s-rule.do
+  :marked
+    **Do** provide descriptive text for all images using the `alt` attribute.
+
+.s-rule.avoid
+  :marked
+    **Avoid** any images not described by text.
+
+.s-why.s-why-last
+  :marked
+    **Why?** Users with visual disabilites will be unable to discern the meaning of images without an alternative textual description.
+
+.l-main-section
+:marked
+  ### <a id="10-10"></a>Provide good textual color contrast
+  #### <a href="#10-10">Style 10-10</a>
+.s-rule.do
+  :marked
+    **Do** provide a color contrast ratio of at least `4.5:1` between the text color and the text background color for small text .
+
+.s-rule.do
+  :marked
+    **Do** provide a color contrast ratio of at least `3:1` between the text color and the text background color for large text.   
+
+.s-rule.do
+  :marked
+    **Do** use one of many freely available color contrast test tools to achieve this.      
+
+.s-rule.avoid
+  :marked
+    **Avoid** providing textual contrast below these levels.
+
+.s-why
+  :marked
+    **Why?** Users with limited vision, who are not reliant on screen readers, may be unable to read text not conforming to these contrast ratios.
+
+.s-why.s-why-last
+  :marked
+    **Why?** These ratios provide an enhanced reading experience for all users in a larger range of ambient light conditions.  
+
+.l-main-section
+:marked
+  ### <a id="10-11"></a>Avoid full reliance on color alone to convey meaning.
+  #### <a href="#10-11">Style 10-11</a>
+.s-rule.do
+  :marked
+    **Do** provide readable text to convey all application-critical information.
+
+.s-rule.avoid
+  :marked
+    **Avoid** only using color to convey application-critical information, i.e. *"Click on the green button"*.
+
+.s-why.s-why-last
+  :marked
+    **Why?** Users with visual disabilites will be unable to recognize this important application information and therefore be unable to use it.
 
 a(href="#toc") Back to top
-Original file line number
+Diff line change
@@ Expand Up / @@ -206,4 +206,5 @@ describe('Style Guide', function () { @@
         let button = element(by.tagName('sg-app > toh-hero-button > button'));
         expect(button.getText()).toBe('OK');
       });
     });