{"action":"created","comment":{"url":"https://api.github.com/repos/edx/edx-platform/pulls/comments/23801593","id":23801593,"diff_hunk":"@@ -0,0 +1,547 @@\n+.. _Accessibility Guideline for Developers:\n+\n+#######################\n+edX Accessibility Guide\n+#######################\n+\n+EdX measures and evaluates accessibility using the World Wide Web Consortium's\n+`Web Content Accessibility Guidelines (WCAG) 2.0 <http://www.w3.org/TR/WCAG/>`_\n+(Dec. 11, 2008). All features that you merge into edX repositories are expected\n+to `conform <http://www.w3.org/TR/WCAG20/#conformance>`_ to `Level AA\n+<http://www.w3.org/TR/WCAG20/#cc1>`_ of this specification. This guide is\n+intended to extend the guidance available in WCAG 2.0, with a focus on features\n+frequently found in the Open edX platform as well as in Learning and Content\n+Management Systems in general.\n+\n+************\n+Introduction\n+************\n+\n+The core mission of edX is to expand access to education for everyone. We expect\n+any user interfaces that are developed for the Open edX platform to be usable by\n+everyone, regardless of any physical limitations that they might have. The Open\n+edX platform is used every day by people who might not be able to see or hear,\n+or who might not be able to use traditional modes of computer interaction such\n+as the mouse or keyboard. \n+\n+Understanding a few core concepts about how people with disabilities use the web\n+and web applications should give you more context for applying the guidance in\n+this document.\n+\n+* People without vision, as well as those with neurological conditions that\n+  prevent precise hand-eye coordination, cannot use a mouse.\n+\n+* People with mobility impairments might use custom keyboards or keyboard\n+  emulators.\n+\n+* Some people rely on speech to interact with web applications and need to be\n+  able to address interactive elements.\n+\n+* People who cannot hear or hear well require visible text captions, or an\n+  equivalent visual cue, for any audible content.\n+\n+* Many people with disabilities use \"`assistive technologies\n+  <http://www.w3.org/TR/WCAG20/#atdef>`_\" (such as screen readers) to interact\n+  with their computers, web browsers, and web applications. Users might customize\n+  their operating system, browser or web page display properties to make web\n+  applications easier for them to use. For example, they might increase the font\n+  size in their displays, reverse or increase contrast, or remove images.\n+\n+* To allow assistive technologies to provide the maximum information to users,\n+  anything in a user interface that is conveyed visually (such as the element\n+  with focus, an element's role, its current state, and other properties) must\n+  also be conveyed programmatically. This information is often included when you\n+  use native HTML5 elements.\n+\n+Keep these core concepts in mind when you develop user interfaces, so that they\n+can truly be used by everyone. More information is available from the W3C's Web\n+Accessibility Initiative's `How People with Disabilities Use the Web: Overview\n+<http://www.w3.org/WAI/intro/people-use-web/Overview.html>`_.\n+\n+\n+****************************\n+Accessibility Best Practices\n+****************************\n+\n+The following sections cover some best practices and tips to keep in mind as you\n+develop user interfaces that are WCAG 2.0 compliant.\n+\n+* :ref:`Use semantic markup`\n+* :ref:`Avoid using CSS to add content`\n+* :ref:`Include title attributes for all iframe elements`\n+* :ref:`Make sure form elements have labels`\n+* :ref:`Include labels for links and interactive controls`\n+* :ref:`Use WAI ARIA to create accessible widgets`\n+* :ref:`Manage focus for popups`\n+* :ref:`Inform users when content changes dynamically`\n+* :ref:`Hide or expose content to targeted audiences`\n+* :ref:`Make images accessible`\n+* :ref:`Choose colors that meet minimum contrast ratios`\n+* :ref:`Test your code for accessibility`\n+\n+\n+.. _Use semantic markup:\n+\n+*******************\n+Use semantic markup\n+*******************\n+\n+The role, state, and associated properties of an element are exposed to users of\n+assistive technologies either directly through the DOM or through the\n+Accessibility API. If you use elements for purposes other than their intended\n+purposes, you can \"break\" features that are designed to make web applications\n+easier to use, resulting in confusion when expected behaviors are not available.\n+For example, the role, state, or associated properties of an element might be\n+incorrectly reported when you use an element in a way that it was not designed\n+to be used, causing confusion for users who rely on assistive technologies.\n+\n+If the semantics and behavior you need already exist in a native HTML5 element,\n+you should use that element. Do not use an element because of its default style\n+or because it provides a convenient styling hook. Here are some common examples.\n+\n+-------\n+Buttons\n+-------\n+\n+If you want a button, use the ``<button>`` element. Do not use a ``<div>`` that\n+looks and behaves like a button.\n+\n+----------\n+Checkboxes\n+----------\n+\n+If you want a checkbox, use the ``<input type=checkbox>`` element. Do not try to\n+recreate states and properties that are included with the native element, such\n+as focus or state. If you attempt to do so, more than likely you will not fully\n+replicate all of them. Native checkbox elements include a toggle for checked\n+state upon ``space`` or ``enter`` keypresses, exposing its label and\n+\"`checkedness <http://www.w3.org/TR/html5/forms.html #concept-fe-checked>`_\" to\n+the Accessibility API.\n+\n+--------\n+Headings\n+--------\n+\n+Use the appropriate levels of headings (``<h1>`` - ``h6>``) to denote a logical\n+hierarchical order of content. Do not use headings as stylistic markup (for\n+their physical size or appearance).\n+\n+-----\n+Lists\n+-----\n+\n+Use ordered lists (``<ol>``) only when you are marking up a collection of\n+related items whose order in the list if important. Use unordered lists\n+(``<ul>``) only when you are marking up a collection of related items. Screen\n+readers provide extra feedback and functionality for lists and other elements\n+with semantic importance. It can be confusing or cumbersome when this feedback is\n+inaccurately reported.\n+\n+\n+.. _Avoid using CSS to add content:\n+\n+******************************\n+Avoid using CSS to add content\n+******************************\n+\n+CSS-generated content can cause many accessibility problems. Since many screen\n+readers interact with the DOM, they are not exposed to content generated by CSS,\n+which does not live in the DOM. There is currently no mechanism for adding\n+alternative content for images added using CSS (either background images or\n+pseudo elements).\n+\n+Many developers think that providing screen reader-only text can be used to\n+solve this. However, images added using this technique will not be rendered to\n+users who have high contrast mode enabled on their operating systems. These\n+users are likely not using screen readers, so they cannot access the visible\n+icon, or the screen reader text.\n+\n+Content injected into the DOM using JavaScript is more accessible than content added using CSS.\n+\n+When adding images that represent important navigational or information\n+elements, use ``<img>`` elements with appropriate ``alt`` attributes. For more\n+information about making images accessible, see :ref:`Make images accessible`.\n+   \n+\n+.. _Include title attributes for all iframe elements:\n+\n+***********************************************************************\n+Include a descriptive ``title`` attribute for all ``<iframe>`` elements\n+***********************************************************************\n+\n+Use the ``title`` attribute to provide a description of the embedded content to\n+help users decide whether or not they would like to interact with this content.\n+It is possible that ``<iframe>`` titles are presented out of context (such as in\n+a list within a dialog box), so choose title text that will make sense when it\n+is exposed out of context.\n+\n+\n+.. _Include labels for links and interactive controls:\n+\n+***********************************************************************\n+Include labels for all links and interactive controls that make sense out of context\n+************************************************************************\n+\n+Label text for all links and interactive controls should make sense out of\n+context. Screen reader users have the option of listing and navigating links and\n+form controls out of the context of the page. When a page contains vague and\n+non-unique text such as **Click here** or **More...**, the purpose of these\n+links is not clear without the context of surrounding text.\n+\n+\n+.. _Make sure form elements have labels:\n+\n+**************************************\n+Make sure form elements have labels\n+**************************************\n+\n+All form elements must have labels, either using the `label element\n+<http://www.w3.org/TR/html5/forms.html#the-label-element>`_ or the `aria-label\n+<http://www.w3.org/TR/wai-aria/states_and_properties#aria-label>`_ or `aria-\n+labelledby <http://www.w3.org/TR/wai-aria/states_and_properties#aria-\n+labelledby>`_ attributes.\n+\n+Sighted users have the benefit of visual context. It is usually quite obvious to\n+them what the purpose is of a given form field, based on physical proximity of\n+descriptive text or other visual cues. However, to a user with a vision\n+impairment, who does not have the benefit of visual context, these relationships\n+are not obvious. Users who rely on speech to interact with their computers also\n+need a label for addressing form elements. If you correct use the ``<label>``\n+element, text is programmatically associated with a given form element, and can\n+then be read to the user upon focus, or used to address the form element.","path":"docs/en_us/developers/source/accessibility.rst","position":211,"original_position":211,"commit_id":"96e268233d93fd9bcad852f32f2f5ccc33495951","original_commit_id":"96e268233d93fd9bcad852f32f2f5ccc33495951","user":{"login":"cptvitamin","id":444368,"avatar_url":"https://avatars.githubusercontent.com/u/444368?v=3","gravatar_id":"","url":"https://api.github.com/users/cptvitamin","html_url":"https://github.com/cptvitamin","followers_url":"https://api.github.com/users/cptvitamin/followers","following_url":"https://api.github.com/users/cptvitamin/following{/other_user}","gists_url":"https://api.github.com/users/cptvitamin/gists{/gist_id}","starred_url":"https://api.github.com/users/cptvitamin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cptvitamin/subscriptions","organizations_url":"https://api.github.com/users/cptvitamin/orgs","repos_url":"https://api.github.com/users/cptvitamin/repos","events_url":"https://api.github.com/users/cptvitamin/events{/privacy}","received_events_url":"https://api.github.com/users/cptvitamin/received_events","type":"User","site_admin":false},"body":"\"...or used to address the form element ^using speech input.\"","created_at":"2015-01-29T20:53:43Z","updated_at":"2015-01-29T20:53:43Z","html_url":"https://github.com/edx/edx-platform/pull/6806#discussion_r23801593","pull_request_url":"https://api.github.com/repos/edx/edx-platform/pulls/6806","_links":{"self":{"href":"https://api.github.com/repos/edx/edx-platform/pulls/comments/23801593"},"html":{"href":"https://github.com/edx/edx-platform/pull/6806#discussion_r23801593"},"pull_request":{"href":"https://api.github.com/repos/edx/edx-platform/pulls/6806"}}},"pull_request":{"url":"https://api.github.com/repos/edx/edx-platform/pulls/6806","id":28242583,"html_url":"https://github.com/edx/edx-platform/pull/6806","diff_url":"https://github.com/edx/edx-platform/pull/6806.diff","patch_url":"https://github.com/edx/edx-platform/pull/6806.patch","issue_url":"https://api.github.com/repos/edx/edx-platform/issues/6806","number":6806,"state":"open","locked":false,"title":"WIP: Accessibility document edit","user":{"login":"catong","id":9041399,"avatar_url":"https://avatars.githubusercontent.com/u/9041399?v=3","gravatar_id":"","url":"https://api.github.com/users/catong","html_url":"https://github.com/catong","followers_url":"https://api.github.com/users/catong/followers","following_url":"https://api.github.com/users/catong/following{/other_user}","gists_url":"https://api.github.com/users/catong/gists{/gist_id}","starred_url":"https://api.github.com/users/catong/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/catong/subscriptions","organizations_url":"https://api.github.com/users/catong/orgs","repos_url":"https://api.github.com/users/catong/repos","events_url":"https://api.github.com/users/catong/events{/privacy}","received_events_url":"https://api.github.com/users/catong/received_events","type":"User","site_admin":false},"body":"","created_at":"2015-01-29T00:11:46Z","updated_at":"2015-01-29T20:53:43Z","closed_at":null,"merged_at":null,"merge_commit_sha":"3d0f03dadd3ac3877b330776f40a1134ac8770bc","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/edx/edx-platform/pulls/6806/commits","review_comments_url":"https://api.github.com/repos/edx/edx-platform/pulls/6806/comments","review_comment_url":"https://api.github.com/repos/edx/edx-platform/pulls/comments/{number}","comments_url":"https://api.github.com/repos/edx/edx-platform/issues/6806/comments","statuses_url":"https://api.github.com/repos/edx/edx-platform/statuses/96e268233d93fd9bcad852f32f2f5ccc33495951","head":{"label":"edx:docs/carol/accessibilitydoc","ref":"docs/carol/accessibilitydoc","sha":"96e268233d93fd9bcad852f32f2f5ccc33495951","user":{"login":"edx","id":3179841,"avatar_url":"https://avatars.githubusercontent.com/u/3179841?v=3","gravatar_id":"","url":"https://api.github.com/users/edx","html_url":"https://github.com/edx","followers_url":"https://api.github.com/users/edx/followers","following_url":"https://api.github.com/users/edx/following{/other_user}","gists_url":"https://api.github.com/users/edx/gists{/gist_id}","starred_url":"https://api.github.com/users/edx/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/edx/subscriptions","organizations_url":"https://api.github.com/users/edx/orgs","repos_url":"https://api.github.com/users/edx/repos","events_url":"https://api.github.com/users/edx/events{/privacy}","received_events_url":"https://api.github.com/users/edx/received_events","type":"Organization","site_admin":false},"repo":{"id":10391073,"name":"edx-platform","full_name":"edx/edx-platform","owner":{"login":"edx","id":3179841,"avatar_url":"https://avatars.githubusercontent.com/u/3179841?v=3","gravatar_id":"","url":"https://api.github.com/users/edx","html_url":"https://github.com/edx","followers_url":"https://api.github.com/users/edx/followers","following_url":"https://api.github.com/users/edx/following{/other_user}","gists_url":"https://api.github.com/users/edx/gists{/gist_id}","starred_url":"https://api.github.com/users/edx/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/edx/subscriptions","organizations_url":"https://api.github.com/users/edx/orgs","repos_url":"https://api.github.com/users/edx/repos","events_url":"https://api.github.com/users/edx/events{/privacy}","received_events_url":"https://api.github.com/users/edx/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/edx/edx-platform","description":"Open edX, the edX platform that powers http://edx.org","fork":false,"url":"https://api.github.com/repos/edx/edx-platform","forks_url":"https://api.github.com/repos/edx/edx-platform/forks","keys_url":"https://api.github.com/repos/edx/edx-platform/keys{/key_id}","collaborators_url":"https://api.github.com/repos/edx/edx-platform/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/edx/edx-platform/teams","hooks_url":"https://api.github.com/repos/edx/edx-platform/hooks","issue_events_url":"https://api.github.com/repos/edx/edx-platform/issues/events{/number}","events_url":"https://api.github.com/repos/edx/edx-platform/events","assignees_url":"https://api.github.com/repos/edx/edx-platform/assignees{/user}","branches_url":"https://api.github.com/repos/edx/edx-platform/branches{/branch}","tags_url":"https://api.github.com/repos/edx/edx-platform/tags","blobs_url":"https://api.github.com/repos/edx/edx-platform/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/edx/edx-platform/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/edx/edx-platform/git/refs{/sha}","trees_url":"https://api.github.com/repos/edx/edx-platform/git/trees{/sha}","statuses_url":"https://api.github.com/repos/edx/edx-platform/statuses/{sha}","languages_url":"https://api.github.com/repos/edx/edx-platform/languages","stargazers_url":"https://api.github.com/repos/edx/edx-platform/stargazers","contributors_url":"https://api.github.com/repos/edx/edx-platform/contributors","subscribers_url":"https://api.github.com/repos/edx/edx-platform/subscribers","subscription_url":"https://api.github.com/repos/edx/edx-platform/subscription","commits_url":"https://api.github.com/repos/edx/edx-platform/commits{/sha}","git_commits_url":"https://api.github.com/repos/edx/edx-platform/git/commits{/sha}","comments_url":"https://api.github.com/repos/edx/edx-platform/comments{/number}","issue_comment_url":"https://api.github.com/repos/edx/edx-platform/issues/comments/{number}","contents_url":"https://api.github.com/repos/edx/edx-platform/contents/{+path}","compare_url":"https://api.github.com/repos/edx/edx-platform/compare/{base}...{head}","merges_url":"https://api.github.com/repos/edx/edx-platform/merges","archive_url":"https://api.github.com/repos/edx/edx-platform/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/edx/edx-platform/downloads","issues_url":"https://api.github.com/repos/edx/edx-platform/issues{/number}","pulls_url":"https://api.github.com/repos/edx/edx-platform/pulls{/number}","milestones_url":"https://api.github.com/repos/edx/edx-platform/milestones{/number}","notifications_url":"https://api.github.com/repos/edx/edx-platform/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/edx/edx-platform/labels{/name}","releases_url":"https://api.github.com/repos/edx/edx-platform/releases{/id}","created_at":"2013-05-30T20:20:38Z","updated_at":"2015-01-29T20:45:32Z","pushed_at":"2015-01-29T20:30:19Z","git_url":"git://github.com/edx/edx-platform.git","ssh_url":"git@github.com:edx/edx-platform.git","clone_url":"https://github.com/edx/edx-platform.git","svn_url":"https://github.com/edx/edx-platform","homepage":"http://openedx.org/","size":1582008,"stargazers_count":1708,"watchers_count":1708,"language":"Python","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":978,"mirror_url":null,"open_issues_count":144,"forks":978,"open_issues":144,"watchers":1708,"default_branch":"master"}},"base":{"label":"edx:master","ref":"master","sha":"116dba39a8ac2c01e6dcbdbb048b58d26a79e2f4","user":{"login":"edx","id":3179841,"avatar_url":"https://avatars.githubusercontent.com/u/3179841?v=3","gravatar_id":"","url":"https://api.github.com/users/edx","html_url":"https://github.com/edx","followers_url":"https://api.github.com/users/edx/followers","following_url":"https://api.github.com/users/edx/following{/other_user}","gists_url":"https://api.github.com/users/edx/gists{/gist_id}","starred_url":"https://api.github.com/users/edx/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/edx/subscriptions","organizations_url":"https://api.github.com/users/edx/orgs","repos_url":"https://api.github.com/users/edx/repos","events_url":"https://api.github.com/users/edx/events{/privacy}","received_events_url":"https://api.github.com/users/edx/received_events","type":"Organization","site_admin":false},"repo":{"id":10391073,"name":"edx-platform","full_name":"edx/edx-platform","owner":{"login":"edx","id":3179841,"avatar_url":"https://avatars.githubusercontent.com/u/3179841?v=3","gravatar_id":"","url":"https://api.github.com/users/edx","html_url":"https://github.com/edx","followers_url":"https://api.github.com/users/edx/followers","following_url":"https://api.github.com/users/edx/following{/other_user}","gists_url":"https://api.github.com/users/edx/gists{/gist_id}","starred_url":"https://api.github.com/users/edx/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/edx/subscriptions","organizations_url":"https://api.github.com/users/edx/orgs","repos_url":"https://api.github.com/users/edx/repos","events_url":"https://api.github.com/users/edx/events{/privacy}","received_events_url":"https://api.github.com/users/edx/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/edx/edx-platform","description":"Open edX, the edX platform that powers http://edx.org","fork":false,"url":"https://api.github.com/repos/edx/edx-platform","forks_url":"https://api.github.com/repos/edx/edx-platform/forks","keys_url":"https://api.github.com/repos/edx/edx-platform/keys{/key_id}","collaborators_url":"https://api.github.com/repos/edx/edx-platform/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/edx/edx-platform/teams","hooks_url":"https://api.github.com/repos/edx/edx-platform/hooks","issue_events_url":"https://api.github.com/repos/edx/edx-platform/issues/events{/number}","events_url":"https://api.github.com/repos/edx/edx-platform/events","assignees_url":"https://api.github.com/repos/edx/edx-platform/assignees{/user}","branches_url":"https://api.github.com/repos/edx/edx-platform/branches{/branch}","tags_url":"https://api.github.com/repos/edx/edx-platform/tags","blobs_url":"https://api.github.com/repos/edx/edx-platform/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/edx/edx-platform/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/edx/edx-platform/git/refs{/sha}","trees_url":"https://api.github.com/repos/edx/edx-platform/git/trees{/sha}","statuses_url":"https://api.github.com/repos/edx/edx-platform/statuses/{sha}","languages_url":"https://api.github.com/repos/edx/edx-platform/languages","stargazers_url":"https://api.github.com/repos/edx/edx-platform/stargazers","contributors_url":"https://api.github.com/repos/edx/edx-platform/contributors","subscribers_url":"https://api.github.com/repos/edx/edx-platform/subscribers","subscription_url":"https://api.github.com/repos/edx/edx-platform/subscription","commits_url":"https://api.github.com/repos/edx/edx-platform/commits{/sha}","git_commits_url":"https://api.github.com/repos/edx/edx-platform/git/commits{/sha}","comments_url":"https://api.github.com/repos/edx/edx-platform/comments{/number}","issue_comment_url":"https://api.github.com/repos/edx/edx-platform/issues/comments/{number}","contents_url":"https://api.github.com/repos/edx/edx-platform/contents/{+path}","compare_url":"https://api.github.com/repos/edx/edx-platform/compare/{base}...{head}","merges_url":"https://api.github.com/repos/edx/edx-platform/merges","archive_url":"https://api.github.com/repos/edx/edx-platform/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/edx/edx-platform/downloads","issues_url":"https://api.github.com/repos/edx/edx-platform/issues{/number}","pulls_url":"https://api.github.com/repos/edx/edx-platform/pulls{/number}","milestones_url":"https://api.github.com/repos/edx/edx-platform/milestones{/number}","notifications_url":"https://api.github.com/repos/edx/edx-platform/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/edx/edx-platform/labels{/name}","releases_url":"https://api.github.com/repos/edx/edx-platform/releases{/id}","created_at":"2013-05-30T20:20:38Z","updated_at":"2015-01-29T20:45:32Z","pushed_at":"2015-01-29T20:30:19Z","git_url":"git://github.com/edx/edx-platform.git","ssh_url":"git@github.com:edx/edx-platform.git","clone_url":"https://github.com/edx/edx-platform.git","svn_url":"https://github.com/edx/edx-platform","homepage":"http://openedx.org/","size":1582008,"stargazers_count":1708,"watchers_count":1708,"language":"Python","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":978,"mirror_url":null,"open_issues_count":144,"forks":978,"open_issues":144,"watchers":1708,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/edx/edx-platform/pulls/6806"},"html":{"href":"https://github.com/edx/edx-platform/pull/6806"},"issue":{"href":"https://api.github.com/repos/edx/edx-platform/issues/6806"},"comments":{"href":"https://api.github.com/repos/edx/edx-platform/issues/6806/comments"},"review_comments":{"href":"https://api.github.com/repos/edx/edx-platform/pulls/6806/comments"},"review_comment":{"href":"https://api.github.com/repos/edx/edx-platform/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/edx/edx-platform/pulls/6806/commits"},"statuses":{"href":"https://api.github.com/repos/edx/edx-platform/statuses/96e268233d93fd9bcad852f32f2f5ccc33495951"}}}}