From ba2600319512cb49354ba147355b9566c72f4ea9 Mon Sep 17 00:00:00 2001 From: Terrence Kevin Oleary Date: Mon, 14 Dec 2020 16:11:05 -0600 Subject: [PATCH] Core/dp-20670-accessibility-docs-updates (#1303) * Edited down accessibility resources, added to Accesibility main * Added link to resources * Updated linkto * Updated resources to just out links * Edited down accessibility resources, added to Accesibility main * Added link to resources * Updated linkto * Updated resources to just out links * More updates to text -fixed broken links -added some new descriptions --- packages/core/.storybook/preview.js | 5 +- packages/core/stories/meta.json | 8 +- .../principles/Accessibility.stories.mdx | 777 ++---------------- .../stories/principles/Resources.stories.mdx | 66 ++ packages/core/stories/styles/index.scss | 9 + 5 files changed, 148 insertions(+), 717 deletions(-) create mode 100644 packages/core/stories/principles/Resources.stories.mdx diff --git a/packages/core/.storybook/preview.js b/packages/core/.storybook/preview.js index d7c1189e31..8eea9ce4f9 100644 --- a/packages/core/.storybook/preview.js +++ b/packages/core/.storybook/preview.js @@ -7,11 +7,12 @@ export const parameters = { 'Overview', [ 'Introduction', 'Get Started', - 'Examples' + 'Examples' ], 'Principles', [ 'Brand Pillars', - 'Accessibility' + 'Accessibility', + 'Resources' ], 'Foundation', [ 'Logo', diff --git a/packages/core/stories/meta.json b/packages/core/stories/meta.json index 85abe7bedb..060ffde7ea 100644 --- a/packages/core/stories/meta.json +++ b/packages/core/stories/meta.json @@ -15,14 +15,14 @@ "kind": "Principles", "story": "Brand Pillars" }, - "DesignGuidelines": { - "kind": "Principles", - "story": "Guidelines" - }, "Accessibility": { "kind": "Principles", "story": "Accessibility" }, + "Resources": { + "kind": "Principles", + "story": "Resources" + }, "Colors": { "kind": "Foundation", "story": "Color" diff --git a/packages/core/stories/principles/Accessibility.stories.mdx b/packages/core/stories/principles/Accessibility.stories.mdx index 1257c09fe6..7491bdfa09 100644 --- a/packages/core/stories/principles/Accessibility.stories.mdx +++ b/packages/core/stories/principles/Accessibility.stories.mdx @@ -1,749 +1,104 @@ import { Meta } from '@storybook/addon-docs/blocks'; +import { linkTo } from '@storybook/addon-links'; +import { Button } from '@massds/mayflower-react'; import generateTitle from '../util/generateTitle'; -# Accessibility -## Web accessibility and the Commonwealth of Massachusetts +# Web accessibility and the Commonwealth -All government digital products are required to conform to the [Web Content Accessibility Guidelines (WCAG) 2.0 and 2.1](https://www.w3.org/WAI/standards-guidelines/wcag/) and the [Americans with Disabilities Act (ADA)](https://www.ada.gov/). +
-Mayflower is a design system for the the Commonwealth of Massachusetts -. It is designed and developed to meet such web accessibility guidelines. If you follow this system's samples, your website would be accessible by broad range of users. +The [Americans with Disabilities Act (ADA)](https://www.ada.gov/) mandates that government digital products meet [Web Content Accessibility Guidelines (WCAG) 2.0 and 2.1](https://www.w3.org/WAI/standards-guidelines/wcag/). Mayflower was designed and developed to meet that standard and in most cases simply using the Mayflower components should make your website or app accessible to broad range of users. -As technology evolves, some methods to meet the guidelines could get outdated. We will update outdated ones though our periodical accessibility testing. Such updates are addressed at [TBD: CHANGELOG, RELEASE NOTES OR ACCESSIBILITY TEST REPORTS????]. +There will, however be cases where Mayflower out-of-the-box will not cover all accessibility issues, we've outlined those below so you can understand what you get for free and what you need to do yoursself. -We value web accessibility, and consider it is important to promote it to anybody who own and work on websites. Here, you'll find resources for web accessibility from basic concepts to technical approaches. - -[TO DO: ADD SOME QUICK LINKS TO RESOURCES.] -- New to web accessibility? [What is web accessibility?](LINK) is a good place to start. -- Looking for specific resources? - - Web accessibility for designers (generic/global resource link?) - - Web accessibility for developers (generic/global resource link?) - - Mayflower web accessibility (link) - - [Web Accessibility Standards in the Commonwealth of Massachusetts](https://www.mass.gov/guides/web-accessibility-standards) - - [IT Accessibility in the Commonwealth of Massachusetts](https://www.mass.gov/it-accessibility) - -## What is web accessibility? - -Web accessibility means **making your website available to as many people as possible**. - -It’s a combination of common sense, empathy and understanding. - -Source: [WUHCAG](https://www.wuhcag.com/what-is-web-accessibility/) - -Web accessibility refers to the **inclusive practice of removing barriers that prevent interaction with, or access to websites, by people with disabilities**. - -Source: [Wikipedia](https://en.wikipedia.org/wiki/Web_accessibility) - -Web accessibility consists of two parts: - -- philosophy — equivalent user experience -- process — techniques + code (what we build on line) - -They both are equally important to achieve the goal of creating an accessible website. - -## Why web accessibility matters - -At its core, the Web is about people being able to find and access information. Increasingly, access to online information is essential to our daily lives. Benefits from the Web are supposed to be avaiable to anybody. There shouldn't be any exception to any of us. - -When it’s broken down, the word accessibility is the “ability” to “access” and really this is why the topic is so important. Broadly stated, it’s intentionally designing the world to include everyone, regardless of disability. So we have access to more of life. - -For people with disabilities who have access to the Internet, independent access to information offers an unprecedented amount of freedom. - -According to [WebAIM](https://webaim.org/), most studies find that about one fifth (20%) of the population has some kind of disability. - -Even though not all of these people have disabilities that make them difficult to access the internet, it is still a significant portion of the population. This number would increase as senior population grows as projected by [United Nations Population Fund (UNFPA)](https://www.unfpa.org/publications/ageing-twenty-first-century). As they age, people could have these problems in various levels and some would have more than one problem. Remember, we are all temporarily able-bodied. - - -Resources: - -- [Brailworks: Why Accessibility Matters](https://brailleworks.com/accessibility-matters/) -- [Stanford University Online Accessibility Program: Why Accessibility Matters](https://soap.stanford.edu/getting-started/why-accessibility-matters) - - -## Myths of web accessibility - -People who are unfamilia with web accessibility tend to misunderstand it. If you believe some things shown below, read through our documentation. You'll start seeing web accessibility in more positive way. We demonstrate such misconceptions are not true in this styleguide. - -### 1. People who have disabilities do not use my website. - -The World Health Organization estimates that about 15% of the global population has a disability, and most of this large swath of the population participates in today’s internet-centric culture. There is no way of knowing how much of your site's traffic is allocated to individuals with disabilities. Sophisticated analytics can tell you a lot about your site visitors' browsers, countries, or basic demographics, but they cannot tell you who has an impairment and who doesn't. - -### 2. There is no economic benefit in making my website more accessible. - -Although there are costs in making your site accessible, the economic benefits can be vast. Individuals with disabilities still comprise a sizable part of the population, and even users who do not have disabilities can benefit from a smoother user experience. - -### 3.Web accessibility is only for the disabled. - -Though the main purpose of accessibility testing is to serve differently abled users, there are many instances in which implementing accessibility guidelines have benefited the overall user base. - -So even though performance improvement was never an integral part of the original requirements, by addressing the accessibility concerns, we were able to improve the performance of the application and benefit the entire user base. - -### 4. Website accessibility is expensive, difficult and time-consuming. - -There is no special Accessible HTML or Accessible CSS. The same languages and technologies are used, but perhaps with more understanding, attention to detail, and in accordance with some guidelines. - -WCAG guidelines can seem daunting at first. However, accessibility compliance isn't nearly as difficult or expensive as people tend to think it will be, especially if you do things the right way from the beginning. Learning accessibility guidelines is also a good investment in that considering the needs of all the site’s users improves the quality of your web design over time. - - -### 5. It's impossible to make my content accessible. - -The ADA requires reasonable efforts and accommodations, but you need not completely change your website. If your site features music, you don't have to stop using it simply because you might have deaf visitors. - -### 6. My website needs to become text-only. - -WCAG guidelines don't forbid you from using images, videos, and other assets. And including alternative text and removing color-based instructions won’t prevent you from having a visually-appealing and media-rich website. There's no need for a boring and dated-looking site that is text-only. - -### 7. Accessible websites are ugly and boring. - -The misconception comes from the early days of the Internet, when technology restricted the developer’s choice in terms of accessibility and design. But times have changed. It is now absolutely possible to create a beautiful, media-rich, interactive, and engaging website that is also accessible. - -Accessibility guidelines don’t forbid anyone to use images, videos, or Java scripts on their websites. The only suggestion is that if you do, make sure that the content of the website is still accessible to all sets of users. - -### 8. I only need to consider the needs of the blind when designing an accessible website. - -Although blind users' needs are important in determining how accessible your website is, there are also users with motor impairments. Individuals who are colorblind, deaf or hard of hearing, and those with cognitive and neurological disabilities all have different design considerations as well. The end goal is to create one great user experience for everyone, regardless of any disabilities they have — or don’t have. Accessible design benefits everyone. - -### 9. Automated evaluation tools are sufficient to determine my website’s accessibility. - -Automated evaluation tools are very helpful, as they can reduce the time and effort necessary for accessibility testing by identifying some potential issues. - -However, they can’t replace manual testing. Many of the accessibility checkpoints are not objective enough to be tested automatically, so they require human intervention and judgment. For example, an automation tool can check if an image has an alternate text description, but it won’t be able to judge if the description provided by the text is accurate and meaningful. - -### 10. I only have to worry about accessibility guidelines if I’m a web developer or designer. - -It’s true that web developers and designers must do most of the heavy lifting in creating accessible websites. But it is also management's responsibility to keep accessibility in mind, and the same goes for editors, artists, and anyone else involved in creating and managing the website. - -### 11. My personal website needs to meet ADA accessibility standards. - -Currently, accessibility regulations apply to websites that provide "goods, services, and programs to the public," such as government websites, shopping, and e-commerce. This distinction can fall into a gray area based on traffic and intent of a website, meaning personal private sites aren’t necessarily subject to accessibility standards. It, however, is a good idea to make your personal website accessible for a better user experience for all. - - -Sources: - -- [Bureau of Internet Accessibility: Website Accessibility Isn't What You Think It Is: 10 Myths, Busted](https://www.boia.org/blog/website-accessibility-isnt-what-you-think-it-is-10-myths-busted) -- [TechWell: The Top Four Myths about Web Accessibility](https://www.techwell.com/techwell-insights/2014/11/top-four-myths-about-web-accessibility) - - - - - -## Benefits of having an accessible website - -Let's take a look at some benefits of having accessible website, and these are also reasons **why you make your website accessible**. - -### 1. Improve the lives of people with disabilities - -You do something positive for the world. You promote a culture of accessibility and inclusion. Web accessibility is essential for equal opportunity. - -Corporate Social Responsibility (CSR) - When an organization's website is not accessible, it further excludes people with disabilities from society. When an organization's website is accessible, it empowers people with disabilities to participate in society. Providing an accessible website is one way an organization can demonstrate that it strives to meet the access needs of a diverse society. - -### 2. Build positive public relations - -An organization's efforts in Web accessibility are a public relations opportunity to increase its positive image, which can increase website use. - -Corporate Social Responsibility (CSR) has been shown to improve financial performance, enhance brand image and reputation, increase sales and customer loyalty, increase ability to attract and retain employees, and provide access to capital and funding. Additional perspectives on CSR, such as statistics that show how CSR impacts customers, are available on the Web. - -### 3. Broaden your market penetration - -You expand your customer/audience base. According to a [2010 report from the U.S. Census Bureau](https://www.census.gov/content/dam/Census/library/publications/2012/demo/p70-131.pdf), around 18.7% of the U.S. population lives with a disability and, out of that number, 12.6% have a severe disability. - -A [study in the United Kingdom (UK)](https://disability-smart.com/2017/01/10/is-there-really-a-business-case-for-website-accessibility/) found that 71% of web users with a disability will simply leave a website that is not accessible. - - -### 4. Avoid discrimination and legal complications - -Your website will comply with your country’s equality and anti-discrimination law. - -Internationally, governments, but also private companies and organisations, are becoming subject to legal challenges because of their inaccessible online content and service offerings. - -In the US, public sector entities (government-funded programs/schools, airlines, and nonprofits) are required to follow certain website accessibility rules, while private sector companies just [hope they will not get sued](https://insight.cryptzone.com/accessibility/6-web-accessibility-takeaways-winn-dixie-accessibility-decision/). - -In 2017 the Information and Communication Technology (ICT) passed a ruling to update the old 508 rules to be more inline with WCAG 2.0 guidelines, meaning that website accessibility updates are required for most public websites — and it is just a matter of time before private websites will be as well. - -### 5. Better Search Engine Optimization (SEO) - -Accessibility techniques increase the findability of web pages by exposing content to search engines, both internally (within a website) and externally (across the World Wide Web). Most of the search engines are only able to process text and the way it is structured. By having a well-marked up site, they can index your site for more relevant information in search results. - - -### 6. Improve usability for all types of users - -Not just people with disabilities, but web accessibility also helps people who: - -- Have a slow Internet connection - - location- for example, rural areas where high speed connections are not available or mobile phone reception is limited - - bandwidth congestion -- Use older technologies - - old web browser - - operating system -- Have a small screen or unusual device -- Can't listen to audio content in where they are at the moment (ex. work, hospital, etc.) -- Are not familiar with the technologies involved to use websites - - infrequent Web users - - new to Web - - -### 7. Produce a high quality and highly flexible website - -- Reduces site development and maintenance time and cost -- Enables content on different configurations, such as mobile devices, screen readers, different operating systems and browsers; -- ‘Future proofed’, that means being prepared for implementing future technologies; -- Cross-browser compatibility. - - -Resources: - -- [Constructing a POUR Website](https://webaim.org/articles/pour/) -- [The Whole Brain Group](http://blog.thewholebraingroup.com/5-benefits-accessible-website) -- [The benefits of Web Accessibility](http://www.accessibletemplate.com/about-accessibility/the-benefits-of-web-accessibility) -- [Benefits of Accessible Design](https://digital.gov/2017/05/09/benefits-of-accessible-design/) -- [Social Factors in Developing a Web Accessibility Business Case for Your Organization](https://www.w3.org/WAI/bcase/soc) -- [Financial Factors in Developing a Web Accessibility Business Case for Your Organization](https://www.w3.org/WAI/bcase/fin.html) -- [Getting Started with Website Accessibility](https://medium.com/statuscode/getting-started-with-website-accessibility-5586c7febc92) - - -## What it takes to access web sites - -Some components are involved to make websites available to any of us. First, we have information to put on a website. We refer it as **web content**. Second, we need tools to create a website, which is categorized as **authoring tools**. Third, we need means to get to the website. That is **user agents**. Let's take a look at each component closely. - -### Web content - -It is any part of a web site such as: - -- text -- images -- forms -- multimedia (audio, video, animation) [content requires another layer of means to access its content] -- any markup code -- scripts -- applications - -### Authoring tools - -They are the tools to build a website. They can be software or services that people use to produce web content. Here are some of them: - -- code editors -- document conversion tools -- content management systems -- blogs -- database scripts - - -### User agents -Software that people use to access web content: - -- desktop graphical browsers -- voice browsers -- mobile phone browsers -- multimedia players -- plug-ins -- assistive technologies - - -To be able to access a website, these components need to play well together. If web content is not available, you wouldn't see anything on the website. If authoring tools are not available, you couldn't have your information or messages on your website. If user agents are not available, you cannot get to the website or the content on the website. Every component is equally important to make a website available. - -Web accessibility principles and techniques support these components to optimize their capabilities to make websites available to broad range of users. - -## Obstacles to use websites - -People with the following conditions find using websites challenging. - -- Problems with sight: - - blindness - - low vision - - color-blindness -- Problems with hearing: - - deafness - - hard-of-hearing -- Problems using a mouse or keyboard: - - inability to use a mouse or/and a keyboard - - slow response time - - limited for motor control -- Problems with reading and understanding: - - learning disabilities - - destructibility - - inability to remember - - focus on large amount of information - -We can ease such problems with our [TO DO] - -### Get to know people with disabilities - -It is essential for us to learn disabilities and a life with them when we think how we could accommodate people with disabilities as our website users. Disabilities are not just types of conditions. There are much more to be aware. - -Some have disabilities at birth. - -Some got disabilities at some point of their life by illness, accidents, aging and so on. In this group, some of them suddenly faced their impatient. To the others, it could develop with various manners. - -Disability is not always permanent. Some have disabilities for certain period of time. They could be in their recovery from injuries, illness, medical procedures and so on. - -Also, there are various range of the severity of their impairments. Some of them could have multiple disabilities. - -Most of disabilities are not visually recognizable. [You can learn more about some types of disabilities.](ADD LINK) - -The adaptability to their impairments also varies depending on their situations. - -You cannot assume all blind people understand/use braille or any deaf people understand/use sign languages. - - -[Learn more about disabilities] >>> Disability Types - - -### How people with disabilities use websites - -Mary audience and including those who may have difficulty with some of the content. -People with disability might need some assistance to use websites depending on their conditions. Not all of them need assistance to use a website, but their user experience could be much better with a mindfully created website. - -Understanding [their obstacles](LINK to Obstacles to use websites) would help us creating practically accessible websites. - -#### Visual disabilities - -##### Blindness - -People who are blind are not able to see things as well as those who are not blind. Although it's true that most blind people do have some degree of vision, it could be said that whatever vision they have is not useful enough for using the web. A computer monitor and mouse would be much less useful to a person who is blind. It's not that blind people are incapable of moving or clicking a mouse; it's just that they don't know where to move it or when to click it, since they can't see what's on the screen. - - -People with substantial, uncorrectable loss of vision in both eyes generally use **[screen readers](http://www.afb.org/prodBrowseCatResults.aspx?CatID=49)** such as VoiceOver for Mac OS, JAWS for Windows, and so on. - -Screen readers read aloud a web page based on how the page is structured as markup, which might not reflect how the page is visually laid out. - -Screen readers can also be used by **those who are both deaf and blind**. Rather than convert text into speech, screen readers for the deaf-blind convert text into Braille characters on refreshable Braille devices, which have small pins that can be raised or lowered to form Braille characters which the deaf-blind individual can feel. - -###### Obstacle 1: Unstructured presentation - -If the page is not marked up in a reading order the page content makes sense, they would have a difficult time to navigate the page and comprehend the content. - -The flow of the page elements such as header, footer, navigation, main content area, and so on really matters to screen readers to understand what is going on in the page. - -###### Obstacle 2: Non-semantic content - -Screen readers process the content as it's marked up. The content doesn't have semantic markup could miss its context to pass on and makes it harder to understand to the users. - -Screen readers recognize headings, links, lists, forms, and so on, and announce what those elements are before reading through their contents. - -###### Obstacle 3: Non-text content missing text alternative presenttion - -If images, movies, videos don't have their alternative text presentation, screen readers cannot accurately convey their content. - -###### Obstacle 4: Keyboard inaccessibiilty - -Screen reader users use their keyboard as their primary means of navigating the web. If a website is unable to navigate with keyboard, they wouldn't be able to use the website. - -##### Low vision - -The visual acuity of people with low vision varies widely, but, in general, low vision is defined as a condition in which a person's vision cannot be fully corrected by glasses, thus interfering with daily activities such as reading and driving. - -The most common technology used by people with low vision is [screen magnifiers](http://www.afb.org/prodBrowseCatResults.aspx?CatID=39), assistive technology to adjust the page elements' contrast to suit their vision condition. - -Some might need high contrast. Some might need to tone down bright colors because of their sensitivity to a light(= brightness). - -Some people with low vision will change the settings in their operating system and/or browser to not only enlarge the text, but to increase the contrast of the text in relation to the background. - -###### Obstacle 1: Text presented in graphics - -Some kinds of content are difficult to interpret when enlarged. For example, graphics that contain text can become blocky and pixilated, making the text difficult to understand. - -###### Obstacle 2: Horizontal scrolling - -Espeially for screen magnifiers users, websites require to use horizontal scrollbar is difficult to use since they browse a page little by little enlarging a small section of the page. - - -##### Color-blindness - -People with color blindness might use assistive technology to transform colors by converting to ones they can recognize. But, you'd better prepare your website assuming they don't use assistive technology. - -[You can see how people with color-blindness would see colors](https://webaim.org/articles/visual/colorblind). - -###### Obstacle: no alternative presentation to colors - -When the colors, only the colors, convey important information, for example using a color they cannot recognize to indicate something important becomes a problem to them. Under these circumstances you will need to either change the graphic or provide an additional means of obtaining the same information. Oftentimes the most appropriate way to do this is to provide an explanation in the text itself. - -#### Auditory disabilities - -Most of people with deafness and hard-of-hearing rely on visual presentation of information. Depending on their severity of hard-of-hearing, they might be able to obtain audio content with some adjustment. - -##### Obstacle 1: no alternative visual presentation of audio content - -- Audio content, such as videos with voices and sounds, without captions or transcripts. -- Web-based services, including web applications, that rely on interaction using voice only. -- Lack of sign language to supplement important information and text that is difficult to read. - - -##### Obstacle 2: no control options for media players - -- Media players that do not display captions and that do not provide volume controls. -- Media players that do not provide options to adjust the text size and colors for captions. - - -#### Physical disabilities (sometimes called “motor disabilities”) - -The conditions for physical disabilities vary in their types and severities. Most likely they have difficulty to use a mouse and/or keyboard. - -To use the Web, people with physical disabilities often use specialized hardware and software such as: - -- Ergonomic or specially designed keyboard or mouse; -- Head pointer, mouth stick, and other aids to help with typing; -- On-screen keyboard with trackball, joysticks, or other pointing devices; -- Switches operated by foot, shoulder, sip-and-puff, or other movements; -- Voice recognition, eye tracking, and other approaches for hands-free interaction. - -People with physical disabilities may be using a mouse or mouse-like device only, or keyboard or keyboard-like device only to operate the computer. **People with physical disabilities rely on keyboard support to activate functionality provided on web pages.** They may need more time to type, click, or carry out other interaction, and they may type single keystrokes in sequence rather than typing simultaneous keystrokes (“chording”) to activate commands. Such keystrokes include commands for special characters, shortcut keys, and to active menu items. - -People with physical disabilities may have trouble clicking small areas and are more likely to make mistakes in typing and clicking. Providing large clickable areas, enough time to complete tasks, and error correction options for forms are important design aspects. Other important design aspects include providing visible indicators of the current focus, and mechanisms to skip over blocks, such as over page headers or navigation bars. People with cognitive and visual disabilities share many of these requirements. - -##### Obstacle 1: lack of keyboard support - -Websites and web browsers that do not provide full keyboard support. - -##### Obstacle 2: lack of time to complete a task - -Insufficient time limits to respond or to complete tasks, such as to fill out online forms. - -##### Obstacle 3: lack of alternative presentation - -Controls, including links with images of text, that do not have equivalent text alternatives. - -##### Obstacle 4: poor presentation - -Missing visual and non-visual orientation cues, page structure, and other navigational aids. - -Inconsistent, unpredictable, and overly complicated navigation mechanisms and page functions. - - -#### Cognitive (reading and understainding) - -The concept of cognitive disabilities is extremely broad, and not always well-defined. In loose terms, **a person with a cognitive disability has greater difficulty with one or more types of mental tasks than the average person**. - -In fact, one may reasonably argue that a great deal of web content cannot be made accessible to individuals with profound cognitive disabilities, no matter how hard the developer tries. Some content will always be too complex for certain audiences. This is unavoidable. Nevertheless, there are still some things that designers can do to increase the accessibility of web content to people with less severe cognitive disabilities. - -Usually, the best advice to help users with cognitive disabilities is to provide information in multiple formats, with a heavy emphasis on visual formats. Even though most web content suffers for a lack of visually-enhanced communicative methods, the take-home message is that no one method is sufficient by itself. **Supplement the information with multiple modes and methods of communication**. - -The main categories of functional cognitive disabilities include deficits or difficulties with: - -##### Obstacle 1: Memory - -Some users may have memory difficulties that impair their ability to remember how they got to content. - -Any kind of reminder of the overall context of a web site can help people with memory deficits. - -##### Obstacle 2: Problem-solving - -Some individuals have a difficult time solving problems as they arise. In many instances, their resilience can be low and the resulting frustration is such that they choose to leave the site and not persist to solve the problem. - -Providing instructions at the start of a task will eliminate or at least reduce the overall number of user errors. - -Error messages should be as explanatory as possible, telling users what they did wrong and how to fix the problem. - -Also, avoid extreme changes in the context of the web site without first warning users. - -All functionality should be as predictable as possible, and any deviations from predictability should be preceded by warnings and/or explained to users after the changes occur. - -##### Obstacle 3: Attention - -There are many individuals that have difficulty with focusing their attention to the task at hand. Distractions like below can make the web environment difficult or even impossible: - -- scrolling text -- blinking icons -- pop-up windows - -Avoiding anything that draws a person's attention away from the main content and using good design, such as color, white space, and simple presentation can help users focus on important content and functionality. - -##### Obstacle 4: Reading, linguistic, and verbal comprehension - -Some individuals have difficulties understanding text in various severities like the brightest minds of recent generations such as Albert Einstein, Thomas Edison, and Henry Ford. - -It would be unreasonable to expect web developers and content authors to accommodate the entire range of reading abilities. It is reasonable, however, to expect content authors to **write as simply and clearly as is feasible**, taking into account the pri -###### Non-Literal Text - -Non-literal text, such as sarcasm, satire, parody, allegory, metaphor, slang, and colloquialisms, can be a problem for some readers. - -###### Non-Existent Text - -The unstated assumptions and implied meaning of written content may seem obvious to the writer, but readers may not have the necessary background knowledge. Some readers may not have the skills to infer meaning from text without additional help. - -##### Obstacle 5: Math comprehension - -Mathematical expressions are not easy for everybody to understand. - -For people who are comfortable reading equations and thinking mathematically, the best way to explain mathematical concepts is to use equations. On the other hand, often it is helpful to explain math conceptually, either with or without the formulas. - -Conceptual explanations help readers understand the reasoning behind the math. - -##### Obstacle 6: Visual comprehension - -Some individuals have difficulties processing visual information, the opposite of the problem experienced by people with reading and verbal processing difficulties. - -They may recognize the fact that there are objects on a web page, but may not be able to identify the objects. - -For example, they may not realize that a photograph of a person is a representation of a person, though they can plainly see the photograph itself (as an object) on the web page. - -For these people, a moving, talking person in a video may be easier to identify and mentally process than a static image of a person in a photograph. Video and multimedia, accompanied with narration, may be the best way to communicate to these individuals. - -#### Seizure - -Some people are susceptible to seizures caused by **strobing**, **flickering**, or **flashing** effects. This kind of seizure is sometimes referred to as a photoepileptic seizure because it is caused by pulses of light (hence the prefix "photo") interacting with the eye's light-receptive neurons and the body's central nervous system. - -Most web content is completely harmless to individuals with photoepileptic tendencies. Even most animations, videos, moving text, and Flash objects do not present any danger. - -We should still make every effort to ensure that our content does not have strobing, flickering, or flashing effects. - -#### Vestibular disorders - -Even if an animating or moving object does not cause a seizure, it may cause nausea or dizziness in some people. - -The following items can result in difficulties for users with vestibular disorders: - -- High contrast graphics with tight parallel lines. -- Animated scrolling that lasts longer than perhaps 1/4 second. -- Parallax or reverse parallax - simultaneous foreground and background scrolling in different directions or at different speeds. -- Moving images beneath static text. - - -Resources: - -- [W3C: How People with Disabilities Use the Web](https://www.w3.org/WAI/people-use-web/) - - - - - -## What you can do to make our website accessible - -There are four main principles to make our website accessible based on these basic concepts: - -- Understanding the user's perspective and needs -- Moving beyond technical accessibility -- Focusing on the principles of accessibility - - -### PERCEIVABLE information and user interface - -Starting at the most basic level, users must be able to process information. -The information could be text, audio, static image, video, and so on, things presented in your website, which are referred as **web content**. - -Information that is not presented in a processable format is not accessible. Websites and apps that require sight or hearing won't pass the test of perceivability. - -#### Text alternatives for non-text content - -Text alternatives convey the purpose of an image or function to provide an equivalent user experience. For examples: - -- Short equivalents for images, including icons, buttons, and graphics; -- Description of data represented on charts, diagrams, and illustrations; -- Brief descriptions of non-text content such as audio and video files; -- Labels for form controls, input, and other user interface components. - - -#### Captions and other alternatives for multimedia - -Among other affordances, this means providing text for those who cannot hear, and audio for those who cannot see. It does not mean creating audio for all text, but content must be consumable by screen readers and other assistive technologies. - -#### Content can be presented in different ways - -Since not everyone has the same abilities or equal use of the same senses, one of the main keys to accessibility is ensuring that information is transformable from one form into another, so that it can be perceived in multiple ways. - -Organize information to have with meaning (semantic structure). Design with text and create information hierarchies. When the presentation is disabled, the web content should still be able to communicate its message effectively. - -#### Content is easier to see and hear - -- Color is not used as the only way of conveying information or identifying content -- Default foreground and background color combinations provide sufficient contrast -- Text is resizable up to 200% without losing information, using a standard browser -- Images of text are resizable, replaced with actual text, or avoided where possible -- Users can pause, stop, or adjust the volume of audio that is played on a website -- Background audio is low or can be turned off, to avoid interference or distraction - -**Ask yourself**: Is there anything on our website that a blind, deaf, low vision, or color blind user would not be able to perceive? - - - -### OPERABLE user interface and navigation - -#### Functionality is available from a keyboard - -Not everyone uses a standard keyboard and mouse to access the web. Some people use adaptive devices or alternative devices that accommodate their disabilities. Some people simply prefer to use the alternative technologies. Many users with disabilities cannot operate a mouse. Alternatives like keyboard-based operation should be implemented. - -Keyboard accessibility includes: - -- All functionality that is available by mouse is also available by keyboard; -- Keyboard focus does not get trapped in any part of the content; -- Web browsers, authoring tools, and other tools provide keyboard support. - -#### Users have enough time to read and use the content - -Some people need more time than others to read and use the content. For instance, some people require more time to type text, understand instructions, operate controls, or to otherwise complete tasks on a website. - -Examples of providing enough time include providing mechanisms to: - -- Stop, extend, or adjust time limits, except where necessary; -- Pause, stop, or hide moving, blinking, or scrolling content; -- Postpone or suppress interruptions, except where necessary; -- Re-authenticate when a session expires without losing data. -- Time limits for completing an action should be generous or configurable. - -#### Content does not cause seizures - -Content that flashes at certain rates or patterns can cause photosensitive reactions, including seizures. Flashing content is ideally avoided entirely or only used in a way that does not cause known risks. - -#### Users can easily navigate, find content, and determine where they are - -With web pages or sections of Web content, users should be able to bypass extraneous or irrelevant pieces of content in order to focus on the content of interest to them. They should be able discern the structure of the content by its headings, subsections, bulleted lists, and other elements of semantic markup. - -Well organized content helps users to orient themselves and to navigate effectively. Such content includes: - -- Pages have clear titles and are organized using descriptive section headings; -- There is more than one way to find relevant pages within a set of web pages; -Users are informed about their current location within a set of related pages; -- There are ways to bypass blocks of content that are repeated on multiple pages; -- The keyboard focus is visible, and the focus order follows a meaningful sequence; -- The purpose of a link is evident, ideally even when the link is viewed on its own. - -**Ask yourself**: Can all functions of our website be performed with a keyboard? Can users control interactive elements of our website? Does our website make completing tasks easy? - - - - -### UNDERSTANDABLE information and user interface - -If users can perceive and operate a website, that doesn't mean they can understand it. Understandable websites use clear, concise language and offer functionality that is easy to comprehend. Writing should be clear and concise. - -#### Text is readable and understandable - -- Identifying the primary language of a web page, such as Arabic, Dutch, or Korean; -- Identifying the language of text passages, phrases, or other parts of a web page; -- Providing definitions for any unusual words, phrases, idioms, and abbreviations; -- Using the clearest and simplest language possible, or providing simplified versions. - -#### Content appears and operates in predictable ways - -Many people rely on predictable user interfaces and are disoriented or distracted by inconsistent appearance or behavior. Examples of making content more predictable include: - -- Navigation mechanisms that are repeated on multiple pages appear in the same place each time; -- User interface components that are repeated on web pages have the same labels each time; -- Forms should follow a logical flow and provide clear labels. -- If a user takes an action, the connection between the action and the result should be obvious. -- Significant changes on a web page do not happen without the consent of the user. - -#### Users are helped to avoid and correct mistakes - -Sites and apps should be forgiving. All people, not just those with disabilities, make mistakes through forms and other interaction, which can be confusing or difficult to use. Examples of helping users to avoid and correct mistakes include: - -- Descriptive instructions, warnings, error messages, and suggestions for correction; -- Context-sensitive help for more complex functionality and interaction; -- Opportunity to review, correct, reverse submissions, or cancellation options if necessary. - -If this feels like usability and not accessibility, that's because usable websites are inherently more accessible. - -**Ask yourself**: Is all of the text on our website clearly written? Are all of the interactions easy to understand? - - -### ROBUST content and reliable interpretation - -#### Content is compatible with current and future user tools - -Users pick their own mix of technologies. Within limits, websites should work well-enough across platforms, browsers, and devices to account for personal choice and user need. - -Robust content is compatible with different browsers, assistive technologies, and other user agents. One of the best ways to meet the principle of robustness is to follow development standards and conventions. Clean code is generally more robust and consumable across platforms. - -- Ensuring markup can be reliably interpreted, for instance by ensuring it is valid; -- Providing a name, role, and value for non-standard user interface components. - -**Ask yourself**: Does our website only support the newest browsers or operating systems? Is our website developed with best practices? - - - -Sources: - -- [W3C - Accessibility Principles](https://www.w3.org/WAI/fundamentals/accessibility-principles/) -- [DYNAMIT](http://www.dynamit.com/accessibility-principles/) -- [WebAIM](https://webaim.org/articles/pour/) -- [Adobe Blog - Design With Accessibility in Mind: The POUR Methodology](https://theblog.adobe.com/design-with-accessibility-in-mind-the-pour-methodology/) -- [DYNO Mapper - Building a POUR Website: the 4 Principles of Accessibility](https://dynomapper.com/blog/27-accessibility-testing/274-4-principles-of-accessibility) - - - - ------------------------------------------------------------------- - ---- -description: >- - Mass.gov and other Massachusetts government websites must comply with 508c - which is defined by the WCAG-AA web-standard. --- -# Accessibility - -In addition to the following items below individual components, colors and page layouts may also have additional accessibility notes. For design purposes the following at minimum must be met, though there may be other applicable guidelines. - -## Accessibility Guidelines +### Structure and layout -### Standards +Sstructured markup made up of [HTML5 semantic elements](https://www.w3schools.com/html/html5_semantic_elements.asp) like article, section, aside, is how we build layouts that are [machine-readable](https://www.smashingmagazine.com/2020/10/developing-semantic-web/) by assistive technologies. -* WCAG 2.0 -* AA +**Mayflower provides:** +- Aria roles where appropriate and sane defaults for each element +- Many elements and components of Mayflower use HTML5 semantic markup -### Contrast +**You should:** +- Change Aria roles if neeeded based on your use case +- Nest elements properly, eg. a section should be inside an article etc. Here are some guidelines on using [semantic markup](https://www.freecodecamp.org/news/semantic-html5-elements/) -* For font sizes under 18 point \(or 14 points if bold\) contrast must be a minimum of 4.5:1 -* For font sizes greater than 18 points \(or 14 points if bold\) contrast must be a minimum of 3:1 +--- -### **Color** +### Colors and contrast -* Color cannot be the only means of displaying information. Additional items such as a label, higher contrast or another visual cue must be used. +Part of accessibility is making sure users with all types of visual ability can use your site, and color is a big part to that. -### Images and other Non-Text Content +**Mayflower provides:** +- A color palette optimized for all forms of color blindness +- A variety of tints and shades to choose from +- Default styles on all elements that already meet WCAG contrast standards -* All non-text content must have a text alternative on the page that displays the same information such as - * Alt tags or aria labels on all images \(these must describe what is happening within the image\) - * In the event an image is purely decorative in nature the alt tag must be present but should be blank - * Note that items such as stock photography or landscapes are not considered purely decorative and must have the appropriate descriptors - * Transcriptions of video or closed captioning +**You should:** +- Stick to the default colors provided by Mayflower components wherever possible +- Check your UI with this [contrast checker](https://contrastchecker.com/). +- Check your UI for all types of [color blindness](https://accessgarage.wordpress.com/2013/02/09/458/) -#### Iconography +--- -Note that iconography is a special type of image content. +### Typography -* * Current guidelines display all icons with a label underneath them - * If this guideline is followed then the alt tag should be left empty \(but it should still exist\) - * If the label is removed then an alt tag with proper information must be applied +Like color and contrast, clear legible typography helps the visually impaired, but it alsso iss helpful to users with language or learning issues. -### **Links** +**Mayflower provides:** +- The highly legible and versatile `Noto Sans` variable font +- Noto glyphs are friendly to readers with learning disabilities such as dyslexia +- A broad range of weights +- Default classes for size, weight, and spacing we optimized for legibility on all devices -* The purpose of a link can be determined from the link text alone or or from the text combined with programmatically determined content - * The largest errors usually found here are on article preview links or similar where there may be multiple links on a page stating “read more” or other similar repeatable text, this should be avoided. -* Additionally links that are not links but items such as files, e-mail to links and phone numbers should be clearly labeled as such +**You should:** +- **Never** use a 'custom' font not provides by Mayflower +- **Never** use weights of `Noto Sans` below `350` at sizes below `1rem` +- **Never** use tints or shades as a font color -### Rich Text Editors +--- -* These should be used sparingly across the site. Rich text editors have the potential to easily break 508c compliance as many of the programmatic fail safes that exist will not happen within a rich text editor -* If a rich text editor is used the content author needs to be sure to follow good programming guidelines if using HTML \(such as semantic markup and using appropriate labels\) -* Additional focus also needs to be taken on headings, labels and other items to guarantee an [adherence to the pages navigability](https://www.w3.org/WAI/WCAG20/quickref/?currentsidebar=%23col_overview&showtechniques=111%2C141%2C143&levels=aaa#navigation-mechanisms) +### Iconography -### Headings +Icons can be very helpful as visual hints or touchstones in a UI but they should never convey all of the meaning of any action. -* Headings should not be used to convey style items -* Headings must be hierarchical and properly nested \(all h2’s within an h1 etc\) so as to maintain proper navigability for low or non-sighted users +**Mayflower provides:** +- A set of icons that are bold, simple and broadly understood +- Icons are in [Scalable Vector Graphics (SVG)](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) format (with .PNG fallbacks) so that icons remain crisp if a visually impaired user increases their text size +- Icons inherit the CSS `color` attribute so that their color will change when high-contrast is enabled -### **Tables** +**You should:** +- **Avoid** adding new icons not in Mayflower if one is neccessary feel free to propose it as an update) +- Choose the icon matches the meaning of the action, as most broadly understood by users +- **Avoid** using an icon alone without text unless space demands (eg. in amobile header) and an `alt` attribute is provided +- **Always** provide an `alt` attribute for icons in the rare case there is no accompanying text -The current tables as defined in components are accessible. However these tables must be used appropriately in-order to remain so. The following rules must be adhered too +--- -* Only use tables for tabular data \(don’t use tables for styling purposes\) -* All labels within a table must be next to the data they are labeling \(the current examples adhere to this pattern\) +### Images -## **Accessibility Checkers** +We know that all imagess need to be described for the blind or visually impaired, but many users also get meaning from images more readily than text. Use images that are not just 'pretty', but that tell the same story as the text. -Note that the following checkers will only catch programmatic misses such as missing alt tags or improper contrast ratios. Many accessibility errors can only be caught by humans and hence online checkers should only be one part of the confirmation process. +**Mayflower provides:** +- The Image component which adds the `alt` attribute +- The `ma_image` class that styles images and makes them responsive -* [Wave](http://wave.webaim.org/) -* [Access Valet](http://valet.webthing.com/access/url.html) -* [A Checker](https://achecker.ca/checker/) +**You should:** +- **Always** add an `alt` description to an image unless it is purely decorative, in which case add `role="aria-hidden"`. +- **Never** Make an image the only source of information, for example in an infographic. +- In general if an image includes text of any kind, *all* of the text should be available in the `alt` sdescription or elsewhere on the page -## **Additional Resources and Guidelines** +### Content -Generally speaking the rules above do not encompass the entirety of all accessibility considerations on the site and additional information may be necessary. Further resources can be found below +**Mayflower provides:** +- Plain-language names and descriptions -* [WCAG Quick Reference](https://www.w3.org/WAI/WCAG20/quickref/) -* [Entirety of the WCAG 2.0 Guidelines](https://www.w3.org/TR/WCAG20/) -* [Web Aim which is an independent company with good information](http://webaim.org/) +**You should:** +- Don't change menu link names provided by Mayflower that already link to other locations on [Mass.gov](http://www.mass.gov) +- Follow the established conventions established by [Mass.gov](https://www.mass.gov) when creating new links. For example, action links are invitations "Sign up for our newsletter", not destinations "Newsletter sign-up page." +- Follow the Plain Language guidelines on [PlainLanguage.gov](https://www.PlainLanguage.gov) diff --git a/packages/core/stories/principles/Resources.stories.mdx b/packages/core/stories/principles/Resources.stories.mdx new file mode 100644 index 0000000000..e52451caef --- /dev/null +++ b/packages/core/stories/principles/Resources.stories.mdx @@ -0,0 +1,66 @@ +import { Meta } from '@storybook/addon-docs/blocks'; +import generateTitle from '../util/generateTitle'; + + + +# Accessibility Resources + +--- + +> Web accessibility means **making your website available to as many people as possible**. It’s a combination of common sense, empathy and understanding. -*[WUHCAG](https://www.wuhcag.com/what-is-web-accessibility/)* + +--- + +## Why web accessibility matters + +At its core, the Web is about people being able to find and access information. Increasingly, access to online information is essential to our daily lives. Benefits from the Web are supposed to be avaiable to anybody. There shouldn't be any exception to any of us. + +When it’s broken down, the word accessibility is the “ability” to “access” and really this is why the topic is so important. Broadly stated, it’s intentionally designing the world to include everyone, regardless of disability. So we have access to more of life. For people with disabilities who have access to the Internet, independent access to information offers an unprecedented amount of freedom. + +According to [WebAIM](https://webaim.org/), most studies find that about one fifth (20%) of the population has some kind of disability. Even though not all of these people have disabilities that make them difficult to access the internet, it is still a significant portion of the population. This number would increase as senior population grows as projected by [United Nations Population Fund (UNFPA)](https://www.unfpa.org/publications/ageing-twenty-first-century). As they age, people could have these problems in various levels and some would have more than one problem. Remember, we are all temporarily able-bodied. + +## Resources + +### The importance of Accessibility + +- **Railworks:** [Why Accessibility Matters](https://brailleworks.com/accessibility-matters/) +- **Stanford University:** [Why Accessibility Matters](https://soap.stanford.edu/getting-started/why-accessibility-matters) +- **Bureau of Internet Accessibility:** [10 Myths, Busted](https://www.boia.org/blog/website-accessibility-isnt-what-you-think-it-is-10-myths-busted) +- **TechWell:** [The Top Four Myths about Web Accessibility](https://www.techwell.com/techwell-insights/2014/11/top-four-myths-about-web-accessibility) +- **The Whole Brain Group:** [three reasons to consider accessibility](https://thewholebraingroup.com/blog/reasons-accessibility/) +- **W3C:** [Developing a Web Accessibility Business Case for Your Organization](https://www.w3.org/WAI/bcase/soc) + +### Acceessibility principles + +- **DYNAMIT:** [acccessibility principles](http://www.dynamit.com/accessibility-principles/) +- **DYNO Mapper**, Building a POUR Website: [the 4 Principles of Accessibility](https://dynomapper.com/blog/27-accessibility-testing/274-4-principles-of-accessibility) +- **W3C** [accessibility Principles](https://www.w3.org/WAI/fundamentals/accessibility-principles/) + +### Designing for Access + +- **Adobe Blog:** Design With Accessibility in Mind: [The POUR Methodology](https://theblog.adobe.com/design-with-accessibility-in-mind-the-pour-methodology/) +- **WebAIM:** [Constructing a POUR Website](https://webaim.org/articles/pour/) +- **Accessibletemplate:** [The benefits of Web Accessibility](http://www.accessibletemplate.com/about-accessibility/the-benefits-of-web-accessibility) +- **Digital.gov** [Benefits of Accessible Design](https://digital.gov/2017/05/09/benefits-of-accessible-design/) +- **Medium:** [Getting Started with Website Accessibility](https://medium.com/statuscode/getting-started-with-website-accessibility-5586c7febc92) + +### Assistive Technologies + +- **AFB:** [screen readers](https://www.afb.org/blindness-and-low-vision/using-technology/assistive-technology-products/screen-readers) +- **AFB:** [screen magnifiers](https://www.afb.org/blindness-and-low-vision/using-technology/using-computer/part-ii-experienced-computer-user-new-0) +- **WebAIM:** [Accesssibility and color-blindness](https://webaim.org/articles/visual/colorblind) +- **W3C:** [how People with Disabilities Use the Web](https://www.w3.org/WAI/people-use-web/) + +### User Generated Content + +- **W3C:** Rich text [adherence to the pages navigability](https://www.w3.org/WAI/WCAG20/quickref/?currentsidebar=%23col_overview&showtechniques=111%2C141%2C143&levels=aaa#navigation-mechanisms) + +### Tools to Build and Test for Accessibility + +- **WebAIM:** [Wave](http://wave.webaim.org/) +- **A Checker:** [Accessibility checker](https://achecker.ca/checker/) + +### Additional Resources and Guidelines + +* **WCAG:** [Quick Reference](https://www.w3.org/WAI/WCAG20/quickref/) +* **WCAG:** Complete WCAG [2.0 Guidelines](https://www.w3.org/TR/WCAG20/) diff --git a/packages/core/stories/styles/index.scss b/packages/core/stories/styles/index.scss index 708b132534..ee900de7cf 100644 --- a/packages/core/stories/styles/index.scss +++ b/packages/core/stories/styles/index.scss @@ -53,6 +53,15 @@ table.sbdocs.sbdocs-table { min-width: 100%; } +.sp { + &--top { + margin-top: 2rem; + } + &--bottom { + margin-bottom: 2rem; + } +} + small { font-size: .9rem; }