From 51a166aed7ed2cb044db4274b94442573b012440 Mon Sep 17 00:00:00 2001 From: AlmeroSteyn Date: Fri, 8 Jul 2016 14:43:52 +0200 Subject: [PATCH] style-guide(add-a11y): Add accessibility quick wins --- public/docs/_examples/style-guide/e2e-spec.ts | 1 + .../style-guide/ts/10-01/app/app.component.ts | 8 + .../style-guide/ts/10-01/app/index.avoid.html | 14 + .../style-guide/ts/10-01/app/index.html | 12 + .../style-guide/ts/10-01/app/index.ts | 1 + .../ts/10-02/app/app.component.avoid.css | 13 + .../ts/10-02/app/app.component.html | 7 + .../style-guide/ts/10-02/app/app.component.ts | 11 + .../style-guide/ts/10-02/app/index.ts | 1 + .../ts/10-03/app/app.component.avoid.html | 4 + .../ts/10-03/app/app.component.css | 11 + .../ts/10-03/app/app.component.html | 3 + .../style-guide/ts/10-03/app/app.component.ts | 15 + .../style-guide/ts/10-03/app/index.ts | 1 + .../style-guide/ts/app/app.routes.ts | 6 + .../style-guide/ts/systemjs.custom.js | 5 +- public/docs/ts/latest/guide/style-guide.jade | 275 ++++++++++++++++++ 17 files changed, 387 insertions(+), 1 deletion(-) create mode 100644 public/docs/_examples/style-guide/ts/10-01/app/app.component.ts create mode 100644 public/docs/_examples/style-guide/ts/10-01/app/index.avoid.html create mode 100644 public/docs/_examples/style-guide/ts/10-01/app/index.html create mode 100644 public/docs/_examples/style-guide/ts/10-01/app/index.ts create mode 100644 public/docs/_examples/style-guide/ts/10-02/app/app.component.avoid.css create mode 100644 public/docs/_examples/style-guide/ts/10-02/app/app.component.html create mode 100644 public/docs/_examples/style-guide/ts/10-02/app/app.component.ts create mode 100644 public/docs/_examples/style-guide/ts/10-02/app/index.ts create mode 100644 public/docs/_examples/style-guide/ts/10-03/app/app.component.avoid.html create mode 100644 public/docs/_examples/style-guide/ts/10-03/app/app.component.css create mode 100644 public/docs/_examples/style-guide/ts/10-03/app/app.component.html create mode 100644 public/docs/_examples/style-guide/ts/10-03/app/app.component.ts create mode 100644 public/docs/_examples/style-guide/ts/10-03/app/index.ts diff --git a/public/docs/_examples/style-guide/e2e-spec.ts b/public/docs/_examples/style-guide/e2e-spec.ts index c0fedf822e..5357da10bd 100644 --- 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 new file mode 100644 index 0000000000..3aea82a610 --- /dev/null +++ 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: `
I am a page set to US English
` +}) +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 new file mode 100644 index 0000000000..fb5755307d --- /dev/null +++ b/public/docs/_examples/style-guide/ts/10-01/app/index.avoid.html @@ -0,0 +1,14 @@ + + + + + + + + + Title + + + + + 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 new file mode 100644 index 0000000000..be3562da68 --- /dev/null +++ b/public/docs/_examples/style-guide/ts/10-01/app/index.html @@ -0,0 +1,12 @@ + + + + + + + Title + + + + + 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 new file mode 100644 index 0000000000..df2f2075c8 --- /dev/null +++ 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 new file mode 100644 index 0000000000..44e200ba76 --- /dev/null +++ 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 new file mode 100644 index 0000000000..b231b9aa5b --- /dev/null +++ b/public/docs/_examples/style-guide/ts/10-02/app/app.component.html @@ -0,0 +1,7 @@ + + +{{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 new file mode 100644 index 0000000000..9f97daf2e7 --- /dev/null +++ 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 new file mode 100644 index 0000000000..df2f2075c8 --- /dev/null +++ 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/10-03/app/app.component.avoid.html b/public/docs/_examples/style-guide/ts/10-03/app/app.component.avoid.html new file mode 100644 index 0000000000..b82383a481 --- /dev/null +++ b/public/docs/_examples/style-guide/ts/10-03/app/app.component.avoid.html @@ -0,0 +1,4 @@ + + +
Press me
+ diff --git a/public/docs/_examples/style-guide/ts/10-03/app/app.component.css b/public/docs/_examples/style-guide/ts/10-03/app/app.component.css new file mode 100644 index 0000000000..afa3ac490e --- /dev/null +++ b/public/docs/_examples/style-guide/ts/10-03/app/app.component.css @@ -0,0 +1,11 @@ +.button { + font-family: Arial; + background-color: #eee; + border: none; + padding: 5px 10px; + border-radius: 4px; + margin-bottom: 5px; + width: 75px; + cursor: pointer; + cursor: hand; +} diff --git a/public/docs/_examples/style-guide/ts/10-03/app/app.component.html b/public/docs/_examples/style-guide/ts/10-03/app/app.component.html new file mode 100644 index 0000000000..2fcbec9a8a --- /dev/null +++ b/public/docs/_examples/style-guide/ts/10-03/app/app.component.html @@ -0,0 +1,3 @@ + + + diff --git a/public/docs/_examples/style-guide/ts/10-03/app/app.component.ts b/public/docs/_examples/style-guide/ts/10-03/app/app.component.ts new file mode 100644 index 0000000000..86de507228 --- /dev/null +++ b/public/docs/_examples/style-guide/ts/10-03/app/app.component.ts @@ -0,0 +1,15 @@ +import { Component } from '@angular/core'; + +@Component({ + moduleId: module.id, + selector: 'sg-app', + templateUrl: 'app.component.html', + styleUrls: ['app.component.css'] +}) +export class AppComponent { + + saveData() { + alert('Button pressed.'); + } + +} diff --git a/public/docs/_examples/style-guide/ts/10-03/app/index.ts b/public/docs/_examples/style-guide/ts/10-03/app/index.ts new file mode 100644 index 0000000000..df2f2075c8 --- /dev/null +++ b/public/docs/_examples/style-guide/ts/10-03/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 index 9254169331..e03787ad53 100644 --- 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,9 @@ 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'; +import { AppComponent as S1003 } from '../10-03/app'; const routes: RouterConfig = [ { path: '01-01', component: S0101 }, @@ -54,6 +57,9 @@ 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 }, + { path: '10-03', component: S1003 }, ]; 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 index 10f13fe801..d927a7f507 100644 --- a/public/docs/_examples/style-guide/ts/systemjs.custom.js +++ b/public/docs/_examples/style-guide/ts/systemjs.custom.js @@ -29,7 +29,10 @@ '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', + '10-03', '10-03/app' ]; var packages = {}; diff --git a/public/docs/ts/latest/guide/style-guide.jade b/public/docs/ts/latest/guide/style-guide.jade index e24feff721..8dab91ba03 100644 --- 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,280 @@ 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. + + ### Provide your page language + #### Style 10-01 +.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 ++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 + ### Never remove the browser focus outline + #### Style 10-02 +.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 + ### If you can use a native HTML element, then do so. + #### Style 10-03 +.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, i.e. accepting keyboard focus and exposing the correct interaction events. + +.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. + +:marked ++makeExample('style-guide/ts/10-03/app/app.component.avoid.html', '', 'app.component.html')(avoid=1) + +:marked ++makeExample('style-guide/ts/10-03/app/app.component.html', '', 'app.component.html') + +.l-main-section +:marked + ### Always support and test keyboard navigation. + #### Style 10-04 +.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 + ### Use `dl` to display the read-only state of interactive controls / form controls. + #### Style 10-05 +.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 + ### Provide a label for all interactive controls / form controls and groups of controls. + #### Style 10-06 +.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 + ### Use links for navigation and buttons for activation. + #### Style 10-07 +.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 + ### Provide descriptive text for your HTML elements. + #### Style 10-08 +.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 + ### Provide alternative text for all your images. + #### Style 10-09 +.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 + ### Provide good textual color contrast + #### Style 10-10 +.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 + ### Avoid full reliance on color alone to convey meaning. + #### Style 10-11 +.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