├── .ruby-version
├── .bundler-version
├── favicon.ico
├── images
    ├── bkg.png
    ├── sign.jpg
    ├── blacktocat.png
    ├── gsa-logo-w100.png
    ├── iterative-design.png
    ├── angle-arrow-down-white.svg
    ├── angle-arrow-up-white.svg
    ├── 18f-logo-black.svg
    ├── Slack_Mark.svg
    ├── 18f-logo-blue.svg
    └── gsa-logo-blue.svg
├── favicon-16x16.png
├── favicon-32x32.png
├── .gitignore
├── .pa11yci
├── .about.yml
├── assets
    ├── css
    │   └── styles.scss
    └── js
    │   ├── time-outs.js
    │   ├── keyboard-access.js
    │   └── flashing.js
├── _sass
    ├── _uswds-theme-settings.scss
    ├── syntax.css
    └── _uswds-theme-custom-styles.scss
├── .github
    ├── dependabot.yml
    └── workflows
    │   └── pa11y.yml
├── pages
    ├── iframeform.md
    ├── alternativeversions.md
    ├── pagetitles.md
    ├── gov-resources.md
    ├── timeouts.md
    ├── language.md
    ├── flashing.md
    ├── iframes.md
    ├── css.md
    ├── multimedia.md
    ├── landmarks.md
    ├── videos.md
    ├── writingguide.md
    ├── checklist.md
    ├── images.md
    ├── keyboard.md
    ├── hiddencontent.md
    ├── color.md
    ├── links.md
    ├── tools.md
    ├── tables.md
    ├── headings.md
    └── forms.md
├── package.json
├── javascripts
    ├── application.js
    └── private-eye.js
├── Gemfile
├── .circleci
    └── config.yml
├── _data
    ├── header.yml
    ├── navigation.yml
    ├── usa_identifier.yaml
    └── theme.yml
├── LICENSE.md
├── Gemfile.lock
├── _config.yml
├── README.md
├── index.md
└── _includes
    ├── footer.html
    └── components
        └── header.html


/.ruby-version:
--------------------------------------------------------------------------------
1 | 2.7.2


--------------------------------------------------------------------------------
/.bundler-version:
--------------------------------------------------------------------------------
1 | 2.1.4


--------------------------------------------------------------------------------
/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/18F/accessibility/18f-pages/favicon.ico


--------------------------------------------------------------------------------
/images/bkg.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/18F/accessibility/18f-pages/images/bkg.png


--------------------------------------------------------------------------------
/images/sign.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/18F/accessibility/18f-pages/images/sign.jpg


--------------------------------------------------------------------------------
/favicon-16x16.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/18F/accessibility/18f-pages/favicon-16x16.png


--------------------------------------------------------------------------------
/favicon-32x32.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/18F/accessibility/18f-pages/favicon-32x32.png


--------------------------------------------------------------------------------
/images/blacktocat.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/18F/accessibility/18f-pages/images/blacktocat.png


--------------------------------------------------------------------------------
/images/gsa-logo-w100.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/18F/accessibility/18f-pages/images/gsa-logo-w100.png


--------------------------------------------------------------------------------
/images/iterative-design.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/18F/accessibility/18f-pages/images/iterative-design.png


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | _site
2 | .sass-cache
3 | .DS_Store
4 | *.log
5 | .*.swp
6 | .jekyll-metadata
7 | .jekyll-cache
8 | node_modules
9 | 


--------------------------------------------------------------------------------
/.pa11yci:
--------------------------------------------------------------------------------
1 | {
2 |   "defaults": {
3 |     "concurrency": 4,
4 |     "standard": "WCAG2AA",
5 |     "runners": ["axe"],
6 |     "hideElements": ".exampleFailure"
7 |   }
8 | }
9 | 


--------------------------------------------------------------------------------
/.about.yml:
--------------------------------------------------------------------------------
 1 | ---
 2 | name: Accessibility
 3 | full_name: Accessibility Guild
 4 | private:
 5 |   slack: g-accessibility
 6 | leads:
 7 | - nick
 8 | members:
 9 | - nick
10 | - alan
11 | - jackie
12 | owner_type: guild
13 | 


--------------------------------------------------------------------------------
/assets/css/styles.scss:
--------------------------------------------------------------------------------
 1 | ---
 2 | ---
 3 | 
 4 | tbody th {
 5 |   background: #ffffff;
 6 |   color: #000000;
 7 |   text-align: left;
 8 |   font-weight: normal;
 9 | }
10 | 
11 | .highlight .m {
12 |   color: #007B7D;
13 | }
14 | 
15 | .highlight .nb {
16 |   color: #0077A1;
17 | }
18 | 


--------------------------------------------------------------------------------
/_sass/_uswds-theme-settings.scss:
--------------------------------------------------------------------------------
 1 | // Just put any changed settings in here!
 2 | 
 3 | $theme-show-notifications: false;
 4 | $theme-font-type-sans: "helvetica";
 5 | $theme-font-role-heading: "sans";
 6 | 
 7 | $theme-color-primary-dark: "blue-80v";
 8 | $theme-color-primary-darker: "blue-90";
 9 | $theme-type-scale-sm: 6;
10 | $theme-type-scale-md: 7;
11 | 


--------------------------------------------------------------------------------
/.github/dependabot.yml:
--------------------------------------------------------------------------------
 1 | version: 2
 2 | updates:
 3 | - package-ecosystem: bundler
 4 |   directory: "/"
 5 |   schedule:
 6 |     interval: daily
 7 |     time: "09:00"
 8 |   open-pull-requests-limit: 10
 9 |   ignore:
10 |   - dependency-name: uswds-jekyll
11 |     versions:
12 |     - 5.2.0
13 |     - 5.3.0
14 |   - dependency-name: jekyll-feed
15 |     versions:
16 |     - 0.15.1
17 | 


--------------------------------------------------------------------------------
/pages/iframeform.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: iframe form
 3 | description: Fill out this form
 4 | permalink: /iframeform/
 5 | page_title: iFrame
 6 | sitemap: false
 7 | ---
 8 | 
 9 | <label for='fname'>First Name&nbsp;</label><input type='text' id='fname'>
10 | 
11 | <label for='mname'>Middle Name&nbsp;</label><input type='text' id='mname'>
12 | 
13 | <label for='lname'>Last Name&nbsp;</label><input type='text' id='lname'>


--------------------------------------------------------------------------------
/images/angle-arrow-down-white.svg:
--------------------------------------------------------------------------------
1 | <?xml version="1.0" encoding="UTF-8"?><svg xmlns="http://www.w3.org/2000/svg" width="64" height="39" viewBox="0 0 64 39"><title>angle-arrow-down-white</title><path fill="#FFF" d="M63.36 4.006L60.155.743C59.727.307 59.235.09 58.68.09s-1.047.217-1.475.653L32 26.403 6.798.742C6.37.307 5.878.09 5.323.09c-.556 0-1.048.217-1.476.653L.642 4.008C.213 4.443 0 4.943 0 5.509c0 .566.214 1.067.642 1.502l29.883 30.426c.427.435.92.653 1.475.653.556 0 1.047-.217 1.474-.653L63.361 7.011c.427-.435.639-.936.639-1.502s-.212-1.066-.64-1.502z"/></svg>


--------------------------------------------------------------------------------
/images/angle-arrow-up-white.svg:
--------------------------------------------------------------------------------
1 | <?xml version="1.0" encoding="UTF-8"?><svg xmlns="http://www.w3.org/2000/svg" width="64" height="39" viewBox="0 0 64 39"><title>angle-arrow-up-white</title><path fill="#FFF" d="M.655 34.187c-.427-.437-.64-.937-.64-1.503 0-.566.213-1.067.64-1.502L30.542.756c.427-.436.918-.653 1.474-.653.555 0 1.048.218 1.474.653l29.884 30.426c.428.435.642.936.642 1.502s-.213 1.066-.642 1.501l-3.206 3.265c-.427.436-.919.653-1.475.653-.555 0-1.047-.217-1.475-.653L32.016 11.79 6.81 37.45c-.427.436-.919.653-1.474.653-.556 0-1.048-.217-1.475-.653L.655 34.187z"/></svg>


--------------------------------------------------------------------------------
/pages/alternativeversions.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Alternative versions
 3 | description: 'How we deal with Alternative Versions'
 4 | permalink: /alternative-versions/
 5 | page_title: Alternative versions
 6 | layout: post
 7 | sidenav: docs
 8 | ---
 9 | Alternate versions of web pages should only be used when the main page can't be made accessible. There are very few instances where they would be necessary. Live dynamic mapping applications are one example.
10 | 
11 | In a situation where an alternate version is provided, it must provide the same information and provide similar functions.
12 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "18f-accessibility",
 3 |   "description": "This repo will contain the guidelines and best practices for 508 accessibility at 18F.  The site is in draft.",
 4 |   "scripts": {
 5 |     "start": "bundle exec jekyll serve",
 6 |     "start-detached": "bundle exec jekyll serve --detach",
 7 |     "pa11y-ci:home": "pa11y-ci http://localhost:4000",
 8 |     "pa11y-ci:sitemap": "pa11y-ci --sitemap http://localhost:4000/sitemap.xml --sitemap-exclude \"/*.pdf\""
 9 |   },
10 |   "author": "18F",
11 |   "license": "CC0-1.0",
12 |   "devDependencies": {
13 |     "pa11y-ci": "^2.4.0"
14 |   }
15 | }
16 | 


--------------------------------------------------------------------------------
/assets/js/time-outs.js:
--------------------------------------------------------------------------------
 1 | window.addEventListener('DOMContentLoaded', function () {
 2 |   var timer,
 3 |     pForm = document.getElementById('pForm');
 4 | 
 5 |   Array.from(pForm.getElementsByTagName('input')).map(function (el) {
 6 |     el.addEventListener('input', function () {
 7 |       if (timer) {
 8 |         clearTimeout(timer);
 9 |       }
10 | 
11 |       timer = setTimeout(function () {
12 |         var c = confirm('Would you like more time to complete the form?'),
13 |           timer
14 |         if (c == true) {
15 |           clearTimeout(timer);
16 |         } else {
17 |           pForm.reset();
18 |         }
19 |       }, 2000);
20 |     })
21 |   });
22 | });
23 | 


--------------------------------------------------------------------------------
/assets/js/keyboard-access.js:
--------------------------------------------------------------------------------
 1 | window.addEventListener('DOMContentLoaded', function() {
 2 |   var moveFocusLinks = document.getElementsByClassName('moveFocus');
 3 |   var keyboardTrapLinks = document.getElementsByClassName('keyboardTrap');
 4 | 
 5 |   function handleFocus() {
 6 |     keyboardTrapLinks[0].focus();
 7 |   }
 8 | 
 9 |   Array.from(moveFocusLinks).map(function(el) {
10 |     el.addEventListener('focus', handleFocus);
11 |   });
12 | 
13 |   Array.from(keyboardTrapLinks).map(function(el) {
14 |     el.addEventListener('click', function() {
15 |       Array.from(moveFocusLinks).map(function(el) {
16 |         el.removeEventListener('focus', handleFocus);
17 |       });
18 |     });
19 |   });
20 | });
21 | 


--------------------------------------------------------------------------------
/.github/workflows/pa11y.yml:
--------------------------------------------------------------------------------
 1 | name: pa11y tests
 2 | 
 3 | on: [pull_request]
 4 | 
 5 | jobs:
 6 |   build:
 7 |     name: Building site and running pa11y-ci tests
 8 |     runs-on: ubuntu-20.04
 9 | 
10 |     steps:
11 |       - name: Checkout source.
12 |         uses: actions/checkout@v2
13 | 
14 |       - name: Install jekyll site dependencies.
15 |         uses: ruby/setup-ruby@v1
16 |         with:
17 |           ruby-version: 2.7.2
18 |           bundler-cache: true
19 | 
20 |       - name: Install pa11y-ci dependencies.
21 |         run: npm install
22 | 
23 |       - name: Start up jekyll server.
24 |         run: npm run start-detached
25 | 
26 |       - name: Run pa11y-ci.
27 |         run: npm run pa11y-ci:sitemap
28 | 
29 | 


--------------------------------------------------------------------------------
/assets/js/flashing.js:
--------------------------------------------------------------------------------
 1 | window.addEventListener('DOMContentLoaded', function () {
 2 |   console.log('foo')
 3 |   var blinking = false,
 4 |     interval,
 5 |     blinkEl = document.getElementsByClassName('blink')[0],
 6 |     blinkBtn = document.getElementById('blinkbutton');
 7 | 
 8 |   function toggleBlinking(el) {
 9 |     var display = el.style.display;
10 |     if (display === 'inline') {
11 |       el.style.display = 'none';
12 |     } else {
13 |       el.style.display = 'inline';
14 |     }
15 |   }
16 | 
17 |   blinkBtn.addEventListener('click', function () {
18 |     if (!blinking) {
19 |       blinkBtn.innerText = 'Click to stop blinking'
20 |       interval = setInterval(function () {
21 |         toggleBlinking(blinkEl)
22 |       }, 200);
23 |       blinking = true;
24 |     } else {
25 |       clearInterval(interval);
26 |       blinkBtn.innerText = 'Click to see non-compliant flashing';
27 |       blinkEl.style.display = 'none';
28 |       blinking = false;
29 |     }
30 |   })
31 | });
32 | 


--------------------------------------------------------------------------------
/pages/pagetitles.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Page titles
 3 | description: 'How we deal with page titles'
 4 | permalink: /page-titles/
 5 | page_title: Page titles
 6 | layout: post
 7 | sidenav: docs
 8 | ---
 9 | Page titles are important because they help a user navigate their browser. Most users have multiple tabs open at once. It's easier to jump between pages if each page title is unique. It's also helpful to have the unique portion first, usually the name of the page.
10 | 
11 | ## Testing
12 | 
13 | 1. Check that the title shown in the tab for the page is unique and describes the page accurately.
14 |   * The title should be in plain English.
15 |   * The title should describe the web site as well as the specific page being displayed by the site.
16 | 
17 | ## Examples
18 | 
19 | ```html
20 | <title>Page Titles - 18F Accessibility Guide</title>
21 | ```
22 | 
23 | > The title for this page is 'Page Titles - 18F Accessibility Guide'. The first half is the name of this page and the second is the name of the site.
24 | 


--------------------------------------------------------------------------------
/pages/gov-resources.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Government Accessibility Resources
 3 | description: 'Other accessibility resources from the U.S. Government'
 4 | permalink: /gov-resources/
 5 | page_title: Government Accessibility Resources
 6 | layout: post
 7 | ---
 8 | This 18F Accessibility Guide is just one of many helpful accessibility sites and resources available from the U.S. Government. Here are some others:
 9 | 
10 | * [Accessibility for Teams](https://accessibility.digital.gov/) - role-based accessibility guidance for software teams from GSA’s TTS/18F group
11 | * [Section508.gov](https://section508.gov/) - the GSA Government-wide IT Accessibility Program
12 | * [21st Century Integrated Digital Experience Act](https://digital.gov/resources/21st-century-integrated-digital-experience-act/?dg) - explainer page on Digital.gov
13 | * [The U.S. Web Design System (USWDS)](https://designsystem.digital.gov/) - a design system for the federal government with accessibility baked in
14 | * [DHS Trusted Tester Process](https://www.dhs.gov/trusted-tester) - a common testing approach for accessibility compliance and conformity from the U.S. Department of Homeland Security
15 | 


--------------------------------------------------------------------------------
/pages/timeouts.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Timeouts
 3 | description: 'How we deal with Time Outs'
 4 | permalink: /timeouts/
 5 | page_title: Timeouts
 6 | layout: post
 7 | sidenav: docs
 8 | scripts:
 9 | - assets/js/time-outs.js
10 | ---
11 | If timeouts are used, you must give the user at least 20 seconds to easily request more time.
12 | 
13 | ## Testing
14 | 
15 | 1. Identify any timeouts on the page.
16 |   * Contact the developer to find these.
17 | 2. Trigger the time out.
18 |   * __If you're not able to request more time or the request lasts less than 20 seconds, it's a failure__.
19 | 
20 | ## Examples
21 | 
22 | ### Passes
23 | 
24 | Fill out this form
25 | 
26 | <form id='pForm'>
27 | <label for='t1'>Field 1</label>&nbsp;<input type='text' id='t1'><br>
28 | <label for='t2'>Field 2</label>&nbsp;<input type='text' id='t2'><br>
29 | <label for='t3'>Field 3</label>&nbsp;<input type='text' id='t3'><br>
30 | <label for='t4'>Field 4</label>&nbsp;<input type='text' id='t4'><br>
31 | <label for='t5'>Field 5</label>&nbsp;<input type='text' id='t5'><br>
32 | </form>
33 | 
34 | > This passes because a timeout does occur, but you are given more than 20 seconds to request more time.
35 | 


--------------------------------------------------------------------------------
/javascripts/application.js:
--------------------------------------------------------------------------------
 1 | document.addEventListener('DOMContentLoaded', function() {
 2 |   PrivateEye({
 3 |     defaultMessage: "This link is private to GSA.",
 4 |     ignoreUrls: [
 5 |       'gsa-tts.slack.com',
 6 |       'anywhere.gsa.gov',
 7 |       'bookit.gsa.gov',
 8 |       'calendar.gsa.gov',
 9 |       'connect.gsa.gov',
10 |       'docs.google.com',
11 |       'drive.google.com',
12 |       'ea.gsa.gov',
13 |       'email.gsa.gov',
14 |       'gcims.gsa.gov',
15 |       'github.com/18F/Accessibility_Reviews',
16 |       'github.com/18F/blog-drafts',
17 |       'github.com/18F/codereviews',
18 |       'github.com/18F/DevOps',
19 |       'github.com/18F/Infrastructure',
20 |       'github.com/18F/security-incidents',
21 |       'github.com/18F/staffing-and-resources',
22 |       'github.com/18F/team-api.18f.gov',
23 |       'github.com/18F/writing-lab',
24 |       'gkey.gsa.gov',
25 |       'gsa-tts.slack.com',
26 |       'gsa.my.salesforce.com',
27 |       'gsaolu.gsa.gov',
28 |       'hrprod.hr.gsa.gov',
29 |       'insite.gsa.gov',
30 |       'mail.gsa.gov',
31 |       'meet.gsa.gov',
32 |       'pages-internal.18f.gov',
33 |       'tock.18f.gov'
34 |     ]
35 |   });
36 | }, false );
37 | 


--------------------------------------------------------------------------------
/Gemfile:
--------------------------------------------------------------------------------
 1 | source 'https://rubygems.org'
 2 | 
 3 | # Hello! This is where you manage which Jekyll version is used to run.
 4 | # When you want to use a different version, change it below, save the
 5 | # file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
 6 | #
 7 | #     bundle exec jekyll serve
 8 | #
 9 | # This will help ensure the proper Jekyll version is running.
10 | # Happy Jekylling!
11 | gem 'jekyll', '~> 4.2.2'
12 | gem 'jekyll-sitemap', '>= 1.4.0'
13 | 
14 | # This is the default theme for new Jekyll sites. You may change this to anything you like.
15 | gem 'uswds-jekyll', '~> 5.3', '>= 5.3.0'
16 | 
17 | # If you want to use GitHub Pages, remove the "gem "jekyll"" above and
18 | # uncomment the line below. To upgrade, run `bundle update github-pages`.
19 | # gem "github-pages", group: :jekyll_plugins
20 | 
21 | # If you have any plugins, put them here!
22 | group :jekyll_plugins do
23 |   gem "jekyll-feed", "~> 0.17"
24 | end
25 | 
26 | # Windows does not include zoneinfo files, so bundle the tzinfo-data gem
27 | gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby]
28 | 
29 | # Performance-booster for watching directories on Windows
30 | gem "wdm", "~> 0.1.0" if Gem.win_platform?
31 | 


--------------------------------------------------------------------------------
/pages/language.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Language
 3 | description: 'How we tell assistive technology what language a page is in'
 4 | permalink: /language/
 5 | page_title: Language
 6 | layout: post
 7 | sidenav: docs
 8 | ---
 9 | Setting the language of your site allows assistive technology to interact with your content correctly. Assistive technology will read foreign languages, but it needs to know the main language of the page and when any content’s language differs from the default language for the page.
10 | 
11 | ## Testing
12 | 
13 | 1. Open the inspector panel.
14 | 2. Locate the main ```html``` tag.
15 |   * __If the ```lang``` attribute isn't set to the correct language, this is a failure.__
16 | 3. Identify any content that differs from the default language. Make sure the content has its own ```lang``` attribute set with that language.
17 |   * __Any alternate language content not set constitutes a failure__.
18 | 
19 | ## Examples
20 | 
21 | ### Failure
22 | 
23 | Sus ojos son verdes.
24 | 
25 | > This text is Spanish and lacks a ```lang``` attribute.
26 | 
27 | ### Passes
28 | 
29 | <p lang="es">Sus ojos son verdes.</p>
30 | 
31 | > This text passes because the ```lang="es"``` attribute identifies its content as Spanish.
32 | 


--------------------------------------------------------------------------------
/pages/flashing.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Flashing
 3 | description: 'How we deal with flashing'
 4 | permalink: /flashing/
 5 | page_title: Flashing
 6 | layout: post
 7 | sidenav: docs
 8 | scripts:
 9 | - assets/js/flashing.js
10 | ---
11 | Flashing is generally a bad idea. It can cause all sorts of issues, from seizures to motion sickness. If you absolutely must have a flashing element there are a few things to consider.
12 | ## Testing
13 | 
14 | * Failure at any step constitutes a 508 compliance issue
15 | 
16 | 1. Look for elements that contain flashing
17 |   * Scrolling or blinking text
18 |   * Scrolling or blinking page elements
19 |   * Videos that contain flickering or flashing
20 |   * GIFs that contain flickering or flashing
21 | 2. Check if you can determine the frequency of "flashing."
22 | 3. Check that the rate of flashing is less than 3 Hz (3 times a second), or scroll delay is set to >= 400.
23 | 
24 | ## Examples
25 | 
26 | ### Fails
27 | <button type='button' id='blinkbutton'>Click to see non-compliant flashing</button>
28 | <span class='blink' style='display:none;'>This text is blinking</span>
29 | 
30 | > ___Failure:___ This blinking text fails because the rate of flashing can't be determined and its greater than 3 Hz.
31 | 


--------------------------------------------------------------------------------
/.circleci/config.yml:
--------------------------------------------------------------------------------
 1 | version: 2
 2 | jobs:
 3 |   build:
 4 |     docker:
 5 |       - image: circleci/ruby:2.7-node-browsers
 6 |     environment:
 7 |       ACCESSLINT_MASTER_BRANCH: 18f-pages
 8 |     steps:
 9 |       - checkout
10 |       - run:
11 |           name: Display versions
12 |           command: |
13 |             echo $(ruby --version)
14 |             echo $(node --version)
15 |             echo $(npm --version)
16 |       - run: sudo npm install -g axe-cli@3.2.0 --unsafe-perm
17 |       - run: gem install bundler
18 |       - run: bundle install
19 |       - run: bundle exec jekyll build
20 |       - store_artifacts:
21 |           path: /tmp
22 |       - run: mkdir test-reports
23 |       - run:
24 |           name: Download Selenium
25 |           command: curl -O http://selenium-release.storage.googleapis.com/3.5/selenium-server-standalone-3.5.3.jar
26 |       - run:
27 |           name: Start Selenium
28 |           command: java -jar selenium-server-standalone-3.5.3.jar -log test-reports/selenium.log
29 |           background: true
30 |       - run:
31 |           name: test
32 |           command: bundle exec jekyll serve --detach && axe http://localhost:4000
33 | workflows:
34 |   version: 2
35 |   commit:
36 |     jobs:
37 |       - build
38 | 


--------------------------------------------------------------------------------
/pages/iframes.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Inline frames (iframes)
 3 | description: 'How we deal with iframes'
 4 | permalink: /iframes/
 5 | page_title: iframes
 6 | layout: post
 7 | sidenav: docs
 8 | ---
 9 | When using `iframe`s, it’s important that all content contained in them is accessible.
10 | 
11 | ## Testing
12 | 
13 | 1. Identify all `iframe`s on a page.
14 | 2. Using the keyboard, navigate to each `iframe` to ensure content is accessible.
15 | 3. Check the `title` or `name` attribute of each `iframe` for a description of the content.
16 | 
17 | ## Examples
18 | 
19 | 
20 | ### Failures
21 | 
22 | <iframe src="../iframeform/" class="exampleFailure"></iframe>
23 | 
24 | ```html
25 | <iframe src="../iframeform/"></iframe>
26 | ```
27 | 
28 | > This `iframe` doesn’t have a `title` or `name`.
29 | 
30 | <iframe src="../iframeform/" name='Provide an address form' class="exampleFailure"></iframe>
31 | 
32 | ```html
33 | <iframe src="../iframeform/" name='Provide an address form'></iframe>
34 | ```
35 | 
36 | > This `name` isn’t correct.
37 | 
38 | ### Passes
39 | 
40 | <iframe src="../iframeform/" title='Provide Name Form'></iframe>
41 | 
42 | ```html
43 | <iframe src="../iframeform/" title='Provide Name Form'></iframe>
44 | ```
45 | 
46 | > Correct `title` is provided. This would also pass if this information was in a `name` attribute.
47 | 
48 | 


--------------------------------------------------------------------------------
/_data/header.yml:
--------------------------------------------------------------------------------
 1 | # This is the configuration for the site header.
 2 | 
 3 | # Set header title differently from the site's title (as defined in _config.yml).
 4 | # Uncomment the following line to use the header title.
 5 | # title: Header title
 6 | 
 7 | # Show or hide the official USA banner at the top of the site.
 8 | # Comment out to the following line to hide.
 9 | usa_banner: true
10 | 
11 | # This setting changes the TLD used as an argument for trust in banner.html.
12 | # If options besides .mil and .gov are added, it may be worth adding a JS
13 | # determiner or other automated feature. If undefined, the default is .gov
14 | # government_tld: .mil
15 | 
16 | # Defines the type of header.
17 | # Header types can be 'basic', 'basic-mega', 'extended' or 'extended-mega'.
18 | # https://designsystem.digital.gov/components/headers/
19 | type: extended
20 | 
21 | # Configuration for site header logo
22 | # If the logo is external add external: true
23 | # logo:
24 | #  src: https://18f.gsa.gov/assets/img/logos/18f-logo.svg
25 | #  alt: 18F
26 | #  external: true
27 | 
28 | title: Accessibility Guide
29 | 
30 | logo:
31 |   src: /images/18f-logo-black.svg
32 |   alt: 18f
33 | 
34 | # this is a key into _data/navigation.yml
35 | # primary:
36 | # links: primary
37 | 
38 | # this is a key into _data/navigation.yml
39 | primary:
40 |   links: primary
41 | secondary:
42 |   links: secondary
43 | 


--------------------------------------------------------------------------------
/images/18f-logo-black.svg:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="utf-8"?>
 2 | <!-- Generator: Adobe Illustrator 19.1.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
 3 | <svg version="1.1" id="Black_w_x2F_white_type" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
 4 | 	 x="0px" y="0px" viewBox="0 0 333 333" enable-background="new 0 0 333 333" xml:space="preserve">
 5 | <path d="M327.3,0H5.7C2.5,0,0,2.5,0,5.7v321.6c0,3.1,2.5,5.7,5.7,5.7h321.6c3.1,0,5.7-2.5,5.7-5.7V5.7C333,2.5,330.5,0,327.3,0z"/>
 6 | <path fill="#FFFFFF" d="M98,229.3c0,1.1-0.9,2-2,2H83.5c-1.1,0-2-0.9-2-2V117.4H65.2c-1.1,0-2-0.9-2-2v-11.9c0-1.1,0.9-2,2-2h30.8
 7 | 	c1.1,0,2,0.9,2,2V229.3z"/>
 8 | <path fill="#FFFFFF" d="M269.8,115.4c0,1.1-0.9,2-2,2h-34.4v39h28.3c1.1,0,2,0.9,2,2v11.9c0,1.1-0.9,2-2,2h-28.3v57.1
 9 | 	c0,1.1-0.9,2-2,2h-12.5c-1.1,0-2-0.9-2-2V103.5c0-1.1,0.9-2,2-2h48.9c1.1,0,2,0.9,2,2V115.4z"/>
10 | <path fill="#FFFFFF" d="M157.5,233.4c-21.9,0-39.8-17.9-39.8-39.8c0-13.2,6.4-25.1,17.1-32.5c-7.7-6.6-12.3-16.3-12.3-26.4
11 | 	c0-19.3,15.7-35,35-35c19.3,0,35,15.7,35,35c0,10.2-4.6,19.8-12.3,26.4c10.7,7.4,17.1,19.4,17.1,32.5
12 | 	C197.3,215.5,179.4,233.4,157.5,233.4z M157.5,169.6c-13.2,0-23.9,10.7-23.9,23.9c0,13.2,10.7,23.9,23.9,23.9
13 | 	c13.2,0,23.9-10.7,23.9-23.9C181.4,180.4,170.7,169.6,157.5,169.6z M157.5,153.8c10.6,0,19.1-8.6,19.1-19.1
14 | 	c0-10.6-8.6-19.1-19.1-19.1s-19.1,8.6-19.1,19.1C138.4,145.2,146.9,153.8,157.5,153.8z"/>
15 | </svg>
16 | 


--------------------------------------------------------------------------------
/pages/css.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: CSS dependence
 3 | description: 'How we deal with CSS'
 4 | permalink: /css/
 5 | page_title: CSS dependence
 6 | layout: post
 7 | sidenav: docs
 8 | ---
 9 | Cascading style sheets ([CSS](https://www.section508.gov/content/glossary/#sectionC)) allow us to add and manage styles (e.g., fonts, colors, size, spacing) on web pages. CSS dependence refers to sites that rely on CSS to be functional or understandable. This is a concern for accessibility because most assistive technology ignores CSS. 
10 | 
11 | For example, images displayed through CSS are completely ignored by assistive technology. Images loaded by CSS do not have alt attributes and would require the images content to be displayed in some other manner on the page. It is recommended that all CSS images be decorative and content images be on the page with `<img>` tags.
12 | 
13 | Another common CSS dependence issue is content order. Content can be reordered with CSS. This can be an issue because assistive technology will read the content in a different order. Content should be ordered without CSS. 
14 | 
15 | ## Testing
16 | 
17 | 1. Disable CSS
18 | 2. Check for missing information (images, text, etc)
19 | 3. Check for code or other items the developer doesn't want you to see
20 |   * Confusing elements shouldn't be present such as CSS, JavaScript, or other code, etc
21 | 4. Check for overlapping text
22 | 5. Check that the content order makes sense with and without CSS
23 | 


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
 1 | As a work of the United States Government, this project is in the
 2 | public domain within the United States.
 3 | 
 4 | Additionally, we waive copyright and related rights in the work
 5 | worldwide through the CC0 1.0 Universal public domain dedication.
 6 | 
 7 | ## CC0 1.0 Universal Summary
 8 | 
 9 | This is a human-readable summary of the
10 | [Legal Code (read the full text)](https://creativecommons.org/publicdomain/zero/1.0/legalcode).
11 | 
12 | ### No Copyright
13 | 
14 | The person who associated a work with this deed has dedicated the work to
15 | the public domain by waiving all of his or her rights to the work worldwide
16 | under copyright law, including all related and neighboring rights, to the
17 | extent allowed by law.
18 | 
19 | You can copy, modify, distribute and perform the work, even for commercial
20 | purposes, all without asking permission.
21 | 
22 | ### Other Information
23 | 
24 | In no way are the patent or trademark rights of any person affected by CC0,
25 | nor are the rights that other persons may have in the work or in how the
26 | work is used, such as publicity or privacy rights.
27 | 
28 | Unless expressly stated otherwise, the person who associated a work with
29 | this deed makes no warranties about the work, and disclaims liability for
30 | all uses of the work, to the fullest extent permitted by applicable law.
31 | When using or citing the work, you should not imply endorsement by the
32 | author or the affirmer.
33 | 


--------------------------------------------------------------------------------
/_data/navigation.yml:
--------------------------------------------------------------------------------
 1 | # _data/navigation.yml
 2 | primary:
 3 |   - text: Home
 4 |     href: /
 5 |   - text: Other .Gov Accessibility Sites
 6 |     href: /gov-resources/
 7 |   - text: More 18F guides
 8 |     href: https://18f.gsa.gov/guides/
 9 |     external: true
10 | 
11 | secondary:
12 |   - text: More 18F guides
13 |     href: https://18f.gsa.gov/guides/
14 |     external: true
15 | 
16 | docs:
17 |   - text: Checklist
18 |     href: /checklist/
19 |   - text: Tools
20 |     href: /tools/
21 |   - text: Keyboard access
22 |     href: /keyboard/
23 |   - text: Images
24 |     href: /images/
25 |   - text: Color and contrast
26 |     href: /color/
27 |   - text: Forms
28 |     href: /forms/
29 |   - text: Flashing
30 |     href: /flashing/
31 |   - text: Page titles
32 |     href: /page-titles/
33 |   - text: Headings
34 |     href: /headings/
35 |   - text: Hidden content
36 |     href: /hidden-content/
37 |   - text: Landmarks
38 |     href: /landmarks/
39 |   - text: Multimedia
40 |     href: /multimedia/
41 |   - text: Timeouts
42 |     href: /timeouts/
43 |   - text: Language
44 |     href: /language/
45 |   - text: Tables
46 |     href: /tables/
47 |   - text: CSS dependence
48 |     href: /css/
49 |   - text: Inline frames
50 |     href: /iframes/
51 |   - text: Links and repetitive content
52 |     href: /links/
53 |   - text: Alternative versions
54 |     href: /alternative-versions/
55 |   - text: Writing guide
56 |     href: /writing-guide/
57 |   - text: Trainings and videos
58 |     href: /training-videos/
59 | 


--------------------------------------------------------------------------------
/pages/multimedia.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Multimedia
 3 | description: 'How we deal with multimedia'
 4 | permalink: /multimedia/
 5 | page_title: Multimedia
 6 | layout: post
 7 | sidenav: docs
 8 | ---
 9 | When using multimedia, we must provide means for everyone to consume the media. Multimedia is anything that uses audio and video.
10 | 
11 | ## Captioning
12 | 
13 | Videos with audio require synchronized captioning. Captioning can be either closed, meaning they can be turned off, or open captioning, meaning it is baked into the video. Anything said in the video must be included in the captioning, and anything written in the captioning must be said in the video. This includes names, sounds, and descriptions. In other words, the captions and audio should be equivalent. WCAG requires pre recorded video to be captioned at A, while live video requires captioning at AA. 
14 | 
15 | ## Audio description
16 | 
17 | Audio description ensures any information displayed visually is conveyed via audio. This can be done a couple of ways. The script for the video can be written in a way that all visual information is described by the narrator. The other way is to add a separate audio track that describes the visual content. This can be done with a special player or a separate version of the video with the audio baked in.
18 | 
19 |  Some examples of when audio descriptions should be used are scene transitions, characters, actions and text on screen.  
20 | 
21 | ## Keyboard access
22 | 
23 | Just a note about keyboard access. All video controls should be accessible via the keyboard, but it's also worth noting that time stamp information should be available to screen readers as well.
24 | 


--------------------------------------------------------------------------------
/images/Slack_Mark.svg:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="utf-8"?>
 2 | <!-- Generator: Adobe Illustrator 23.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
 3 | <svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
 4 | 	 viewBox="0 0 270 270" style="enable-background:new 0 0 270 270;" xml:space="preserve">
 5 | <style type="text/css">
 6 | 	.st0{fill:#E01E5A;}
 7 | 	.st1{fill:#36C5F0;}
 8 | 	.st2{fill:#2EB67D;}
 9 | 	.st3{fill:#ECB22E;}
10 | </style>
11 | <g>
12 | 	<g>
13 | 		<path class="st0" d="M99.4,151.2c0,7.1-5.8,12.9-12.9,12.9c-7.1,0-12.9-5.8-12.9-12.9c0-7.1,5.8-12.9,12.9-12.9h12.9V151.2z"/>
14 | 		<path class="st0" d="M105.9,151.2c0-7.1,5.8-12.9,12.9-12.9s12.9,5.8,12.9,12.9v32.3c0,7.1-5.8,12.9-12.9,12.9
15 | 			s-12.9-5.8-12.9-12.9V151.2z"/>
16 | 	</g>
17 | 	<g>
18 | 		<path class="st1" d="M118.8,99.4c-7.1,0-12.9-5.8-12.9-12.9c0-7.1,5.8-12.9,12.9-12.9s12.9,5.8,12.9,12.9v12.9H118.8z"/>
19 | 		<path class="st1" d="M118.8,105.9c7.1,0,12.9,5.8,12.9,12.9s-5.8,12.9-12.9,12.9H86.5c-7.1,0-12.9-5.8-12.9-12.9
20 | 			s5.8-12.9,12.9-12.9H118.8z"/>
21 | 	</g>
22 | 	<g>
23 | 		<path class="st2" d="M170.6,118.8c0-7.1,5.8-12.9,12.9-12.9c7.1,0,12.9,5.8,12.9,12.9s-5.8,12.9-12.9,12.9h-12.9V118.8z"/>
24 | 		<path class="st2" d="M164.1,118.8c0,7.1-5.8,12.9-12.9,12.9c-7.1,0-12.9-5.8-12.9-12.9V86.5c0-7.1,5.8-12.9,12.9-12.9
25 | 			c7.1,0,12.9,5.8,12.9,12.9V118.8z"/>
26 | 	</g>
27 | 	<g>
28 | 		<path class="st3" d="M151.2,170.6c7.1,0,12.9,5.8,12.9,12.9c0,7.1-5.8,12.9-12.9,12.9c-7.1,0-12.9-5.8-12.9-12.9v-12.9H151.2z"/>
29 | 		<path class="st3" d="M151.2,164.1c-7.1,0-12.9-5.8-12.9-12.9c0-7.1,5.8-12.9,12.9-12.9h32.3c7.1,0,12.9,5.8,12.9,12.9
30 | 			c0,7.1-5.8,12.9-12.9,12.9H151.2z"/>
31 | 	</g>
32 | </g>
33 | </svg>
34 | 


--------------------------------------------------------------------------------
/pages/landmarks.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Landmarks
 3 | description: 'Proper page layout using Landmarks'
 4 | permalink: /landmarks/
 5 | page_title: Landmark
 6 | layout: post
 7 | sidenav: docs
 8 | ---
 9 | 
10 | All elements on a page should be contained in a landmark element. This helps users of AT quickly navigate a page. HTML5 provides built in landmark elements such as `main`, `nav`, `aside`, `header`, `footer`. When using HTML5 elements, don't define role.
11 | 
12 | When using HTML4 use ARIA role on divs to define landmark elements such as `role="main"`.
13 | 
14 | ## Testing
15 | 
16 | 1. Identify content in the source code
17 | 2. Check that all rendered content is contained by a landmark element
18 | 
19 | ## Examples
20 | 
21 | ### HTML5
22 | 
23 | ```html
24 | <!DOCTYPE html>
25 | <html lang="en">
26 |   <head>
27 |     <meta charset="UTF-8">
28 |     <title>Sample page</title>
29 |   </head>
30 |   <body>
31 |     <header>
32 |       <h1>Site Name</h1>
33 |     </header>
34 |     <nav>
35 |       <ul>
36 |         <li>Home</li>
37 |         <li><a href="./otherpage/">Other Page</a></li>
38 |       </ul>
39 |     </nav>
40 |     <main>
41 |       <article>Here's an article</article>
42 |     </main>
43 |     <footer>Footer</footer>
44 |   </body>
45 | </html>
46 | ```
47 | 
48 | ### HTML4
49 | 
50 | ```html
51 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
52 |         "http://www.w3.org/TR/html4/strict.dtd">
53 | <html lang="en">
54 |   <head>
55 |     <meta charset="UTF-8">
56 |     <title>Sample page</title>
57 |   </head>
58 |   <body>
59 |     <div role='banner' id='header'>
60 |       <h1>Site Name</h1>
61 |     </div>
62 |     <div role='navigation' id='main-nav'>
63 |       <ul>
64 |         <li>Home</li>
65 |         <li><a href="./otherpage/">Other Page</a></li>
66 |       </ul>
67 |     </div>
68 |     <div role="main">
69 |       <div>Here's an article</div>
70 |     </div>
71 |     <div role='contentinfo'>Footer</div>
72 |   </body>
73 | </html>
74 | ```
75 | 


--------------------------------------------------------------------------------
/pages/videos.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Training and videos
 3 | description: 'Videos and trainings from around the web'
 4 | permalink: /training-videos/
 5 | page_title: Accessibility training and videos
 6 | layout: post
 7 | sidenav: docs
 8 | ---
 9 | 
10 | There are tons of great talks and videos about accessibility online. This is a collection of training and videos we found useful.
11 | 
12 | ## W3C - Digital Accessibility Foundations Free Online Course
13 | 
14 | A free, self-paced training course designed for technical and non-technical audiences, including developers, designers, content authors, and project/product managers. [Explore the course overview and syllabus on w3.org](https://www.w3.org/WAI/fundamentals/foundations-course/) or [enroll in the course directly on edX](https://www.edx.org/course/web-accessibility-introduction).
15 | 
16 | ## #ID24 2016: The Web Accessibility Basics w/ Marco Zehe
17 | 
18 | <iframe width="560" height="315" src="https://www.youtube.com/embed/zngSYz3pYl4?list=PL95LOQw9SLWxmcZtzBiFuT9HAJKFJnl2n" allowfullscreen title="#ID24 2016: The Web Accessibility Basics w/ Marco Zehe"></iframe>
19 | 
20 | ## 18F Design Presents: Aaron Gustafson
21 | 
22 | <iframe width="560" height="315" src="https://www.youtube.com/embed/Fu1L34TLUHM" allowfullscreen title="18F Design Presents: Aaron Gustafson"></iframe>
23 | 
24 | ## Crossing Over: Bringing Mobile Innovations to Accessibility #a11yMTL
25 | 
26 | <iframe width="560" height="315" src="https://www.youtube.com/embed/ZW0j7ehtw2Q" allowfullscreen title="Crossing Over: Bringing Mobile Innovations to Accessibility #a11yMTL"></iframe>
27 | 
28 | ## Accessible SVG Data Visualization
29 | 
30 | <iframe width="420" height="315" src="https://www.youtube.com/embed/W1VUr544i84" allowfullscreen title="Accessible SVG Data Visualization"></iframe>
31 | 
32 | ## Derek Featherstone: Accessibility is a Design Tool
33 | 
34 | <iframe width="560" height="315" src="https://www.youtube.com/embed/LeWAnR4JPM0" allowfullscreen title="Derek Featherstone: Accessibility is a Design Tool"></iframe>
35 | 


--------------------------------------------------------------------------------
/pages/writingguide.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Writing guide
 3 | description: 'When writing about accessibility, here are some things to keep in mind'
 4 | permalink: /writing-guide/
 5 | page_title: Accessibility writing guide
 6 | layout: post
 7 | sidenav: docs
 8 | ---
 9 | 
10 | ## The law
11 | 
12 | Section 508 is part of the 'Rehabilitation Act of 1973.' The law was amended in 1998 to add 508 which requires that government agencies provide equal access to information to disabled employees.
13 | 
14 | The correct way to refer to the law is:
15 | 
16 | * Section 508 of the Rehabilitation Act of 1973, as amended (29 U.S.C. § 794 (d))
17 | * Section 508 of the Rehabilitation Act
18 | * Section 508
19 | 
20 | While related in ways, the Rehabilitation Act is not part of the Americans with Disabilities Act.
21 | 
22 | ## Key words
23 | 
24 | * __Conformance:__ We conform with the standards of Section 508, not the law of Section 508.
25 | 
26 | * __Compliance:__ A government agency is in compliance with the law.
27 | 
28 | ## Talking points
29 | 
30 | * The goal of accessibility at 18F is to build sites that are usable by everyone, not to meet minimum standards
31 | * We focus on building accessibility into every step of a project, from design to each sprint review
32 | * Employing accessibility best practices improves the user experience of all users
33 | * 18F guidelines and best practices are not intended to be a replacement or supplement for [Section 508 Standards](https://www.access-board.gov/ict/#508-chapter-1-application-and-administration), but are tools to achieving these standards in a modern web development consultancy
34 | 
35 | ## Examples
36 | 
37 | [U.S. Web Design System](https://designsystem.digital.gov/)
38 | 
39 | `Accessibility isn’t an optional enhancement, it’s at the core of how we design. Every design, asset, and piece of code we offer should meet or exceed the accessibility standards outlined in Section 508, and our guidance should ensure any project-specific customizations perform well for the broadest possible definition of the public.`
40 | 
41 | 
42 | 
43 | 
44 | 


--------------------------------------------------------------------------------
/_data/usa_identifier.yaml:
--------------------------------------------------------------------------------
 1 | # Identifier data
 2 | 
 3 | identifier_data:
 4 |   - site_name: 18F Accessibility Guide
 5 |     site_email: 18F@gsa.gov
 6 |     site_url: https://accessibility.18f.gov
 7 |     site_about: https://accessibility.18f.gov
 8 |     agency: U.S. General Services Administration
 9 |     agency_acronym: GSA
10 |     agency_logo: gsa-logo-blue.svg
11 |     agency_url: https://www.gsa.gov
12 |     agency_about_url: https://www.gsa.gov/about
13 |     org_primary: Technology Transformation Services
14 |     org_primary_acronym: TTS
15 |     org_primary_url: https://www.gsa.gov/tts/
16 |     org_primary_email: tts-info@gsa.gov
17 |     org_primary_about: https://www.gsa.gov/tts/
18 |     org_primary_bio: "As part of GSA’s Technology Transformation Services (TTS), we apply modern methodologies and technologies to improve the public’s experience with government. We help agencies make their services more accessible, efficient, and effective with modern applications, platforms, processes, personnel, and software solutions."
19 |     org_secondary: 18F
20 |     org_secondary_acronym: 18F
21 |     org_secondary_logo: 18f-logo-blue.svg
22 |     org_secondary_url: https://18f.gsa.gov
23 |     org_secondary_email: 18F@gsa.gov
24 |     org_secondary_about: https://18f.gsa.gov/about/
25 |     org_secondary_bio: "TTS Solutions is a portfolio of products and services that help agencies improve delivery of information and services to the public."
26 |     foia_request_url: "https://www.gsa.gov/reference/freedom-of-information-act-foia"
27 |     fraud_waste_abuse_url: "https://www.gsaig.gov/"
28 |     no_fear_act_url: "https://www.gsa.gov/about-us/organization/office-of-civil-rights/notification-and-federal-employee-antidiscrimination-and-retaliation-act-of-2002"
29 |     budget_performance_url: "https://www.gsa.gov/reference/reports/budget-performance"
30 |     accessibility_url: "https://www.gsa.gov/website-information/accessibility-aids"
31 |     usagov_contact_url: "https://www.usa.gov/contact"
32 |     privacy_policy_url: "https://www.gsa.gov/website-information/website-policies"


--------------------------------------------------------------------------------
/images/18f-logo-blue.svg:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="UTF-8"?>
 2 | <svg width="333px" height="333px" viewBox="0 0 333 333" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
 3 |     <!-- Generator: Sketch 55.2 (78181) - https://sketchapp.com -->
 4 |     <title>18F-Logo-2016-Blue</title>
 5 |     <desc>Created with Sketch.</desc>
 6 |     <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
 7 |         <g id="18F-Logo-2016-Blue" fill-rule="nonzero">
 8 |             <path d="M327.3,0 L5.7,0 C2.5,0 0,2.5 0,5.7 L0,327.3 C0,330.4 2.5,333 5.7,333 L327.3,333 C330.4,333 333,330.5 333,327.3 L333,5.7 C333,2.5 330.5,0 327.3,0 Z" id="Path" fill="#00CFFF"></path>
 9 |             <path d="M98,229.3 C98,230.4 97.1,231.3 96,231.3 L83.5,231.3 C82.4,231.3 81.5,230.4 81.5,229.3 L81.5,117.4 L65.2,117.4 C64.1,117.4 63.2,116.5 63.2,115.4 L63.2,103.5 C63.2,102.4 64.1,101.5 65.2,101.5 L96,101.5 C97.1,101.5 98,102.4 98,103.5 L98,229.3 Z" id="Path" fill="#1C304A"></path>
10 |             <path d="M269.8,115.4 C269.8,116.5 268.9,117.4 267.8,117.4 L233.4,117.4 L233.4,156.4 L261.7,156.4 C262.8,156.4 263.7,157.3 263.7,158.4 L263.7,170.3 C263.7,171.4 262.8,172.3 261.7,172.3 L233.4,172.3 L233.4,229.4 C233.4,230.5 232.5,231.4 231.4,231.4 L218.9,231.4 C217.8,231.4 216.9,230.5 216.9,229.4 L216.9,103.5 C216.9,102.4 217.8,101.5 218.9,101.5 L267.8,101.5 C268.9,101.5 269.8,102.4 269.8,103.5 L269.8,115.4 L269.8,115.4 Z" id="Path" fill="#1C304A"></path>
11 |             <path d="M157.5,233.4 C135.6,233.4 117.7,215.5 117.7,193.6 C117.7,180.4 124.1,168.5 134.8,161.1 C127.1,154.5 122.5,144.8 122.5,134.7 C122.5,115.4 138.2,99.7 157.5,99.7 C176.8,99.7 192.5,115.4 192.5,134.7 C192.5,144.9 187.9,154.5 180.2,161.1 C190.9,168.5 197.3,180.5 197.3,193.6 C197.3,215.5 179.4,233.4 157.5,233.4 Z M157.5,169.6 C144.3,169.6 133.6,180.3 133.6,193.5 C133.6,206.7 144.3,217.4 157.5,217.4 C170.7,217.4 181.4,206.7 181.4,193.5 C181.4,180.4 170.7,169.6 157.5,169.6 Z M157.5,153.8 C168.1,153.8 176.6,145.2 176.6,134.7 C176.6,124.1 168,115.6 157.5,115.6 C147,115.6 138.4,124.2 138.4,134.7 C138.4,145.2 146.9,153.8 157.5,153.8 Z" id="Shape" fill="#1C304A"></path>
12 |         </g>
13 |     </g>
14 | </svg>


--------------------------------------------------------------------------------
/Gemfile.lock:
--------------------------------------------------------------------------------
 1 | GEM
 2 |   remote: https://rubygems.org/
 3 |   specs:
 4 |     addressable (2.8.1)
 5 |       public_suffix (>= 2.0.2, < 6.0)
 6 |     autoprefixer-rails (9.8.6.5)
 7 |       execjs
 8 |     colorator (1.1.0)
 9 |     concurrent-ruby (1.1.10)
10 |     em-websocket (0.5.3)
11 |       eventmachine (>= 0.12.9)
12 |       http_parser.rb (~> 0)
13 |     eventmachine (1.2.7)
14 |     execjs (2.8.1)
15 |     ffi (1.15.5)
16 |     forwardable-extended (2.6.0)
17 |     http_parser.rb (0.8.0)
18 |     i18n (1.12.0)
19 |       concurrent-ruby (~> 1.0)
20 |     jekyll (4.2.2)
21 |       addressable (~> 2.4)
22 |       colorator (~> 1.0)
23 |       em-websocket (~> 0.5)
24 |       i18n (~> 1.0)
25 |       jekyll-sass-converter (~> 2.0)
26 |       jekyll-watch (~> 2.0)
27 |       kramdown (~> 2.3)
28 |       kramdown-parser-gfm (~> 1.0)
29 |       liquid (~> 4.0)
30 |       mercenary (~> 0.4.0)
31 |       pathutil (~> 0.9)
32 |       rouge (~> 3.0)
33 |       safe_yaml (~> 1.0)
34 |       terminal-table (~> 2.0)
35 |     jekyll-autoprefixer (1.0.2)
36 |       autoprefixer-rails (~> 9.3)
37 |     jekyll-feed (0.17.0)
38 |       jekyll (>= 3.7, < 5.0)
39 |     jekyll-sass-converter (2.2.0)
40 |       sassc (> 2.0.1, < 3.0)
41 |     jekyll-sitemap (1.4.0)
42 |       jekyll (>= 3.7, < 5.0)
43 |     jekyll-watch (2.2.1)
44 |       listen (~> 3.0)
45 |     kramdown (2.4.0)
46 |       rexml
47 |     kramdown-parser-gfm (1.1.0)
48 |       kramdown (~> 2.0)
49 |     libv8-node (15.14.0.1)
50 |     liquid (4.0.3)
51 |     listen (3.7.1)
52 |       rb-fsevent (~> 0.10, >= 0.10.3)
53 |       rb-inotify (~> 0.9, >= 0.9.10)
54 |     mercenary (0.4.0)
55 |     mini_racer (0.4.0)
56 |       libv8-node (~> 15.14.0.0)
57 |     pathutil (0.16.2)
58 |       forwardable-extended (~> 2.6)
59 |     public_suffix (5.0.0)
60 |     rb-fsevent (0.11.2)
61 |     rb-inotify (0.10.1)
62 |       ffi (~> 1.0)
63 |     rexml (3.2.5)
64 |     rouge (3.30.0)
65 |     safe_yaml (1.0.5)
66 |     sassc (2.4.0)
67 |       ffi (~> 1.9)
68 |     terminal-table (2.0.0)
69 |       unicode-display_width (~> 1.1, >= 1.1.1)
70 |     unicode-display_width (1.8.0)
71 |     uswds-jekyll (5.4.0)
72 |       jekyll (>= 4.0, < 5)
73 |       jekyll-autoprefixer
74 |       mini_racer
75 | 
76 | PLATFORMS
77 |   ruby
78 | 
79 | DEPENDENCIES
80 |   jekyll (~> 4.2.2)
81 |   jekyll-feed (~> 0.17)
82 |   jekyll-sitemap (>= 1.4.0)
83 |   tzinfo-data
84 |   uswds-jekyll (~> 5.3, >= 5.3.0)
85 | 
86 | BUNDLED WITH
87 |    2.1.4
88 | 


--------------------------------------------------------------------------------
/_config.yml:
--------------------------------------------------------------------------------
 1 | # Welcome to Jekyll!
 2 | #
 3 | # This config file is meant for settings that affect your whole blog, values
 4 | # which you are expected to set up once and rarely edit after that. If you find
 5 | # yourself editing this file very often, consider using Jekyll's data files
 6 | # feature for the data you need to update frequently.
 7 | #
 8 | # For technical reasons, this file is *NOT* reloaded automatically when you use
 9 | # 'bundle exec jekyll serve'. If you change this file, please restart the server process.
10 | 
11 | # Site settings
12 | # These are used to personalize your new site. If you look in the HTML files,
13 | # you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
14 | # You can create any custom variable you would like, and they will be accessible
15 | # in the templates via {{ site.myvariable }}.
16 | title: 18F Accessibility Guide
17 | description: >-
18 |   This is the 18F Accessibility Guide.
19 | baseurl: "" # the subpath of your site, e.g. /blog
20 | url: "https://accessibility.18f.gov" # the base hostname & protocol for your site, e.g. http://example.com
21 | twitter_username: jekyllrb
22 | github_username:  jekyll
23 | 
24 | include: ['pages']
25 | 
26 | # Build settings
27 | markdown: kramdown
28 | theme: uswds-jekyll
29 | plugins:
30 |   - jekyll-feed
31 |   - jekyll-sitemap
32 | 
33 | # Google Analytics & DAP tracking code for handbook
34 | google_analytics_ua: UA-48605964-19
35 | dap_agency: GSA
36 | dap_subagency: TTS
37 | 
38 | # Add search site handle to enable search
39 | search_site_handle: 18f-accessibility
40 | 
41 | scripts:
42 |   - assets/uswds/js/uswds.min.js
43 |   - javascripts/private-eye.js
44 |   - javascripts/application.js
45 | 
46 | exclude:
47 | - CONTRIBUTING.md
48 | - Gemfile
49 | - Gemfile.lock
50 | - LICENSE.md
51 | - README.md
52 | - go
53 | - vendor
54 | - node_modules
55 | 
56 | highlighter: rouge
57 | permalink: pretty
58 | 
59 | incremental: true
60 | 
61 | sass:
62 |   style: compressed
63 | 
64 | # Author/Organization info to be displayed in the templates
65 | author:
66 |   name: 18F
67 |   url: https://18f.gsa.gov
68 | 
69 | # Point the logo URL at a file in your repo or hosted elsewhere by your organization
70 | logourl: /assets/img/18f-logo.png
71 | logoalt: 18F
72 | 
73 | back_link:
74 |   url: "https://guides.18f.gov/"
75 |   text: Read more 18F Guides
76 | 
77 | repos:
78 | - name: Accessibility
79 |   description: Main repository
80 |   url: https://github.com/18F/accessibility
81 | 


--------------------------------------------------------------------------------
/images/gsa-logo-blue.svg:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="UTF-8"?>
 2 | <svg width="178px" height="178px" viewBox="0 0 178 178" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
 3 |     <title>gsa-logo-blue</title>
 4 |     <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
 5 |         <g id="gsa-logo-blue">
 6 |             <rect id="gsa-background-white-on-dark-bg" fill="#FFFFFF" x="0" y="0" width="178" height="178"></rect>
 7 |             <path d="M177.735849,0.00135173191 L177.735849,177.902788 L-1.70530257e-13,177.902788 L-1.70530257e-13,0.00135173191 L177.735849,0.00135173191 Z M34.4426358,91.3873839 C20.0112081,94.1584342 12.7219938,107.170544 12.7219938,119.358096 C12.7219938,128.462011 14.5248662,137.121543 24.9112363,144.204618 C34.4219606,150.691088 48.5958851,150.598912 59.5795012,147.471841 L60.18637,147.295016 L60.1475078,117.327119 L40.0759787,117.327119 L39.9864264,126.140411 L50.384624,126.118446 L50.4454519,140.367389 C50.4454519,140.367389 38.3913827,141.67519 33.2243875,138.973416 C25.3421007,134.850634 22.0878063,127.351901 22.2567727,119.358096 C22.4122219,111.859364 24.6848212,105.72419 31.7864827,101.543959 C39.6062518,96.9452655 51.5833688,98.4345815 58.5785916,102.702184 L58.97657,102.95145 L59.2908476,93.5754999 C52.8819488,91.0747958 43.9182766,89.5676148 34.4426358,91.3873839 Z M124.81301,120.99572 L112.341594,149.052605 L121.693889,149.052605 L145.38637,137.517263 L138.685159,132.216784 L126.52802,138.453337 L131.514221,127.075134 L124.81301,120.99572 Z M152.838637,120.824725 L146.240496,127.264038 L155.44579,149.052267 L165.57871,149.052267 L152.838637,120.824725 Z M83.6054633,91.6513096 C78.9859194,93.2987327 75.1250352,97.3252042 74.021684,101.892368 C69.4257955,120.928133 94.3703182,120.532751 97.5215433,129.724528 C97.7851309,132.74227 97.3120248,135.71608 95.4229794,137.469952 C90.0139722,142.494496 80.8180099,140.188924 75.6347634,137.496906 L75.3345536,137.338158 L74.415376,146.660039 C83.2117713,149.812954 94.2621797,150.243818 101.855534,144.297888 C104.493101,141.660321 107.488876,137.4784 107.237116,131.956576 C106.451422,114.757477 92.0081667,116.85773 83.869051,107.931231 C82.7690791,105.013179 83.6172909,101.165812 86.1027879,99.7921149 C91.088989,97.0328921 98.5725148,98.6110391 103.825683,101.236778 C103.693889,100.844776 105.077725,92.4032103 105.077725,92.4032103 C98.8090679,90.4212334 90.0413967,88.679189 83.6054633,91.6513096 Z M139.035258,90.5910448 L125.436835,120.528527 L135.100028,120.528527 L139.364742,110.88561 L143.3608,120.528527 L152.713096,120.528527 L139.035258,90.5910448 Z" id="Combined-Shape" fill="#005087" fill-rule="nonzero"></path>
 8 |         </g>
 9 |     </g>
10 | </svg>


--------------------------------------------------------------------------------
/_data/theme.yml:
--------------------------------------------------------------------------------
 1 | ## Color configurations
 2 | ## 'primary' - Defines content link color, primary button bg color, return to top link color
 3 | ## 'primary darker' - Defines content link hover color, primary button hover bg color, return to top link hover color
 4 | ## 'base' - Defines header site title, active top nav link color, left nav link color, link color in primary and main footer and text in usa-banner
 5 | ## 'visited' - Defines visited link color
 6 | #
 7 | colors:
 8 |   primary: '#046B99'
 9 |   primary-darker: '#1C304A'
10 | #   base: 'orange'
11 | #   visited: 'red'
12 | #
13 | # # USA banner colors
14 | #   usa-banner:
15 | #     usa-banner-bg: 'LightBlue'
16 | #     usa-banner-text: 'Black'
17 | #     usa-banner-link: 'Gray'
18 | #     usa-banner-link-hover: 'Gray'
19 | #
20 | # # Header colors
21 |   header:
22 |     header-bg: 'white'
23 |     # header-title: '#1C304A'
24 | #     header-link: 'DarkSlateGray'
25 | #     header-link-hover: 'Indigo'
26 | #
27 | # # Alt section colors
28 | #   alt-section:
29 | #     bg-color: '#e6e3d0'
30 | #     header-color: 'DarkSlateGray'
31 | #     text-color: 'Black'
32 | #     link-color: 'red'
33 | #     link-hover-color: 'orange'
34 | #
35 | # # Hero colors
36 | #   hero:
37 | #     hero-bg: 'white'
38 | #     hero-header: 'DarkSlateGray'
39 | #     hero-header-alt: 'DarkSlateGray'
40 | #     hero-text: 'Gray'
41 | #     hero-link: 'DodgerBlue'
42 | #     hero-button-bg: 'DodgerBlue'
43 | #     hero-button-text: 'white'
44 | #
45 | # # Top navigation colors
46 | #   top-navigation:
47 | #     top-nav-bg: 'DarkSlateGray'
48 | #     top-nav-link: 'white'
49 | #     top-nav-link-hover: 'black'
50 | #     top-nav-link-hover-bg: '#6eb7b7'
51 | #     top-nav-link-current: 'black'
52 | #     top-nav-dropdown-bg: '#6eb7b7'
53 | #     top-nav-dropdown-link: 'orange'
54 | #     top-nav-dropdown-link-hover-bg: 'DarkSlateGray'
55 | #
56 | # # Side navigation colors
57 | #   side-navigation:
58 | #     side-nav-bg: 'white'
59 | #     side-nav-link: 'black'
60 | #     side-nav-link-hover: 'white'
61 | #     side-nav-link-hover-bg: 'DarkSlateGray'
62 | #     side-nav-link-current: 'DarkSlateGray'
63 | #
64 | # # Footer colors
65 | #   footer:
66 | #     primary-footer-bg: 'Gainsboro'
67 | #     primary-footer-link: 'black'
68 | #     footer-bg: 'DarkSlateGray'
69 | #     footer-text: 'white'
70 | #     footer-link: 'LightBlue'
71 | #
72 | #
73 | # # Font configurations
74 | # # 'sans' - Defines navigation and body text
75 | # # 'serif' - Defines headings
76 | # # 'normal' - Defines the default font weight
77 | # # 'bold' - Defines the bold font weight
78 | #
79 | fonts:
80 |   sans: >-
81 |       "Helvetica Neue", "Helvetica", "Arial", sans-serif
82 |   serif: >-
83 |       "Helvetica Neue", "Helvetica", "Arial", sans-serif
84 | #   normal: 300
85 | #   bold: 500
86 | 


--------------------------------------------------------------------------------
/javascripts/private-eye.js:
--------------------------------------------------------------------------------
  1 | // https://github.com/18F/private-eye
  2 | (function() {
  3 |   'use strict';
  4 | 
  5 |   var STYLES = 'a.private-link::after { content: "\\1F512"; font-size: 0.75em; vertical-align: baseline; padding-left:2px; }';
  6 |   var STYLES_ID = '_privateEye-styles';
  7 | 
  8 |   var DEFAULT_OPTIONS = {
  9 |     defaultMessage: 'This is a link to a private site, which may or may not be accessible to you.',
 10 |     wrapper: ''
 11 |   };
 12 | 
 13 |   var isString = function(str) { return !!str && typeof str === 'string'; };
 14 |   var isArray = function(arr) { return !!arr && arr.length; };
 15 | 
 16 |   var optionValidators = {
 17 |     defaultMessage: isString,
 18 |     wrapper: isString,
 19 |     ignoreUrls: isArray,
 20 |   };
 21 | 
 22 |   function setStyles() {
 23 |     var styles = document.createElement('style');
 24 |     styles.innerHTML = STYLES;
 25 |     styles.id = STYLES_ID;
 26 |     document.body.appendChild(styles);
 27 |   }
 28 | 
 29 |   function getOptions(opts) {
 30 |     var newObj = {};
 31 | 
 32 |     for (var prop in DEFAULT_OPTIONS) {
 33 |       newObj[prop] = DEFAULT_OPTIONS[prop];
 34 |     }
 35 | 
 36 |     for (var prop in opts) {
 37 |       var val = opts[prop];
 38 | 
 39 |       if (optionValidators[prop](val)) {
 40 |         newObj[prop] = val;
 41 |       }
 42 |     }
 43 | 
 44 |     return newObj;
 45 |   }
 46 | 
 47 |   var PrivateEye = function(opts) {
 48 |     // The old docs recommend calling this as a function. This is here to detect
 49 |     // those cases and make sure backward compatibility stays intact now that the
 50 |     // new syntax is preferred.
 51 |     if (!(this instanceof PrivateEye)) {
 52 |       return new PrivateEye(opts);
 53 |     }
 54 | 
 55 |     // Don't add the styles to the page more than once.
 56 |     if (!document.getElementById(STYLES_ID)) {
 57 |       setStyles();
 58 |     }
 59 | 
 60 |     this.opts = getOptions(opts);
 61 | 
 62 |     this.checkLinks();
 63 |   };
 64 | 
 65 |   PrivateEye.prototype.checkLinks = function() {
 66 |     var self = this;
 67 | 
 68 |     this.opts.ignoreUrls.forEach(function(url) {
 69 |       var hrefValue;
 70 |       var titleValue;
 71 | 
 72 |       // If the `url` is an Object, then parse the properties `message` & `url`
 73 |       if (url === Object(url)) {
 74 |         titleValue = url.message;
 75 |         hrefValue = url.url;
 76 |       } else {
 77 |         hrefValue = url;
 78 |         titleValue = self.opts.defaultMessage;
 79 |       }
 80 | 
 81 |       var wrapper = self.opts.wrapper.length ? self.opts.wrapper + ' ' : '';
 82 |       var selector = wrapper + 'a';
 83 |       var anchors = document.querySelectorAll(selector);
 84 | 
 85 |       Array.prototype.forEach.call(anchors, function(anchor) {
 86 |         var anchorHref = anchor.href.toLowerCase().trim();
 87 | 
 88 |         if (anchorHref.indexOf(hrefValue.toLowerCase()) !== -1) {
 89 |           anchor.className += ' private-link';
 90 |         }
 91 |       });
 92 |     });
 93 |   }
 94 | 
 95 |   if (typeof module === 'object' && typeof module.exports === 'object') {
 96 |     module.exports = PrivateEye;
 97 |   } else {
 98 |     window.PrivateEye = PrivateEye;
 99 |   }
100 | })();
101 | 


--------------------------------------------------------------------------------
/pages/checklist.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Checklist
 3 | description: 'A simple checklist for determining if your site is accessible'
 4 | permalink: /checklist/
 5 | page_title: checklist
 6 | layout: post
 7 | sidenav: docs
 8 | ---
 9 | This checklist helps developers identify potential accessibility issues affecting their websites or applications. It's broken down into three sections of decreasing importance: A, B and C. Please check and address these issues in the order in which they appear.
10 | 
11 | For more detail on accessibility standards, please see [WCAG2.0 AA](https://www.w3.org/TR/WCAG20/) 
12 | 
13 |  * A - Critical issues that will cause serious problems and/or stop most users of assistive technology from using the site
14 |  * B - Issues that may cause problems or increased frustration for certain users
15 |  * C - Minor issues that will cause problems or frustration for a small number of users
16 | 
17 | It is important to note, while B and C are noted as less critical, they are still required to be truly 508 compliant. This checklist should be used as a reference for development and is not a substitute for compliance checks by a section 508 coordinator.
18 | 
19 | ##  A - Critical
20 | 
21 | 1. <a href='../keyboard/'>Site is keyboard accessible</a>
22 |  * All interactions can be accessed with a keyboard
23 | 2. <a href='../keyboard/#keyboard-trap'>Site is free of keyboard traps</a>
24 |  * The keyboard focus is never trapped in a loop
25 | 4. <a href='../forms/'>All `form` inputs have explicit labels</a>
26 | 6. <a href='../images/'>All relevant images use an `img` tag</a>
27 | 5. <a href='../images/'>All images have `alt` attributes</a>
28 | 6. <a href='../multimedia/'>Multimedia is tagged</a>
29 |  * All multimedia has appropriate captioning and audio description
30 | 7. <a href='../color/'>Text has sufficient color contrast</a>
31 |  * All text has a contrast ratio of 4.5:1 with the background
32 | 
33 | ## B - Less Critical
34 | 
35 | 1. <a href='../keyboard/'>Site never loses focus</a>
36 |  * Focus is always visible when moving through the page with the keyboard
37 | 2. <a href='../keyboard/'>Tab order is logical</a>
38 | 3. <a href='../forms/'>Form instructions are associated with inputs</a>
39 | 4. <a href='../timeouts/'>Site doesn't timeout unexpectedly</a>
40 |  * Identify elements that may "timeout" and verify that the user can request more time
41 | 5. <a href='../tables/'>Tables are coded properly</a>
42 |  * Tables have proper headers and column attributes
43 | 6. <a href='../headings/'>Headings are nested properly</a>
44 |  * Heading elements are nested in a logical way
45 | 
46 | ## C - Minor
47 | 1. <a href='../iframes/'>Frames are named</a>
48 |  * All frames have a name element
49 | 2. <a href='../flashing/'>Flashing elements are compliant</a>
50 |  * Elements that flash on screen do so at a rate of less than 3 Hz
51 | 3. <a href='../language/'>Language is set</a>
52 |  * The language for the page is set
53 |  * The language for sections on the page that differ from the site language are set
54 | 4. <a href='../css/'>CSS is not required to use the page</a>
55 |  * The page makes sense with or without CSS
56 | 5. <a href='../links/'>Links are unique and contextual</a>
57 |  * All links can be understood taken alone, e.g., 'Read more - about 508'
58 | 6. <a href='../page-titles/'>Page titles are descriptive</a>
59 | 7. <a href='../plugins/'>Required plugins are linked on the page</a>
60 | 
61 | ### Checklist for accessible files
62 | We also need to create accessible files and assets. This includes slides, documents, forms, charts, and diagrams. 
63 | 
64 | Use this [GSA only: Google tools checklist](https://docs.google.com/document/d/1DXiU7pBxMQogH5G4MFC79ki5xCMt1VlED5Mq-XUINmA/edit?usp=sharing) for creating more accessible files and assets. 
65 | 


--------------------------------------------------------------------------------
/pages/images.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Images
 3 | description: 'How we work with images'
 4 | permalink: /images/
 5 | page_title: Images
 6 | layout: post
 7 | sidenav: docs
 8 | ---
 9 | When using images on a page, you must provide an alternate method for that content. This can be provided in multiple ways. You can provide this information with a caption, `alt` attribute (`alt` tag), `title` attribute, or `aria-label` attribute. If an image has text, all the text in the image must be provided in the alternate content. No matter which method is used, an `alt` or title attribute must be provided, even if the attribute is blank.
10 | 
11 | ## Testing
12 | 
13 | 1. Using the web developer tool, select images > Display Alt Attributes & Outline All Images.
14 | 2. Inspect each `alt` attribute for the following:
15 |   * A unique description of the image is provided
16 |   * Repeated images used for controls, status indicators, or other programmatic elements have consistent `alt` text
17 |   * Text included in the image should be included in the `alt` when they are important to understanding the image
18 |     * Note: [DHS Trusted Tester](https://www.dhs.gov/trusted-tester) requires all text in an image be included in the `alt` attribute
19 |   * "Image of" or "Photo of" is not used
20 |   * If the `alt` attribute is empty, ensure the image is purely decorative
21 |     * If the image is not decorative, make sure the image is described on the page
22 | 3. Check outlined images without `alt` attribute by doing the following:
23 |   * Right click the image
24 |   * Select 'Inspect Element'
25 |   * Check for a title attribute for the information normally found on the `alt` attribute
26 | 
27 | ## Examples
28 | 
29 | ### Correct
30 | 
31 | <img src="{{site.baseurl}}/images/sign.jpg" alt="Warning do not read this sign">
32 | 
33 | ```html
34 | <img src="{{site.baseurl}}/images/sign.jpg" alt="Warning do not read this sign">
35 | ```
36 | 
37 | > Preferred method for providing alternate content.
38 | > Clear `alt` attribute with all text included.
39 | 
40 | ---
41 | 
42 | <img src="{{site.baseurl}}/images/sign.jpg" title="Warning do not read this sign" class="exampleFailure">
43 | 
44 | ```html
45 | <img src="{{site.baseurl}}/images/sign.jpg" title="Warning do not read this sign">
46 | ```
47 | 
48 | > Acceptable, but less compatible with certain assistive technologies.
49 | > Clear title attribute with all text included.
50 | 
51 | ---
52 | 
53 | <img src="{{site.baseurl}}/images/sign.jpg" alt="">
54 | <span>Warning do not read this sign</span>
55 | 
56 | ```html
57 | <img src="{{site.baseurl}}/images/sign.jpg" alt="">
58 | <span>Warning do not read this sign</span>
59 | ```
60 | 
61 | > Information contained in the image is provided on the page.
62 | > In most instances, an `alt` attribute would be preferred.
63 | > Images marked with an empty `alt` (`alt=""`) are considered "Decorative" and not read by AT.
64 | 
65 | ---
66 | 
67 | ### Incorrect
68 | 
69 | <img src="{{site.baseurl}}/images/sign.jpg" class="exampleFailure">
70 | 
71 | ```html
72 | <img src="{{site.baseurl}}/images/sign.jpg">
73 | ```
74 | 
75 | > Image is missing an `alt` attribute and alternative content
76 | 
77 | ---
78 | 
79 | <img src="{{site.baseurl}}/images/sign.jpg" alt="sign">
80 | 
81 | ```html
82 | <img src="{{site.baseurl}}/images/sign.jpg" alt="sign">
83 | ```
84 | 
85 | > `Alt` attribute is missing text from image
86 | 
87 | ---
88 | 
89 | <img src="{{site.baseurl}}/images/sign.jpg" alt="Image of sign that says WARNING DO NOT READ THIS SIGN">
90 | 
91 | ```html
92 | <img src="{{site.baseurl}}/images/sign.jpg" alt="Image of sign that says WARNING DO NOT READ THIS SIGN">
93 | ```
94 | 
95 | > Avoid using "Image of" or "Picture of" as the screen reader will notify the user that it's an image. Also avoid using all caps as some screen readers will read each letter, i.e. W-A-R-N-I-N-G.
96 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | **⚠️ This guide has moved to the [consolidated 18F guides repository](https://github.com/18F/guides).**
 2 | 
 3 | # Accessibility
 4 | This repo will contain the guidelines and best practices for 508 accessibility at 18F. 
 5 | The site is in draft.
 6 | 
 7 | ## This site is built using the 18F Guides Template
 8 | 
 9 | See the [guides template repo](https://github.com/18f/guides-template) for more information.
10 | 
11 | ## Generating the accessibility site/hosting locally
12 | 
13 | ### Cloning and running 18F/accessibility
14 | 
15 | You will need [Ruby](https://www.ruby-lang.org) ( > version 2.1.5 ). You may
16 | consider using a Ruby version manager such as
17 | [rbenv](https://github.com/sstephenson/rbenv) or [rvm](https://rvm.io/) to
18 | help ensure that Ruby version upgrades don’t mean all your
19 | [gems](https://rubygems.org/) will need to be rebuilt.
20 | 
21 | On OS X, you can use [Homebrew](http://brew.sh/) to install Ruby in
22 | `/usr/local/bin`, which may require you to update your `$PATH` environment
23 | variable:
24 | 
25 | ```shell
26 | $ brew update
27 | $ brew install ruby
28 | ```
29 | 
30 | You will also need the the [Bundler gem](http://bundler.io/) for this project:
31 | 
32 | ```shell
33 | $ gem install bundler 
34 | ```
35 | 
36 | To serve 18F Accessibility Guide locally, using `accessibility` as the name of your new repository:
37 | 
38 | ```shell
39 | $ git clone https://github.com/18F/accessibility.git accessibility
40 | $ cd accessibility
41 | $ bundle install
42 | $ bundle exec jekyll serve
43 | ```
44 | 
45 | This will install all the gems needed by the template, and launch a running instance on
46 | `http://localhost:4000`. You can see how your local copy of accessibility renders
47 | at any time by going to that URL. To stop serving locally, simply type `Ctrl+C`
48 | into the terminal again.
49 | 
50 | Note: The main branch of this project is 18f-pages. Please submit all PRs against that branch.
51 | 
52 | ### Forking into your own repository
53 | 
54 | If you haven’t already followed the cloning instructions above, the easiest way to do this is simply to go to https://github.com/18F/accessibility and click `Fork`, then set up the repository under your own username. Then follow the instructions above to clone locally, subbing in MY-USER-NAME for 18F’s in the URL that follows `git clone`.
55 | 
56 | If you _have_ already cloned locally from 18F and want to maintain your own accessibility repository, do the following.
57 | 
58 | You’ll need to create a new repository on Github. To do this, go to github.com/MY-USER-NAME and click the "New Repository" button. Enter the title and description for your new guide and then click `Create Repository`. It’s easiest if you use `accessibility` as the name, as it will match back to the 18F accessibility you’re building from.
59 | 
60 | After the repository is created, you’ll see the repository URL at the top. Copy this url by hitting the handy `Copy to Clipboard` button next to the text box.
61 | 
62 | Go back to the directory where you cloned the repository. We’re going to change this repo to point to the one you just created (which is empty), instead of back to 18F’s, and push to it.
63 | ```
64 | git remote set-url origin https://github.com/MY-USER-NAME/accessibility.git
65 | git push origin 18f-pages-staging
66 | ```
67 | 
68 | Now you can edit your own fork of accessibility freely, and push up changes as you need.
69 | 
70 | ## Public domain
71 | 
72 | This project is in the worldwide [public domain](LICENSE.md). As stated in [CONTRIBUTING](CONTRIBUTING.md):
73 | 
74 | > This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).
75 | >
76 | > All contributions to this project will be released under the CC0
77 | >dedication. By submitting a pull request, you are agreeing to comply
78 | >with this waiver of copyright interest.
79 | 


--------------------------------------------------------------------------------
/_sass/syntax.css:
--------------------------------------------------------------------------------
  1 | .highlight table td { padding: 5px; }
  2 | .highlight table pre { margin: 0; }
  3 | .highlight .cm {
  4 |   color: #333322;
  5 |   font-style: italic;
  6 | }
  7 | .highlight .cp {
  8 |   color: #333333;
  9 |   font-weight: bold;
 10 | }
 11 | .highlight .c1 {
 12 |   color: #333322;
 13 |   font-style: italic;
 14 | }
 15 | .highlight .cs {
 16 |   color: #333333;
 17 |   font-weight: bold;
 18 |   font-style: italic;
 19 | }
 20 | .highlight .c, .highlight .ch, .highlight .cd, .highlight .cpf {
 21 |   color: #333322;
 22 |   font-style: italic;
 23 | }
 24 | .highlight .err {
 25 |   color: #a61717;
 26 |   background-color: #e3d2d2;
 27 | }
 28 | .highlight .gd {
 29 |   color: #000000;
 30 |   background-color: #ffdddd;
 31 | }
 32 | .highlight .ge {
 33 |   color: #000000;
 34 |   font-style: italic;
 35 | }
 36 | .highlight .gr {
 37 |   color: #aa0000;
 38 | }
 39 | .highlight .gh {
 40 |   color: #333333;
 41 | }
 42 | .highlight .gi {
 43 |   color: #000000;
 44 |   background-color: #ddffdd;
 45 | }
 46 | .highlight .go {
 47 |   color: #888888;
 48 | }
 49 | .highlight .gp {
 50 |   color: #555555;
 51 | }
 52 | .highlight .gs {
 53 |   font-weight: bold;
 54 | }
 55 | .highlight .gu {
 56 |   color: #aaaaaa;
 57 | }
 58 | .highlight .gt {
 59 |   color: #aa0000;
 60 | }
 61 | .highlight .kc {
 62 |   color: #000000;
 63 |   font-weight: bold;
 64 | }
 65 | .highlight .kd {
 66 |   color: #000000;
 67 |   font-weight: bold;
 68 | }
 69 | .highlight .kn {
 70 |   color: #000000;
 71 |   font-weight: bold;
 72 | }
 73 | .highlight .kp {
 74 |   color: #000000;
 75 |   font-weight: bold;
 76 | }
 77 | .highlight .kr {
 78 |   color: #000000;
 79 |   font-weight: bold;
 80 | }
 81 | .highlight .kt {
 82 |   color: #445588;
 83 |   font-weight: bold;
 84 | }
 85 | .highlight .k, .highlight .kv {
 86 |   color: #000000;
 87 |   font-weight: bold;
 88 | }
 89 | .highlight .mf {
 90 |   color: #007777;
 91 | }
 92 | .highlight .mh {
 93 |   color: #007777;
 94 | }
 95 | .highlight .il {
 96 |   color: #007777;
 97 | }
 98 | .highlight .mi {
 99 |   color: #007777;
100 | }
101 | .highlight .mo {
102 |   color: #007777;
103 | }
104 | .highlight .m, .highlight .mb, .highlight .mx {
105 |   color: #007777;
106 | }
107 | .highlight .sb {
108 |   color: #d14;
109 | }
110 | .highlight .sc {
111 |   color: #d14;
112 | }
113 | .highlight .sd {
114 |   color: #d14;
115 | }
116 | .highlight .s2 {
117 |   color: #d14;
118 | }
119 | .highlight .se {
120 |   color: #d14;
121 | }
122 | .highlight .sh {
123 |   color: #d14;
124 | }
125 | .highlight .si {
126 |   color: #d14;
127 | }
128 | .highlight .sx {
129 |   color: #d14;
130 | }
131 | .highlight .sr {
132 |   color: #009926;
133 | }
134 | .highlight .s1 {
135 |   color: #d14;
136 | }
137 | .highlight .ss {
138 |   color: #990073;
139 | }
140 | .highlight .s, .highlight .sa, .highlight .dl {
141 |   color: #d14;
142 | }
143 | .highlight .na {
144 |   color: #007070;
145 | }
146 | .highlight .bp {
147 |   color: #999999;
148 | }
149 | .highlight .nb {
150 |   color: #005B7A;
151 | }
152 | .highlight .nc {
153 |   color: #445588;
154 |   font-weight: bold;
155 | }
156 | .highlight .no {
157 |   color: #007070;
158 | }
159 | .highlight .nd {
160 |   color: #3c5d5d;
161 |   font-weight: bold;
162 | }
163 | .highlight .ni {
164 |   color: #800080;
165 | }
166 | .highlight .ne {
167 |   color: #990000;
168 |   font-weight: bold;
169 | }
170 | .highlight .nf, .highlight .fm {
171 |   color: #990000;
172 |   font-weight: bold;
173 | }
174 | .highlight .nl {
175 |   color: #990000;
176 |   font-weight: bold;
177 | }
178 | .highlight .nn {
179 |   color: #555555;
180 | }
181 | .highlight .nt {
182 |   color: #000080;
183 | }
184 | .highlight .vc {
185 |   color: #007070;
186 | }
187 | .highlight .vg {
188 |   color: #007070;
189 | }
190 | .highlight .vi {
191 |   color: #007070;
192 | }
193 | .highlight .nv, .highlight .vm {
194 |   color: #007070;
195 | }
196 | .highlight .ow {
197 |   color: #000000;
198 |   font-weight: bold;
199 | }
200 | .highlight .o {
201 |   color: #000000;
202 |   font-weight: bold;
203 | }
204 | .highlight .w {
205 |   color: #bbbbbb;
206 | }
207 | .highlight {
208 |   background-color: #f8f8f8;
209 |   font-size: 1rem;
210 |   line-height: 1.4rem;
211 |   white-space: pre-wrap;
212 |   border-radius: 0.6rem;
213 | }
214 | pre.highlight {
215 |   padding: 1.2rem;
216 | }


--------------------------------------------------------------------------------
/index.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | published: true
 3 | permalink: /
 4 | filename: index.md
 5 | title: Home
 6 | page_title: Home
 7 | layout: post
 8 | sidenav: docs
 9 | ---
10 | 
11 | Accessibility is one of the most important aspects of modern web development. Accessibility means the greatest number of users can view your content. It means search engines will be able to read your site more completely. Users of all types will have a better experience if you take accessibility concerns into account. And least of all, it is required by law for all federal information and communication technology (ICT) products to be accessible (with a few minor exceptions).
12 | 
13 | Accessibility works best when incorporated into an agile production environment. It's very hard to adequately address accessibility concerns at the end of a project, but if taken into account at the beginning, it's quite straightforward and cost effective. The best way to ensure this is done is through training and education. Every member of a production team should be aware of what accessibility concerns are and have a basic understanding of how they are addressed.
14 | 
15 | The Web Content Accessibility Guidelines (WCAG) have long been the gold standard for accessibility on the web. Here at 18F we follow [WCAG2.0 AA](https://www.w3.org/TR/WCAG20/) as our minimum standard for accessibility.  
16 | 
17 | If you have questions about accessibility or would like help, please reach out on the [GitHub Repo](https://github.com/18F/accessibility).
18 | 
19 | __Disclaimer:__ This resource is intended to help 18F develop accessible products and is not a replacement for the standards defined by the U.S. Access Board. Please visit the [Access Board's Section 508 Standards for ICT](https://www.access-board.gov/ict/) for more information.
20 | 
21 | ## Resources
22 | 
23 | ### Testing Tools
24 | 
25 | Please see [our tools page for a listing of accessibility testing tools](tools/). 
26 | 
27 | ### Government Sites and tutorials
28 | * [Section 508](https://section508.gov/)
29 | * [Accessibility for Teams](https://accessibility.digital.gov/)
30 | * [18F Accessibility Checklist](./checklist/)
31 | * [U.S. Web Design System Accessibility Tips](https://designsystem.digital.gov/documentation/accessibility/)
32 | * [ANDI video training series (GSA)](https://www.section508.gov/training/web-software/andi-training-videos/)
33 | * [GSA Accessibility Aids](https://www.gsa.gov/website-information/accessibility-aids)
34 | * [Create Accessible PDFs](https://www.section508.gov/create/pdfs)
35 | * [Required fixes for PDFs](https://www.hhs.gov/web/section-508/making-files-accessible/pdf-required/)
36 | * [Making Files Accessible PDF, Word, Excel, PowerPoint](https://www.hhs.gov/web/section-508/os-training-resources/)
37 | 
38 | ### World Wide Web Consortium's Web Accessibility Initiative
39 | * [Web Content Accessibility Guidelines (WCAG) 2.0](https://www.w3.org/TR/WCAG20/)
40 | * [How to Meet WCAG (Quick Reference)](https://www.w3.org/WAI/WCAG21/quickref/)
41 | * [Web Accessibility Tutorials](https://www.w3.org/WAI/tutorials/)
42 | * [Accessible Rich Internet Applications (ARIA) Documentation](https://www.w3.org/html/wg/drafts/html/master/dom.html#wai-aria) 
43 | * [Web Accessibility Evaluation Tools List](https://www.w3.org/WAI/ER/tools/)
44 | 
45 | ### Misc Sites and tutorials
46 | * [Inclusive Components](https://inclusive-components.design/) - A blog about designing inclusive web interfaces, piece by piece.
47 | * [WebAIM's Blog](http://webaim.org/blog/)
48 | * [The Accessibility Project](https://a11yproject.com/) - Good accessibility blog.
49 | * [Knowbility's Blog - WCAG 2.1 Series](https://knowbility.org/blog/2018/WCAG21-intro/)
50 | * [Simply Accessible](http://simplyaccessible.com/archives/) - A great blog and resource with articles about modern accessibility.
51 | * [WebAIM's Accessibility Resources](https://webaim.org/resources/)
52 | * [Tips for creating Accessible SVGs](https://www.sitepoint.com/tips-accessible-svg/)
53 | * [Udacity Web Accessibility Course](https://www.udacity.com/course/web-accessibility--ud891) - Free web accessibility course by Google
54 | * [Vox Accessibility Guidelines Checklist](https://accessibility.voxmedia.com/)
55 | * [CanIUse.com](https://caniuse.com/) - useful for HTML5, ARIA & CSS 
56 | * [New Zealand Web Accessibility Standard 1.1](https://www.digital.govt.nz/standards-and-guidance/nz-government-web-standards/web-accessibility-standard-1-1/)
57 | 


--------------------------------------------------------------------------------
/pages/keyboard.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Keyboard access
 3 | description: 'How we work with keyboards only'
 4 | permalink: /keyboard/
 5 | page_title: Keyboard access
 6 | layout: post
 7 | sidenav: docs
 8 | scripts:
 9 | - assets/js/keyboard-access.js
10 | ---
11 | 
12 | Keyboard access to a website is key to the usability of your site. All interactions and information that can be accessed with a mouse **must** be accessible with just a keyboard. This doesn't mean everyone who can't use a mouse will use a keyboard, but alternative AT inputs use keyboard-like inputs to navigate the web.
13 | 
14 | ## Testing
15 | 
16 | 1. Identify all interactions on the page.
17 | 2. Using the tab, enter, and space bar, navigate the page and ensure each input and interaction can be triggered.
18 |   * Ensure rollover and hover interactions (help text, etc) can be triggered as well.
19 |   * __If the user cannot interact with something, or get the information another way, this is a failure__.
20 | 3. Make sure the tab order of the page is logical and follows the visual order of elements on the page.
21 |   * __If the tab order is confusing, this is a failure__.
22 | 4. Check that the focus is always visible when moving through the page with the tab key.
23 |   * __If you lose focus, on a hidden link or other object when simply tabbing through the page, this is a failure__.
24 | 5. Make sure you can tab through the page and get back to the address bar.
25 |   * __If you ever need your mouse to get back to an element, this is a failure__.
26 | 6. Keyboard users must be able to easily use and dismiss modal dialog boxes, lightboxes, or other pop-ups.
27 |   * Modal dialog boxes need to trap the keyboard. When a modal dialog box is triggered, the keyboard focus needs to immediately move to the first actionable element in the modal.
28 |   * The keyboard use is confined to the modal dialog box until it is dismissed. When a user moves the keyboard focus past the last element in the modal dialog box, it needs to loop to the beginning of the dialog box.
29 |   * The keyboard user needs to be able to access all controls in the dialog box, especially the controls to dismiss the dialog.
30 |   * __If the keyboard user cannot do all of these things, this is a failure__.
31 |   * Ideally, the keyboard user should also be able to dismiss the modal dialog box with the Escape key.
32 | 7. If an interaction reveals hidden content.
33 |   * Ensure the focus is moved to the revealed content.
34 |     * If this does not happen, check for a programmatic description of the change.
35 | 8. Check for title attributes providing information not on the screen.
36 |   * __Title attributes which can only be exposed by hovering the mouse over the element are a failure of keyboard access__.
37 | 9. Check that the focus never goes to elements that won't be available to somebody using a mouse.
38 | 
39 | ## Examples
40 | 
41 | <a href="#">Link to nowhere 1</a>
42 | 
43 | <a href="#">Link to nowhere 2</a>
44 | 
45 | <a href="javascript:var link = document.getElementById('hiddenContent'); link.setAttribute('style', 'display: block'); link.focus();">Reveal Hidden Content</a>
46 | 
47 | <div id="hiddenContent" style="display:none;" tabindex='-1'>This div was hidden, now it's not!</div>
48 | 
49 | ```html
50 | <a href="#">Link to nowhere 1</a>
51 | <a href="#">Link to nowhere 2</a>
52 | <a href="javascript:var link = document.getElementById('hiddenContent'); link.setAttribute('style', 'display: block'); link.focus();">
53 |   Reveal Hidden Content
54 | </a>
55 | <div id="hiddenContent"
56 | 	 style="display:none;"
57 | 	 tabindex='-1'>
58 | 	This div was hidden, now it's not!
59 | </div>
60 | ```
61 | 
62 | > Avoid using tabindex of >= 1 as this will disrupt the normal tab order of the page. tabindex of -1 is only appropriate when autofocusing an element not normally interactive.
63 | 
64 | <h3 id='keyboard-trap'>Keyboard trap</h3>
65 | 
66 | <a class="sr-only moveFocus" href="#">hidden</a>
67 | 
68 | <a class="keyboardTrap" href="#">Select to disable keyboard trap</a>
69 | 
70 | <a class="keyboardTrap" href="#">Select to disable keyboard trap</a>
71 | 
72 | <a class="keyboardTrap" href="#">Select to disable keyboard trap</a>
73 | 
74 | <a class="keyboardTrap" href="#">Select to disable keyboard trap</a>
75 | 
76 | <a class="sr-only moveFocus" href="#">hidden</a>
77 | 
78 | > This is an example of a keyboard trap. Focus moves in a loop making the rest of the page inaccessible. A quick test is to tab through the page quickly and ensure you can get focus back to the address bar.
79 | 


--------------------------------------------------------------------------------
/pages/hiddencontent.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | title: Hidden content
  3 | description: 'How and when to hide content'
  4 | permalink: /hidden-content/
  5 | page_title: Hidden Content
  6 | layout: post
  7 | sidenav: docs
  8 | ---
  9 | 
 10 | Hiding content is very useful for accessibility. We can hide things visually and only display it to screen reader users, we can hide content from screen reader users and only show it visually, or we can hide content from both. 
 11 | 
 12 | ## Techniques
 13 | {% capture css_display_none %}
 14 |   ```css
 15 |     {
 16 |       display:none;
 17 |     }
 18 |   ```
 19 | {% endcapture %}
 20 | 
 21 | {% capture css_sr_only %}
 22 |   ```css
 23 |     .sr-only {
 24 |       border: 0; 
 25 |       clip: rect(0 0 0 0); 
 26 |       height: 1px; 
 27 |       margin: -1px;
 28 |       overflow: hidden;
 29 |       padding: 0;
 30 |       position: absolute;
 31 |       width: 1px;
 32 |     }
 33 |   ```
 34 | {% endcapture %}
 35 | <table>
 36 | <thead>
 37 |   <tr>
 38 |     <th style="width:40%;" scope='col'>
 39 |       Technique
 40 |     </th>
 41 |     <th scope='col'>
 42 |       Visually hidden
 43 |     </th>
 44 |     <th scope='col'>
 45 |       Screen reader hidden
 46 |     </th>
 47 |     <th scope='col'>
 48 |       Additional info
 49 |     </th>
 50 |   </tr>
 51 | </thead>
 52 | <tbody>
 53 |   <tr>
 54 |     <th scope='row'>
 55 |       CSS:<br> {{ css_sr_only | markdownify }}
 56 |     </th>
 57 |     <td>Yes</td>
 58 |     <td>No</td>
 59 |     <td>There are multiple ways to accomplish this with CSS. This is the current way we are recommending it.</td>
 60 |   </tr>
 61 |   <tr>
 62 |     <th scope='row'>
 63 |       CSS:<br>
 64 |       {{ css_display_none | markdownify }}
 65 |     </th>
 66 |     <td>Yes</td>
 67 |     <td>Yes</td>
 68 |     <td></td>
 69 |   </tr>
 70 |   <tr>
 71 |     <th scope='row'>
 72 |       HTML5 attribute:<br>
 73 |       <strong>hidden</strong>
 74 |     </th>
 75 |     <td>Yes</td>
 76 |     <td>Yes</td>
 77 |     <td>In supported browsers, this is the same as {{ css_display_none | markdownify }}</td>
 78 |   </tr>
 79 |   <tr>
 80 |     <th scope='row'>
 81 |       aria attribute:<br>
 82 |       <strong>aria-hidden='false'</strong>
 83 |     </th>
 84 |     <td>No</td>
 85 |     <td>No</td>
 86 |     <td>This is overwritten by other techniques. i.e. Using {{ css_display_none | markdownify }} will cause the element not to be read or seen.</td>
 87 |   </tr>
 88 |   <tr>
 89 |     <th scope='row'>
 90 |       aria attribute:<br>
 91 |       <strong>aria-hidden='true'</strong>
 92 |     </th>
 93 |     <td>No</td>
 94 |     <td>Yes</td>
 95 |     <td></td>
 96 |   </tr>
 97 | </tbody>
 98 | </table>
 99 |  
100 | ## Aria hidden
101 | 
102 | aria-hidden should be used in combination with these techniques. If we want to hide something from just the screen reader, you can mark it as `aria-hidden='true'`. 
103 | 
104 | Items with `aria-hidden='true'` are always ignored by the screen reader.
105 | This is useful for:
106 | 
107 | - Collapsing Menus
108 | - Repetitive information
109 | - Off screen content
110 | 
111 | If an element has multiple states, its visibility should be tracked with `aria-hidden` `true/false`. An element with `aria-hidden='false'` is treated by the screen reader as if it didn't have the `aria-hidden` attribute and is read or not read based on other factors, such as CSS. 
112 | 
113 | ## CSS
114 | 
115 | CSS can be used to hide content and allow it to still be used with the screen reader. For an example of that, see this code here, 
116 | 
117 | ```css
118 | .sr-only {
119 |   border: 0;
120 |   clip: rect(0 0 0 0);
121 |   height: 1px;
122 |   margin: -1px;
123 |   overflow: hidden;
124 |   padding: 0;
125 |   position: absolute;
126 |   width: 1px;
127 | }
128 | ```
129 | 
130 | Using this we can:
131 | 
132 | - Provide additional details about a form element
133 |   - Hidden labels
134 |   - Error details
135 | - Provide context to page elements
136 | - Add additional instructions for navigation
137 | 
138 | We can also use CSS to hide content visually and from screen readers. 
139 | 
140 | ```css
141 | {
142 |   display: none;
143 | }
144 | ```
145 | 
146 | This will hide completely and is the same as `<div aria-hidden='true' hidden>content</div>` Note that `aria-hidden='true'` should be used for additional compatibility. 
147 | 
148 | `display: none;` and `hidden` can be used for:
149 | 
150 | - Collapsing menus
151 | - Repetitive information
152 | - Off-screen content
153 | 
154 | ## Additional resources
155 | 
156 | For more information on this topic, see these articles. 
157 | 
158 | - [HTML5 Accessibility Chops: hidden and aria-hidden](https://www.tpgi.com/html5-accessibility-chops-hidden-and-aria-hidden/)
159 | - [The state of hidden content support in 2016](https://www.tpgi.com/the-state-of-hidden-content-support-in-2016/)
160 | 


--------------------------------------------------------------------------------
/pages/color.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Color and contrast
 3 | description: 'How we work with color and contrast'
 4 | permalink: /color/
 5 | page_title: Color and contrast
 6 | layout: post
 7 | sidenav: docs
 8 | ---
 9 | There are two main accessibility concerns for color, contrast and color dependence. Color contrast is the ratio of the foreground color(text) and the background color. Text should have a ratio of 4.5:1 or greater with the background.
10 | 
11 | Color dependence is the need to see color to understand the information. An example of this would be `The required fields are red.` Some users may not be able to distinguish red from other colors and would lack information to fill out this form.
12 | 
13 | Links that only rely on color also fail this requirement. Links must be distinguished by more than just color (hue). Links can be distinguished by underlines, symbols, context (in a menu for example), or lightness. If the contrast between the surrounding text and a link is greater than 3:1 it is acceptable. Also note, the link text itself still needs to have a contrast ratio of 4.5:1 or greater with the background. [More information about link color dependence.](https://www.w3.org/TR/2016/NOTE-WCAG20-TECHS-20161007/F73)
14 | 
15 | ## Testing
16 | 
17 | ### Color contrast
18 | 
19 | 1. Using a [color contrast checker](https://www.tpgi.com/color-contrast-checker//), compare the color of the text with the color of the background.
20 | 2. In situations where the color is a gradient or cannot be determined programmatically, compare the lightest part of the text with the lightest part of the background using the color picker. Then compare the darkest part of the text with the darkest part of the background.
21 | 3. Check that the ratios are greater than [4.5:1][https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0#contrast-minimum] (ex 5.3:1 would pass).
22 | 
23 | **Note:** Run this test for all states of the text (hover, visited, focused). This test should also be performed on images of text.
24 | 
25 | **Note:** Logos, disabled form fields, and disabled buttons are **exempt** from this test and don't need to be tested for contrast.
26 | 
27 | ### Color dependence
28 | 
29 | 1. Identify sections which use color to convey information.
30 | 2. Check to see if the information is conveyed in another way visually and programmatically.
31 | 3. If links are only distinguished by color surrounded by normal text
32 |   1. Check if the link has a contrast ratio of 3:1 with the surrounding text
33 | 
34 | ## Examples
35 | 
36 | ### Failures
37 | 
38 | <span style = "color:#58AA02" class="exampleFailure">This text fails. </span>
39 | 
40 | > This text fails because it's too light. The contrast ratio is (2.93 : 1).
41 | 
42 | <span style = "color:#FFFFFF; background:#8D8E90" class="exampleFailure">This text fails.</span>
43 | 
44 | > This text fails because the background isn't dark enough. The contrast ratio is (3.28 : 1).
45 | 
46 | <span style="color:#AA0000;">Red text indicates a required field</span>
47 | 
48 | <label for="name">First Name&nbsp;</label><input type="text" id="name">
49 | 
50 | <label for="lname" style="color:#AA0000">Last Name&nbsp;</label><input type="text" id="lname">
51 | 
52 | > This is a failure because the only indication of which fields are required is the color of the text label.
53 | 
54 | <span><a href="#" style="color:#006061; text-decoration:none; border-bottom-style: none;">I'm a link.</a> I'm just normal text  </span>
55 | 
56 | > This fails because the contrast ratio between the link and surrounding text is less than 3:1.
57 | 
58 | ### Passes
59 | 
60 | <span style = "color:#458503">This text passes. </span>
61 | 
62 | > This text passes. The contrast ratio is (4.56 : 1).
63 | 
64 | <span style = "color:#FFFFFF; background:#757679">This text passes.</span>
65 | 
66 | > This text passes. The contrast ratio is (4.54 : 1).
67 | 
68 | <span style="color:#AA0000;">* indicates a required field</span>
69 | 
70 | <label for="name-2">First Name&nbsp;</label><input type="text" id="name-2">
71 | 
72 | <label for="lname-2" style="color:#AA0000">* Last Name&nbsp;</label><input type="text" id="lname-2">
73 | 
74 | > This example passes because the * and the red text indicates the required field.
75 | 
76 | <span><a href="#" style="color:#006465; text-decoration:none; border-bottom-style: none;">I'm a link.</a> I'm just normal text  </span>
77 | 
78 | > This passes because the link and the black text have a contrast(lightness) ratio of 3:1, but we would recommend a greater contrast ratio for links without other visual indicators
79 | 
80 | <span><a href="#" style="color:#000000; text-decoration:none; border-bottom-style: none;">I'm a link.</a> I'm just normal text  </span>
81 | 
82 | > This passes because all users see the link as normal text.
83 | 
84 | [WCAG 2.0 AA]: https://www.w3.org/WAI/WCAG20/quickref/#visual-audio-contrast-contrast
85 | 


--------------------------------------------------------------------------------
/pages/links.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | title: Links and repetitive content
  3 | description: 'How we deal with links and repetitive content'
  4 | permalink: /links/
  5 | page_title: Links and Repetitive Content
  6 | layout: post
  7 | sidenav: docs
  8 | ---
  9 | Links are commonly used to quickly navigate a site when someone is using assistive technology. Often, screen reader users won’t read through an entire page to find what they are looking for. They may simply move from link to link.
 10 | 
 11 | Things become problematic when links only make sense with additional context. Links such as ‘Click Here’ or ‘Read more’ don’t make sense without that visual context. It’s important that we inspect our sites for these types of links. These links can be made accessible using ```title``` or ```ARIA``` attributes, but this isn’t ideal. **The best method for making links accessible is to write better link text.**
 12 | 
 13 | The other issue screen reader and keyboard users come across is lengthy nav bars. These are usually made up of a list of links and compound menus. They can be quite lengthy to tab through. To alleviate these pains, a skip navigation link should be provided. This is the first focusable element on the page and jumps to an anchor with a ```tabindex='-1'```.
 14 | 
 15 | ## Testing
 16 | 
 17 | ### Unique links
 18 | 
 19 | 1. Identify all links on the page.
 20 | 2. Identify links with the same text.
 21 |   * If the link destinations are different, check for ```title``` or ```ARIA``` attributes that distinguish them.
 22 | 3. Identify links with generic text (‘Click here’, ‘Read more’).
 23 |   * Check for the ```title``` or ```ARIA``` attributes to provide context or additional off-screen text.
 24 | 
 25 | ### Links that open in a new window
 26 | 1. Identify links that open in new windows.
 27 | 2. Check for links with ```target='_blank'```.
 28 | 3. Verify that an indication is given accessibly. Some examples are:
 29 |   *  ```<a href='#' target='_blank' aria-label='Opens in new window'>```
 30 |   *  ```<a href='#' target='_blank' title='Opens in new window'>```
 31 |   *  ```<a href='#' target='_blank'>Link<span class='sr-only'>Opens in new window</span></a>```
 32 | 
 33 | ### Skip navigation
 34 | 
 35 | 1. First, compare the pages on the site for links that are repeated at the beginning of the tab order.
 36 |   * `Skip Navigation` is not needed if repetitive nav links are not used.
 37 | 2. If the `Skip Navigation` link is not visible, ensure it becomes visible when it has focus.
 38 | 3. Find the target of the skip navigation link.
 39 |   * Verify the target is a valid `id`.
 40 |   * Verify the target is after the repetitive content and before meaningful content.
 41 |   * Verify the target has a ```tabindex='-1'``` or is included in the tab order (such as a link or a button).
 42 |    * This ensures the element will receive focus when used.
 43 | 4. Activate the `Skip Navigation` link.
 44 | 5. If visual focus is after the repetitive content, the test is complete.
 45 | 6. If there is no visual focus, tab again to verify focus is after the repetitive content.
 46 | 
 47 | ## Examples
 48 | 
 49 | ### Passes
 50 | 
 51 | Home <a href='../' title='home'>Click Here</a>
 52 | 
 53 | Keyboard Access <a href='../keyboard/' aria-label="Keyboard Access">Click Here</a>
 54 | 
 55 | ```html
 56 | Home <a href='../' title='home'>Click Here</a>
 57 | 
 58 | Keyboard Access <a href='../keyboard/' aria-label="Keyboard Access">Click Here</a>
 59 | ```
 60 | 
 61 | > These links are not unique, but the ```title``` attribute in the first link gives a screen reader user context and the ```aria-label``` provides the context in the second link.
 62 | 
 63 | #### Skip navigation
 64 | 
 65 | ```html
 66 | //This is the code used on this guide
 67 | <a class="usa-skipnav" href="#main-content">Skip to main content</a>
 68 | ...
 69 | <main id="main-content" tabindex="-1" ...>
 70 | 
 71 | ```
 72 | ```css
 73 | .usa-skipnav {
 74 |     font-family: Helvetica Neue,Helvetica,Roboto,Arial,sans-serif;
 75 |     font-size: 1.08rem;
 76 |     line-height: 1.6;
 77 |     color: #005ea2;
 78 |     text-decoration: underline;
 79 |     background: transparent;
 80 |     left: 0;
 81 |     padding: 0.5rem 1rem;
 82 |     position: absolute;
 83 |     top: -3.8rem;
 84 |     transition: 0.2s ease-in-out;
 85 |     z-index: 100;
 86 | }
 87 | 
 88 | .usa-skipnav:focus {
 89 |     z-index: 9999;
 90 | }
 91 | 
 92 | .usa-skipnav:focus, .usa-skipnav.usa-focus {
 93 |     background: #fff;
 94 |     left: 0;
 95 |     position: absolute;
 96 |     top: 0;
 97 |     transition: 0.2s ease-in-out;
 98 | }
 99 | 
100 | .usa-skipnav:focus {
101 |     outline: 0.25rem solid #2491ff;
102 |     outline-offset: 0;
103 | }
104 | 
105 | .usa-skipnav:active {
106 |     color: #11181d;
107 | }
108 | ```
109 | 
110 | > This is how the 'Skip Navigation' was achieved for the accessibility site. Feel free to use for your own site.
111 | 


--------------------------------------------------------------------------------
/_includes/footer.html:
--------------------------------------------------------------------------------
 1 | {% assign identifier = site.data.usa_identifier.identifier_data[0] %}
 2 | 
 3 | <footer class="usa-footer">
 4 |   <section>
 5 |     <div class="usa-footer__secondary-section">
 6 |       <div class="grid-container">
 7 |         <div class="grid-row grid-gap">
 8 |           <div class="usa-footer__contact-links mobile-lg:grid-col-12">
 9 |             <div class="usa-footer grid-row">
10 |               <div class="grid-col-auto">
11 |                 This project is maintained by <a class="usa-link" href="{{ identifier.org_secondary_url }}">{{ identifier.org_secondary }}</a>
12 |               </div>
13 |             </div>
14 |             <div class="usa-footer grid-row">
15 |               <div class="grid-col-auto">
16 |                 Have questions or would like to contact us? Email us at <a class="usa-link" href="mailto:{{ identifier.site_email }}">{{ identifier.site_email }}</a>
17 |               </div>
18 |             </div>
19 |           </div>
20 |         </div>
21 |       </div>
22 |     </div>
23 |   </section>
24 |   <div class="usa-identifier">
25 |     <section class="usa-identifier__section usa-identifier__section--masthead" aria-label="Agency identifier">
26 |       <div class="usa-identifier__container">
27 |         <div class="usa-identifier__logos">
28 |           <a href="https://www.gsa.gov/" class="usa-identifier__logo">
29 |             <img class="usa-identifier__logo-img" src="{{ site.baseurl }}/images/{{ identifier.agency_logo }}" alt="GSA logo" role="img" />
30 |           </a>
31 |         </div>
32 |         <div class="usa-identifier__identity text-base-lightest" aria-label="Agency description">
33 |           <p class="usa-identifier__identity-domain">{{ identifier.site_name }}</p>
34 |           <p class="usa-identifier__identity-disclaimer text-base-lightest">An official website of the
35 |             <a href="https://www.gsa.gov/about-us/organization/federal-acquisition-service/technology-transformation-services">
36 |               GSA’s Technology Transformation Services
37 |             </a>
38 |           </p>
39 |         </div>
40 |       </div>
41 |     </section>
42 |     <nav class="usa-identifier__section usa-identifier__section--required-links" aria-label="Important links">
43 |       <div class="usa-identifier__container">
44 |         <ul class="usa-identifier__required-links-list">
45 |           <li class="usa-identifier__required-links-item">
46 |             <a class="usa-identifier__required-link usa-link" href="{{ identifier.agency_about_url }}" title="About GSA">
47 |               About GSA
48 |             </a>
49 |           </li>
50 |           <li class="usa-identifier__required-links-item">
51 |             <a class="usa-identifier__required-link usa-link" href="{{ identifier.accessibility_url }}" title="View accessibility statement">
52 |               Accessibility support
53 |             </a>
54 |           </li>
55 |           <li class="usa-identifier__required-links-item">
56 |             <a class="usa-identifier__required-link usa-link" href="{{ identifier.foia_request_url }}" title="Submit a Freedom of Information Act (FOIA) request">
57 |               FOIA requests
58 |             </a>
59 |           </li>
60 |           <li class="usa-identifier__required-links-item">
61 |             <a class="usa-identifier__required-link usa-link" href="{{ identifier.no_fear_act_url }}" title="View No FEAR Act data">
62 |               No FEAR Act data
63 |             </a>
64 |           </li> 
65 |           <li class="usa-identifier__required-links-item">
66 |             <a class="usa-identifier__required-link usa-link" href="{{ identifier.fraud_waste_abuse_url }}" title="Office of the Inspector General">
67 |               Office of the Inspector General
68 |             </a>
69 |           </li>                   
70 |           <li class="usa-identifier__required-links-item">
71 |             <a class="usa-identifier__required-link usa-link" href="{{ identifier.budget_performance_url }}" title="View budget and performance reports">
72 |               Performance reports
73 |             </a>
74 |           </li>
75 |           <li class="usa-identifier__required-links-item">
76 |             <a class="usa-identifier__required-link usa-link" href="{{ identifier.privacy_policy_url }}" title="Our privacy policy">
77 |               Privacy policy
78 |             </a>
79 |           </li>       
80 |         </ul>
81 |       </div>
82 |     </nav>
83 |     <section class="usa-identifier__section usa-identifier__section--usagov" aria-label="U.S. government information and services">
84 |       <div class="usa-identifier__container">
85 |         <div class="usa-identifier__usagov-description text-base-lightest">Looking for U.S. government information and services?</div>
86 |         <a href="https://www.usa.gov/" class="usa-link">Visit USA.gov</a>
87 |       </div>
88 |     </section>
89 |   </div>
90 | </footer>
91 | 


--------------------------------------------------------------------------------
/pages/tools.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Tools
 3 | description: 'Tools we use to improve and test accessibility'
 4 | permalink: /tools/
 5 | page_title: Accessibility-friendly Tools
 6 | layout: post
 7 | sidenav: docs
 8 | ---
 9 | 
10 | ## Color tools
11 | * [WebAIM color contrast checker](https://webaim.org/resources/contrastchecker/) compares two hex colors and tells you whether they meet WCAG AA and AAA contrast thresholds.
12 | * [Snook's color contrast analyzer](https://snook.ca/technical/colour_contrast/colour.html) lets you adjust RGB and HSV values and reports contrast compliance interactively.
13 | * [Color Safe](http://colorsafe.co/) is a guide for choosing colors that meet WCAG contrast thresholds.
14 | * [Color Contrast Analyzer](https://www.tpgi.com/color-contrast-checker/) is a desktop application for contrast checking that also simulates different forms of color impairment.
15 | 
16 | ### Color impairment
17 | * [Color Oracle](https://colororacle.org/) is a desktop application for simulating color impairment on your entire screen.
18 | * [colourblind](https://github.com/Altreus/colourblind) is another simulation tool similar to Daltonize, but with more options (protanopia, protanomaly, deuteranopia, deuteranomaly, tritanopia, tritanomaly, achromatopsia, and achromatomaly) in a single bookmarklet.
19 | * [postcss-colorblind](https://github.com/btholt/postcss-colorblind) is a CSS build tool that modifies colors in your CSS to simulate [four common impairment groups](https://github.com/skratchdot/color-blind#color-blindness-table).
20 | 
21 | ## Accessibility review tools
22 | These tools can be used to test sites for Section 508 and WCAG compliance in browser:
23 | 
24 | * [Accessibility Insights](https://accessibilityinsights.io/) - Browser plugin (Chrome, Edge), Android and Windows applications for automated and guided manual testing for accessibility including WCAG 2.0 and 2.1. 
25 | * Accessibility Management Platform (AMP): [GSA-specific info](https://insite.gsa.gov/employee-resources/information-technology/508-accessibility/accessibility-management-platform-amp) and [general product info](https://www.levelaccess.com/solutions/software/amp/)
26 | * [Google's Accessibility Developer Tools](https://chrome.google.com/webstore/detail/accessibility-developer-t/fpkknkljclfencbdbgkenhalefipecmb?hl=en) is a Chrome plugin for running basic accessibility tests from the comfort of your browser.
27 | * [Web Accessibility Toolbar (WAT)](https://www.dhs.gov/publication/web-accessibility-toolbar) is an IE tool that has been developed to aid manual examination of web pages for a variety of aspects of accessibility. It is used by [DHS's Trusted Tester program](https://www.dhs.gov/trusted-tester).
28 | * [WAVE](https://wave.webaim.org/) is an accessibility auditor and browser extension with document inspection features.
29 | * The [W3C](https://www.w3.org/) maintains a comprehensive [list of web accessibility evaluation tools](https://www.w3.org/WAI/ER/tools/).
30 | 
31 | ## Autocomplete widgets
32 | These JavaScript widgets produce HTML with [ARIA autocomplete](https://www.w3.org/TR/wai-aria/#aria-autocomplete) attributes:
33 | 
34 | * [Awesomplete](https://projects.verou.me/awesomplete/) is dependency-free
35 | * [jQuery UI autocomplete](http://jqueryui.com/autocomplete/) requires jQuery
36 | * [Select2](https://select2.org/) also requires jQuery
37 | 
38 | ## Automated testing
39 | 
40 | Automated testing tools can help you find some of the more common accessibility mistakes quickly, however no automated tool can detect all accessibility issues. [A recent experiment by the UK's Government Digital Service](https://accessibility.blog.gov.uk/2017/02/24/what-we-found-when-we-tested-tools-on-the-worlds-least-accessible-webpage/) found that the best automated tools only caught about 40 percent of the errors on a test site; some of the most popular tools caught less than 20 percent. Whatever automated tool you use, be sure to also do manual testing. 
41 | 
42 | These tools can be used in automated tests and with continuous integration
43 | tools to help you ensure that your sites remain accessible throughout the
44 | development process:
45 | 
46 | * [Accessibility Insights](https://accessibilityinsights.io/) - Browser plugin (Chrome, Edge), Android and Windows applications for automated and guided manual testing for accessibility including WCAG 2.0 and 2.1. 
47 | * [axe](https://www.deque.com/axe/) - Suite of automated accessibility testing tools built around the open source [axe-core testing engine/ruleset](https://github.com/dequelabs/axe-core), by Deque.
48 | * [pa11y](http://pa11y.org/) consists of a suite of tools including command-line and JavaScript APIs, a [web service](https://github.com/nature/pa11y-webservice), and a [dashboard](https://github.com/nature/pa11y-dashboard) for monitoring accessibility reports across multiple sites. [Pa11y with axe-core is recommended in the 18F Engineering Practices Guide](https://engineering.18f.gov/accessibility-scanning/) for automated accessibility scans.
49 | 
50 | There are many other [npm](https://www.npmjs.com/) packages tagged [wcag](https://www.npmjs.com/search?q=wcag) and [a11y](https://www.npmjs.com/search?q=a11y).


--------------------------------------------------------------------------------
/pages/tables.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | title: Tables
  3 | description: 'How we deal with tables'
  4 | permalink: /tables/
  5 | page_title: Tables
  6 | layout: post
  7 | sidenav: docs
  8 | ---
  9 | 
 10 | When tables are used to show data, the header cells that relate to the data cells need to be programmatically linked. This makes table navigation for screen readers more accurate and meaningful.
 11 | 
 12 | **Simple tables** can have up to two levels of headings; one row of headers and/or one column of headings. A table with more than one row or more than one column of headings is considered to be a complex table. Each table header cell should have `<th scope='col'>` or `<th scope='row'>`.
 13 | 
 14 | **Note:** Simple tables with headers in the first row and/or column don’t actually need the scope attribute for assistive technology to read them correctly. However, 508 test procedures within the federal government require table headings to have either `scope` or `id` attributes. 
 15 | 
 16 | **Complex tables** are tables with more than two levels of `headers`. Each header (`th`) should be given a unique `id`, and each data cell (`td`) should have a `headers` attribute with each related header cell’s `id` listed.
 17 | 
 18 | If a table has text associated with it, ensure the text is programmatically linked to the table. This is usually accomplished with a `<caption>` element. This element should be the first element under the `<table>` element. While a `caption` is not required, it can be very helpful to screen reader users navigating the page. A `caption` element is **strongly** encouraged on data tables to give context to the data.
 19 | 
 20 | ## Testing
 21 | 
 22 | 1. Identify 'data' tables (layout tables are exempt).
 23 | 2. View the table source code.
 24 | 3. Identify the table `headers`.
 25 |   * Check for `scope` on simple tables.
 26 |   * Check for `id` and headers on complex tables.
 27 | 
 28 | ## Examples
 29 | 
 30 | ### Passes
 31 | 
 32 | #### Simple table
 33 | 
 34 | <table>
 35 |   <caption>User’s Height and Age</caption>
 36 |   <tr>
 37 |     <th scope='col'>
 38 |       Name
 39 |     </th>
 40 |     <th scope='col'>
 41 |       Height
 42 |     </th>
 43 |     <th scope='col'>
 44 |       Age
 45 |     </th>
 46 |   </tr>
 47 |   <tr>
 48 |     <th scope='row'>
 49 |       Walter
 50 |     </th>
 51 |     <td>6'4</td>
 52 |     <td>34</td>
 53 |   </tr>
 54 |   <tr>
 55 |     <th scope='row'>
 56 |       Steve
 57 |     </th>
 58 |     <td>5'4</td>
 59 |     <td>30</td>
 60 |   </tr>
 61 | </table>
 62 | 
 63 | ```html
 64 | <table>
 65 |   <caption>User’s Height and Age</caption>
 66 |   <tr>
 67 |     <th scope='col'>
 68 |       Name
 69 |     </th>
 70 |     <th scope='col'>
 71 |       Height
 72 |     </th>
 73 |     <th scope='col'>
 74 |       Age
 75 |     </th>
 76 |   </tr>
 77 |   <tr>
 78 |     <th scope='row'>
 79 |       Walter
 80 |     </th>
 81 |     <td>6'4</td>
 82 |     <td>34</td>
 83 |   </tr>
 84 |   <tr>
 85 |     <th scope='row'>
 86 |       Steve
 87 |     </th>
 88 |     <td>5'4</td>
 89 |     <td>30</td>
 90 |   </tr>
 91 | </table>
 92 | ```
 93 | 
 94 | > Looking at this table, the column `headers` all relate to the cells below. This is done programmatically with ```scope='col'```. Each height and age value is programmatically related to the person via ```scope="row"```.
 95 | 
 96 | #### Complex table
 97 | 
 98 | <table>
 99 |   <caption>User’s Height and Weight</caption>
100 |   <tr>
101 |     <th rowspan='2' id='name' scope='col'>
102 |       Name
103 |     </th>
104 |     <th colspan='2' id='height' scope='col'>
105 |       Height
106 |     </th>
107 |     <th rowspan='2' id='age' scope='col'>
108 |       Age
109 |     </th>
110 |   </tr>
111 |   <tr>
112 |     <th id='feet' headers='height' scope='col'>
113 |       Feet
114 |     </th>
115 |     <th id='inches' headers='height' scope='col'>
116 |       Inches
117 |     </th>
118 |   </tr>
119 |   <tr>
120 |     <th headers='name' scope='row'>
121 |       Walter
122 |     </th>
123 |     <td headers='height feet'>6</td>
124 |     <td headers='height inches'>4</td>
125 |     <td headers='age'>34</td>
126 |   </tr>
127 |   <tr>
128 |     <th headers='name' scope='row'>
129 |       Steve
130 |     </th>
131 |     <td headers='height feet'>5</td>
132 |     <td headers='height inches'>4</td>
133 |     <td headers='age'>30</td>
134 |   </tr>
135 | </table>
136 | 
137 | ```html
138 | <table>
139 |   <caption>User's Height and Weight</caption>
140 |   <tr>
141 |     <th rowspan='2' id='name'>
142 |       Name
143 |     </th>
144 |     <th colspan='2' id='height'>
145 |       Height
146 |     </th>
147 |     <th rowspan='2' id='age'>
148 |       Age
149 |     </th>
150 |   </tr>
151 |   <tr>
152 |     <th id='feet' headers='height'>
153 |       Feet
154 |     </th>
155 |     <th id='inches' headers='height'>
156 |       Inches
157 |     </th>
158 |   </tr>
159 |   <tr>
160 |     <th headers='name' id='walter'>
161 |       Walter
162 |     </th>
163 |     <td headers='height feet walter'>6</td>
164 |     <td headers='height inches walter'>4</td>
165 |     <td headers='age walter'>34</td>
166 |   </tr>
167 |   <tr>
168 |     <th headers='name' id='steve'>
169 |       Steve
170 |     </th>
171 |     <td headers='height feet steve'>5</td>
172 |     <td headers='height inches steve'>4</td>
173 |     <td headers='age steve'>30</td>
174 |   </tr>
175 | </table>
176 | ```
177 | 
178 | > This is an example of a complex table. All the cells are associated with their respective headers via the ```headers``` attribute. Most tables don’t require this level of complexity.
179 | 


--------------------------------------------------------------------------------
/_sass/_uswds-theme-custom-styles.scss:
--------------------------------------------------------------------------------
  1 | 
  2 | //// 18F styles
  3 | 
  4 | // Color
  5 | $color-light:        color("cyan-10v"); // was #b3efff
  6 | $color-bright:       color("cyan-30v"); // was #00cfff
  7 | $color-medium:       color("primary");
  8 | $color-dark:         color("primary-dark"); // was #1C304A
  9 | $color-base:         color("primary-dark"); // was #1F2E4A
 10 | $color-black:        color("black");
 11 | $color-inverse:      color("white");
 12 | 
 13 | $color-bright-hover: color("accent-cool-dark");
 14 | $color-medium-hover: color("blue-60");
 15 | 
 16 | $color-gray-lightest: color("base-lightest"); // Adding bc used in our $border-light in this file.
 17 | $color-gray-hover:    color("gray-2");
 18 | $color-gray-divider:  color("gray-20");
 19 | 
 20 | $color-gray-border:   color("base-dark");
 21 | 
 22 | $logo-size-lg: 3rem;
 23 | $logo-size-md: 2rem;
 24 | 
 25 | // Typography
 26 | .usa-prose{
 27 |   h1,h2,h3,h4,h5,h6 {
 28 |     color: $color-dark;
 29 |   }
 30 | 
 31 |   p, li {
 32 |     color: $color-base;
 33 |   }
 34 | }
 35 | .usa-list li,
 36 | .usa-prose>ul li,
 37 | .usa-prose>ol li {
 38 |   margin-bottom: units(0.5);
 39 | }
 40 | .usa-prose>ul li>ul,
 41 | .usa-prose>ul li>ol,
 42 | .usa-prose>ol li>ul,
 43 | .usa-prose>ol li>ol {
 44 |   margin-top: units(1.5);
 45 | }
 46 | 
 47 | // Links
 48 | a {
 49 |   color: $color-medium;
 50 | }
 51 | 
 52 | a:hover {
 53 |   color: $color-medium-hover;
 54 | }
 55 | 
 56 | // Header
 57 | .usa-nav .usa-current::after,
 58 | .usa-header--extended .usa-current:hover::after,
 59 | .usa-nav__primary>.usa-nav__primary-item > .usa-current:hover::after {
 60 |   background-color: $color-bright;
 61 |   height: units(0.5);
 62 | }
 63 | 
 64 | .usa-nav__primary>.usa-nav__primary-item > .usa-current,
 65 | .usa-nav__primary>.usa-nav__primary-item > a:hover {
 66 |   color: $color-black;
 67 | }
 68 | 
 69 | .usa-nav__primary>.usa-nav__primary-item > a:hover {
 70 |   background-color: $color-gray-lightest;
 71 | }
 72 | 
 73 | .usa-nav__primary>.usa-nav__primary-item > a:hover::after {
 74 |   height: 0;
 75 | }
 76 | 
 77 | .usa-nav__secondary-links {
 78 |   display: none;
 79 | }
 80 | 
 81 | // logo
 82 | .usa-header.usa-header--extended .usa-logo-img {
 83 |   height: $logo-size-md;
 84 | }
 85 | 
 86 | .usa-logo__text {
 87 |   line-height: $logo-size-md;
 88 | }
 89 | 
 90 | 
 91 | @include at-media('desktop') {
 92 |   .usa-header.usa-header--extended .usa-logo-img {
 93 |     height: $logo-size-lg;
 94 |   }
 95 | 
 96 |   .usa-logo__text {
 97 |     line-height: $logo-size-lg;
 98 |   }
 99 | }
100 | 
101 | // usa-sidenav
102 | 
103 | .usa-sidenav a {
104 |   color: $color-base;
105 | }
106 | 
107 | .usa-sidenav > .usa-sidenav__item {
108 |   padding-left: 0;
109 | }
110 | 
111 | .usa-sidenav .usa-current {
112 |   color: $color-dark;
113 | }
114 | 
115 | .usa-sidenav .usa-current::after {
116 |   background-color: $color-bright;
117 |   border-radius: 0;
118 |   width: units(1);
119 |   top: 0;
120 |   bottom: 0;
121 | }
122 | 
123 | .usa-sidenav a:hover {
124 |   color: inherit;
125 |   background-color: $color-gray-lightest;
126 | }
127 | 
128 | //// Customization
129 | 
130 | // Ensure skip to main content link is visible
131 | .usa-skipnav:focus {
132 |   z-index: 9999;
133 | }
134 | 
135 | // Set max-width on container to contain lines
136 | .usa-layout-docs__main {
137 |   max-width: units("tablet");
138 | }
139 | 
140 | // Set line-height to specify distance between lines of text
141 | .usa-prose > h1,
142 | .usa-prose > h2,
143 | .usa-prose > h3,
144 | .usa-prose > h4,
145 | .usa-prose > h5,
146 | .usa-prose > h6 {
147 |   @include u-line-height("heading", 3);
148 | }
149 | 
150 | // Set property values for code block
151 | pre {
152 |   white-space: pre-wrap;
153 | }
154 | 
155 | // Show Slack icon before Slack Links
156 | a[href^="https://gsa-tts.slack.com"]::before {
157 |   content: "";
158 |   $size: units(4);
159 |   width: $size;
160 |   height: $size;
161 |   display: inline-block;
162 |   vertical-align: middle;
163 |   margin: units(-2px) units(-0.5) 0;
164 |   background-size: 100%;
165 |   background-repeat: no-repeat;
166 |   background-image: url("/images/Slack_Mark.svg");
167 | }
168 | .usa-prose>ul.list-item--margin-bottom-extra>li,
169 | .usa-prose>ol.list-item--margin-bottom-extra>li {
170 |   @include u-margin-bottom(1.5);
171 | }
172 | 
173 | @include at-media("desktop") {
174 |   .usa-header--extended .usa-logo {
175 |     max-width: none;
176 |   }
177 | 
178 |   .usa-nav__primary>.usa-nav__primary-item {
179 |     @include u-font("ui", "xs");
180 |   }
181 | 
182 |   .usa-header--extended .usa-nav__primary-item>.usa-current::after {
183 |     background-color: $color-bright;
184 |   }
185 | 
186 |   .usa-header--extended .usa-nav__primary-item>.usa-nav__link:not(.usa-current):hover::after {
187 |     display: none;
188 |   }
189 | }
190 | 
191 | .usa-layout-docs__sidenav {
192 |   overflow: visible;
193 |   order: 0;
194 |   margin-bottom: units(3);
195 |   padding-top: 0;
196 |   position: relative;
197 | }
198 | 
199 | .usa-header .usa-logo a {
200 |   display: inline-block;
201 | }
202 | 
203 | @include at-media("desktop") {
204 |   .usa-layout-docs__sidenav {
205 |     @include grid-col(3);
206 |     position: sticky;
207 |   }
208 | 
209 |   .usa-layout-docs__main {
210 |     @include u-flex("fill");
211 |   }
212 | }
213 | 
214 | 
215 | //// Footer (usa-anchor styles)
216 | 
217 | // Fixing footer anchor to bottom
218 | @include at-media("desktop") {
219 |   body {
220 |     display: flex;
221 |     flex-direction: column;
222 |     min-height: 100vh;
223 |   }
224 | }
225 | 
226 | .usa-identifier {
227 |   margin-top: auto;
228 | }
229 | 
230 | @import 'syntax';
231 | 


--------------------------------------------------------------------------------
/pages/headings.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | title: Headings
  3 | description: 'Proper use of heading elements'
  4 | permalink: /headings/
  5 | page_title: Headings
  6 | layout: post
  7 | sidenav: docs
  8 | ---
  9 | 
 10 | When laying out a page, headings provide a semantic way to lay out sections of content. A heading element briefly describes the topic of the section it introduces. Heading elements are used by users of AT to navigate a page quickly and to understand the structure of a page. Also see [Landmarks](../landmarks/).
 11 | 
 12 | When using heading elements, reserve the `<h1>` element for the page title. On the home page, this is usually the title of the site and on other pages, this may be the page title. Use the `<h1>` element once per page—some assistive technology may be unable to read multiple `<h1>`s on a single page correctly. Other heading levels may be used more than once following document outline order.
 13 | 
 14 | **Note:** `<section>` and `<article>` elements may allow you to reset the heading order allowing you to "restart" heading levels at `<h1>` according to the HTML5 spec. At this point, we are unaware of any browsers that support this feature beyond general HTML5 conformance checkers. For this reason, we recommend developers maintain the document outline with `h1-h6` when using HTML5 outline elements.
 15 | 
 16 | For sub sections, use `<h2>` to `<h6>` in document outline order. `<h1>` is the most important and `<h6>` is the least. Avoid skipping headings. Avoid breaking document outline order (you may go from `<h1>` to `<h3>`, but never `<h3>` to `<h1>`).
 17 | 
 18 | For logos that are text-based, use `<em>` element. 
 19 | 
 20 | If your logo is an image and acting as the main heading of the page, add an `<h1>` element for its text and use a `sr-only` rule so it's visibly hidden but accessible to screen reader users.
 21 | 
 22 | The following code snippet shows one example of proper section and subsection heading hierarchy.
 23 | 
 24 | ```html
 25 | <h2>Section</h2> 
 26 | lorum ipsum 
 27 | <h3>Sub Section</h3>
 28 | lorum ipsum
 29 | ``` 
 30 | 
 31 | ## Testing
 32 | 
 33 | 1. Identify visual 'heading' elements 
 34 | 2. Check that all visual 'heading' elements use an `<h>` tag
 35 | 3. Verify that all sub heading elements have a higher number
 36 | 
 37 | ## Examples
 38 | 
 39 | ### Passes
 40 | 
 41 | <div>
 42 |   <h3>Category</h3>
 43 |   <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet auctor lectus. Curabitur non est nibh. Suspendisse vehicula fermentum quam. Donec lobortis diam a ligula faucibus mattis.</p>
 44 |   <h4>Sub Category 1</h4>
 45 |   <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet auctor lectus. Curabitur non est nibh. Suspendisse vehicula fermentum quam. Donec lobortis diam a ligula faucibus mattis.</p>
 46 |   <h4>Sub Category 2</h4>
 47 |   <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet auctor lectus. Curabitur non est nibh. Suspendisse vehicula fermentum quam. Donec lobortis diam a ligula faucibus mattis.</p>
 48 | </div>
 49 | 
 50 | ```html
 51 | <div>
 52 |   <h3>Category</h3>
 53 |   <p>
 54 |     Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
 55 |     Nam sit amet auctor lectus. Curabitur non est nibh. Suspendisse vehicula fermentum quam. 
 56 |     Donec lobortis diam a ligula faucibus mattis.
 57 |    </p>
 58 |   <h4>Sub category 1</h4>
 59 |   <p>
 60 |     Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
 61 |     Nam sit amet auctor lectus. Curabitur non est nibh. 
 62 |     Suspendisse vehicula fermentum quam. 
 63 |     Donec lobortis diam a ligula faucibus mattis.
 64 |    </p>
 65 |   <h4>Sub category 2</h4>
 66 |   <p>
 67 |     Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
 68 |     Nam sit amet auctor lectus. Curabitur non est nibh. 
 69 |     Suspendisse vehicula fermentum quam. 
 70 |     Donec lobortis diam a ligula faucibus mattis.
 71 |   </p>
 72 | </div>
 73 | ```
 74 | 
 75 | > This section has a main category and two sub categories. The sub categories are on the same level and as such use the the same heading element.
 76 | 
 77 | ### Fails
 78 | 
 79 | <div class="exampleFailure">
 80 |   <h3>Category</h3>
 81 |   <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet auctor lectus. Curabitur non est nibh. Suspendisse vehicula fermentum quam. Donec lobortis diam a ligula faucibus mattis.</p>
 82 |   <h2>Sub Category 1</h2>
 83 |   <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet auctor lectus. Curabitur non est nibh. Suspendisse vehicula fermentum quam. Donec lobortis diam a ligula faucibus mattis.</p>
 84 |   <h5>Sub Category 2</h5>
 85 |   <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet auctor lectus. Curabitur non est nibh. Suspendisse vehicula fermentum quam. Donec lobortis diam a ligula faucibus mattis.</p>
 86 | </div>
 87 | 
 88 | ```html
 89 | <div>
 90 |   <h3>Category</h3>
 91 |   <p>
 92 |     Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
 93 |     Nam sit amet auctor lectus. Curabitur non est nibh. 
 94 |     Suspendisse vehicula fermentum quam. 
 95 |     Donec lobortis diam a ligula faucibus mattis.
 96 |   </p>
 97 |   <h2>Sub category 1</h2>
 98 |   <p>
 99 |     Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
100 |     Nam sit amet auctor lectus. Curabitur non est nibh. 
101 |     Suspendisse vehicula fermentum quam. 
102 |     Donec lobortis diam a ligula faucibus mattis.
103 |    </p>
104 |   <h5>Sub category 2</h5>
105 |   <p>
106 |     Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
107 |     Nam sit amet auctor lectus. Curabitur non est nibh. 
108 |     Suspendisse vehicula fermentum quam. 
109 |     Donec lobortis diam a ligula faucibus mattis.
110 |   </p>
111 | </div>
112 | ```
113 | 
114 | > This section has several issues. The first sub category has a lower value than the main category. The second sub category has skipped a heading level which while is better, this can cause confusion as it's not clear if this category is the sub category of `Category` or `Sub category 1`
115 | 


--------------------------------------------------------------------------------
/_includes/components/header.html:
--------------------------------------------------------------------------------
  1 | {% if header %}
  2 |   <div class="usa-overlay"></div>
  3 | {% if header.type == 'basic' %}
  4 |   <header class="usa-header usa-header--basic" role="banner">
  5 | {% elsif header.type == 'basic-mega' %}
  6 |   <header class="usa-header usa-header--basic usa-header--basic-megamenu" role="banner">
  7 | {% elsif header.type == 'extended' or header.type == 'extended-mega' %}
  8 |   <header class="usa-header usa-header--extended" role="banner">
  9 | {% endif %}
 10 | 
 11 |   {% if header.type == 'basic' or header.type == 'basic-mega' %}
 12 |     <div class="usa-nav-container">
 13 |   {% endif %}
 14 |     <div class="usa-navbar">
 15 |       <div class="usa-logo" id="header-logo">
 16 |         <a
 17 |           href="{% if header.href %}{{ header.href }}{% else %}{{ site.baseurl }}/{% endif %}"
 18 |           title="Home">
 19 |           {% if header.logo %}
 20 |             <img
 21 |               class="usa-logo-img"
 22 |               src="{% if header.logo.external %}{{ header.logo.src }}{% else %}{{ header.logo.src | relative_url }}{% endif %}"
 23 |               alt="{{ header.logo.alt }}">
 24 |           {% endif %}
 25 |           <em class="usa-logo__text">
 26 |             {{ header.title | default: site.title }}
 27 |           </em>
 28 |         </a>
 29 |       </div>
 30 |       <button class="usa-menu-btn">Menu</button>
 31 |     </div>
 32 | 
 33 |     <nav role="navigation" class="usa-nav">
 34 |       <div class="usa-nav__inner">
 35 |         <button class="usa-nav__close">
 36 |           <img src="{{ site.baseurl }}/assets/uswds/img/close.svg" alt="close">
 37 |         </button>
 38 | 
 39 |         {% assign _primary = header.primary.links %}
 40 |         {% assign primary_links = site.data.navigation[_primary] | default: _primary %}
 41 |         {% if primary_links %}
 42 |         <ul class="usa-nav__primary usa-accordion">
 43 |           {% for _section in primary_links %}
 44 |           <li class="usa-nav__primary-item">
 45 |             {% if _section.links %}
 46 |               {% assign section_links = site.data.navigation[_section.links] | default: _section.links %}
 47 |               {% assign _section_id = _section.id %}
 48 |               {% unless _section_id %}{% assign _section_id = 'nav-' | append: forloop.index %}{% endunless %}
 49 |             <button class="usa-accordion__button usa-nav__link" aria-expanded="false" aria-controls="{{ _section_id }}">
 50 |               <span>{{ _section.text }}</span>
 51 |             </button>
 52 |             {% if header.type == 'basic' or header.type == 'extended' %}
 53 |             <ul id="{{ _section_id }}" class="usa-nav__submenu">
 54 |             {% endif %}
 55 |             {% if header.type == 'basic-mega' or header.type == 'extended-mega' %}
 56 |             <div id="{{ _section_id }}" class="usa-nav__submenu usa-megamenu">
 57 |               <div class="grid-row grid-gap-4">
 58 |             {% endif %}
 59 |               {% for _link in section_links %}
 60 |                 {% if header.type == 'basic-mega' or header.type == 'extended-mega' %}
 61 |                 <!-- wrap every 3 links in a usa-megamenu-col div -->
 62 |                 {% capture modulo %}{{ forloop.index | modulo: 3 }}{% endcapture %}
 63 |                   {% if modulo == '1' %}
 64 |                     <div class="desktop:grid-col-3">
 65 |                       <ul class="usa-nav__submenu-list">
 66 |                   {% endif %}
 67 |                 {% endif %}
 68 |                 <li class="usa-nav__submenu-item">
 69 |                   <a href="{% if _link.external %}{{ _link.href }}{% else %}{{ _link.href | relative_url }}{% endif %}">{{ _link.text }}</a>
 70 |                 </li>
 71 |                 {% if header.type == 'basic-mega' or header.type == 'extended-mega' %}
 72 |                   {% if modulo == '0' or forloop.last %}
 73 |                     </ul>
 74 |                     </div>
 75 |                   {% endif %}
 76 |                 {% endif %}
 77 |               {% endfor %}
 78 |             {% if header.type == 'basic' or header.type == 'extended' %}
 79 |             </ul>
 80 |             {% endif %}
 81 |             {% if header.type == 'basic-mega' or header.type == 'extended-mega' %}
 82 |               </div><!-- /grid-row -->
 83 |             </div>
 84 |             {% endif %}
 85 |             {% else %}
 86 |               {% assign basedir = page.url | remove_first: '/' | split: '/' | first | lstrip %}
 87 |               {% assign linkdir = _section.href |  replace: "/", ""  | lstrip %}
 88 |               <a class="{% if _section.class %}{{ _section.class }}{% else %} usa-nav__link {% endif %} {% if linkdir == basedir %} usa-current{% endif %}" href="{% if _section.external %}{{ _section.href }}{% else %}{{ _section.href | relative_url }}{% endif %}">
 89 |                 <span>{{ _section.text }}</span>
 90 |               </a>
 91 |             {% endif %}
 92 |           </li>
 93 |           {% endfor %}
 94 |         </ul>
 95 |         {% endif %}
 96 | 
 97 |         {% if header.type == 'basic' or header.type == 'basic-mega' %}
 98 |           {% assign _secondary = header.secondary %}
 99 |           {% if site.search_site_handle  %}
100 |             <form
101 |               accept-charset="UTF-8"
102 |               action="https://search.usa.gov/search"
103 |               id="search_form"
104 |               method="get"
105 |               class="usa-search usa-search--small js-search-form">
106 |               <input
107 |                 name="utf8"
108 |                 type="hidden"
109 |                 value="&#x2713;" />
110 |               <input
111 |                 id="affiliate"
112 |                 name="affiliate"
113 |                 type="hidden"
114 |                 value="{{ site.search_site_handle }}" />
115 |               <div role="search">
116 |                 <label for="query" class="usa-sr-only">Enter Search Term(s):</label>
117 |                 <input
118 |                   autocomplete="off"
119 |                   class="usa-input usagov-search-autocomplete"
120 |                   id="query"
121 |                   name="query"
122 |                   type="search" />
123 |                 <button
124 |                   class="usa-button"
125 |                   type="submit"
126 |                   name="commit">
127 |                   <span class="usa-sr-only">Search</span>
128 |                 </button>
129 |               </div>
130 |             </form>
131 |             {% endif %}
132 |           {% endif %}
133 | 
134 |           {% if header.type == 'extended' or header.type == 'extended-mega' %}
135 |           {% assign _secondary = header.secondary %}
136 |           <div class="usa-nav__secondary">
137 |             <ul class="usa-unstyled-list usa-nav__secondary-links">
138 |               {% assign secondary_links = site.data.navigation[_secondary.links] | default: _secondary.links %}
139 |               {% for _link in secondary_links %}
140 |                 <li class="usa-nav__secondary-item">
141 |                   <a href="{% if _link.external %}{{ _link.href }}{% else %}{{ _link.href | relative_url }}{% endif %}"
142 |                   {% if _link.class %} class="{{ _link.class }}" {% endif %}>
143 |                     {{ _link.text }}
144 |                   </a>
145 |                 </li>
146 |               {% endfor %}
147 |             </ul>
148 |             {% if site.search_site_handle  %}
149 |               <form
150 |                 accept-charset="UTF-8"
151 |                 action="https://search.usa.gov/search"
152 |                 id="search_form"
153 |                 method="get"
154 |                 class="usa-search usa-search--small js-search-form">
155 |               <input
156 |                 name="utf8"
157 |                 type="hidden"
158 |                 value="&#x2713;" />
159 |               <input
160 |                 type="hidden"
161 |                 name="affiliate"
162 |                 id="affiliate"
163 |                 value="{{ site.search_site_handle }}" />
164 |                 <div role="search">
165 |                   <label
166 |                     for="query" class="usa-sr-only">Enter search terms</label>
167 |                   <input
168 |                     autocomplete="off"
169 |                     class="usa-input usagov-search-autocomplete"
170 |                     id="query"
171 |                     name="query"
172 |                     type="search" />
173 |                   <button
174 |                     class="usa-button"
175 |                     type="submit"
176 |                     name="commit">
177 |                     <span class="usa-sr-only">Search</span>
178 |                   </button>
179 |                 </div>
180 |               </form>
181 |             {% endif %}
182 |           </div>
183 |           {% endif %}
184 | 
185 | 
186 |         </div>
187 |       </div>
188 |     </nav>
189 |   {% if header.type == 'basic' or header.type == 'basic-mega' %}
190 |     </div>
191 |   {% endif %}
192 |   </header>
193 | {% endif %}
194 | 


--------------------------------------------------------------------------------
/pages/forms.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | title: Forms
  3 | description: 'How we work with forms'
  4 | permalink: /forms/
  5 | page_title: Forms
  6 | layout: post
  7 | sidenav: docs
  8 | ---
  9 | Making forms accessible is a simple process. Each form element should be associated with its instructions and errors, and everything should be accessible via the keyboard.
 10 | 
 11 | ## Testing
 12 | 
 13 | 1. Identify each form element.
 14 | 2. Find all instructions associated with each element.
 15 |   * __It is a failure if a form element isn't programmatically associated with _all_ instructions. This includes legends, labels, hint text and tooltips.__
 16 |   * A common way of achieving this is using `fieldset` and `legend` tags. `Fieldset` is used to group a set of elements. `Legend` is the first child of a `fieldset` tag and provides context for those fields. 
 17 | 3. Ensure all field elements are accessible via the keyboard.
 18 |   * __If the form cannot be filled out with just a keyboard, this is a failure.__
 19 | 4. Check for title attributes
 20 |   * Title attributes can be a substitute for labels.
 21 |   * __If the title attributes provides all the related information it passes, if it provides extra information it fails.__
 22 |     * Title attributes are not accessible via keyboard.
 23 | 
 24 | ## Examples
 25 | ### Passes
 26 | 
 27 | <fieldset>
 28 |   <legend>Name</legend>
 29 |   <label for="firstname">First</label>
 30 |   <input type='text' id='firstname'>
 31 |   <label for="lastname">Last</label>
 32 |   <input type='text' id='lastname'>
 33 | </fieldset>
 34 | 
 35 | <fieldset>
 36 |   <legend>Favorite Soup?</legend>
 37 |   <input type='radio' name='soup' value='pea' id='peasoup' title='Pea Soup'><label for="peasoup">Pea Soup</label>
 38 |   <input type='radio' name='soup' value='chicken' id='chicken' title='Chicken Noodle'><label for="chicken">Chicken Noodle</label>
 39 |   <input type='radio' name='soup' value='tomato' id='tomato' title='Tomato'><label for="tomato">Tomato</label>
 40 | </fieldset>
 41 | <br>
 42 | 
 43 | ```html
 44 | <fieldset>
 45 |   <legend>Name</legend>
 46 |   <label for="firstname">First</label>
 47 |   <input type='text' id='firstname'><br>
 48 |   <label for="lastname">Last</label>
 49 |   <input type='text' id='lastname'>
 50 | </fieldset>
 51 | 
 52 | <fieldset>
 53 |   <legend>Favorite Soup?</legend>
 54 |   <input type='radio' name='soup' value='pea' id='peasoup' title='Pea Soup'><label for="peasoup">Pea Soup</label>
 55 |   <input type='radio' name='soup' value='chicken' id='chicken' title='Chicken Noodle'><label for="chicken">Chicken Noodle</label>
 56 |   <input type='radio' name='soup' value='tomato' id='tomato' title='Tomato'><label for="tomato">Tomato</label>
 57 | </fieldset>
 58 | ```
 59 | > ___Name:___ Each form element has a ```label```, and it's associated with the ```for``` attribute. The ```for``` attribute refers to the ```id``` of the ```input```. When looking at this form, 'First' and 'Last' wouldn't make sense without 'Name.' This is associated with the ```fieldset``` and ```legend```. All elements are wrapped in a ```fieldset```. There can only be one ```legend``` tag per ```fieldset```. Anything in the ```legend``` tag will be associated.
 60 | 
 61 | > ___Favorite Soup:___ ```Fieldset``` and ```legend``` is often used for radio buttons as its the easiest way to associate the radio buttons with the question. Notice there are no ```label```s for the radio buttons, but each button has a ```title``` attribute for assistive technology to read.
 62 | 
 63 | ### Fails
 64 | 
 65 | <fieldset class="exampleFailure">
 66 |   <legend>Name</legend>
 67 |   <label for="first_name-2">First</label>
 68 |   <input type='text' id='firstname-2'>
 69 |   <label for="1lastname">Last</label>
 70 |   <input type='text' id='1lastname'>
 71 | </fieldset>
 72 | 
 73 | <fieldset class="exampleFailure">
 74 |   <legend>Favorite Soup?</legend>
 75 |   <span style='color:#990000;'>This Question Is Required</span>
 76 |   <input type='radio' name='soup' value='pea' id='pea-2' title='Chick Pea Soup'><label for="pea-2">Pea Soup</label>
 77 |   <input type='radio' name='soup' value='chicken' id='chicken-2' title='Chicken Noodle'><label for="chicken-2">Chicken Noodle</label>
 78 |   <input type='radio' name='soup' value='tomato' id='tomato-2' title='Tomato'><label for="tomato-2">Tomato</label>
 79 | </fieldset>
 80 | <br>
 81 | 
 82 | ```html
 83 | <fieldset>
 84 |   <legend>Name</legend>
 85 |   <label for="first_name-2">First</label>
 86 |   <input type='text' id='firstname-2'>
 87 |   <label for="1lastname">Last</label>
 88 |   <input type='text' id='1lastname'>
 89 | </fieldset>
 90 | 
 91 | <fieldset>
 92 |   <legend>Favorite Soup?</legend>
 93 |   <span style='color:#990000;'>This Question Is Required</span>
 94 |   <input type='radio' name='soup' value='pea' id='pea-2' title='Chick Pea Soup'><label for="pea-2">Pea Soup</label>
 95 |   <input type='radio' name='soup' value='chicken' id='chicken-2' title='Chicken Noodle'><label for="chicken-2">Chicken Noodle</label>
 96 |   <input type='radio' name='soup' value='tomato' id='tomato-2' title='Tomato'><label for="tomato-2">Tomato</label>
 97 | </fieldset>
 98 | <br>
 99 | ```
100 | 
101 | > ___Failure:___ First name label ```for``` and ```id``` don't match.
102 | 
103 | > ___Failure:___ "This Question Is Required" is not associated with the form fields.
104 | 
105 | > ___Failure:___ The ```title``` tag for Pea Soup indicates it's 'Chick Pea Soup.' This information is not available to keyboard, sighted users.
106 | 
107 | 
108 | ### How ARIA affects form inputs
109 | 
110 | Screen readers vary on what they read and the additional information they provide by default. This is a broad summary of what is read based on VoiceOver for Mac OSX.
111 | 
112 | You can test these with your own screen reader. If you have a OSX you can turn VoiceOver on by hitting command+F5.
113 | 
114 | **Further information** Using `aria-label` or `aria-labelledby` will cause a screen reader to only read them and not the default label. If you want an input to read from multiple things like an error message, use `aria-labelledby` and pass it the `for` attribute of the label and any additional `id`s you want read. ex. `aria-labelledby='car1 car_description car-error-message'`
115 | 
116 | #### No ARIA
117 | 
118 | Reads just the `label` and not the description
119 | 
120 | <label for="car_1">Car</label>
121 | <input type="text" id="car_1"/><br/>
122 | <span id='carmakedescription'><i>Please enter Make and Model</i></span>
123 | 
124 | ```html
125 | <label for="car_1">Car</label>
126 | <input type="text" id="car_1"/><br/>
127 | <span id="carmakedescription_1"><i>Please enter Make and Model</i></span>
128 | ```
129 | 
130 | **Screen reader reads input as:** `Car Edit text`
131 | <hr>
132 | 
133 | #### With aria-label
134 | 
135 | Reads the `aria-label` and doesn't read the normal `label`.
136 | 
137 | <label for="car_2">Car</label>
138 | <input type="text" id="car_2" aria-label="Car, please enter make and model" /><br/>
139 | <span id='carmakedescription_2'><i>Please enter Make and Model</i></span>
140 | 
141 | ```html
142 | <label for="car_2">Car</label>
143 | <input type="text" id="car_2" aria-label="Car, please enter make and model" /><br/>
144 | <span id="carmakedescription_2"><i>Please enter Make and Model</i></span>
145 | ```
146 | 
147 | **Screen reader reads input as:** `Car, please enter make and model Edit text`
148 | <hr>
149 | 
150 | #### With aria-labelledby pointing at `carmakedescription`
151 | 
152 | Reads only the `aria-labelledby` attribute and not the default label
153 | 
154 | <label for="car_3">Car</label>
155 | <input type="text" id="car_3" aria-labelledby="carmakedescription_3" /><br/>
156 | <span id='carmakedescription_3'><i>Please enter Make and Model</i></span>
157 | 
158 | ```html
159 | <label for="car_3">Car</label>
160 | <input type="text" id="car_3" aria-labelledby="carmakedescription_3" /><br/>
161 | <span id='carmakedescription_3'><i>Please enter Make and Model</i></span>
162 | ```
163 | 
164 | **Screen reader reads input as:** `Please enter Make and Model Edit text`
165 | <hr>
166 | 
167 | #### With aria-labelledby pointing at `carlabel carmakedescription`
168 | 
169 | Reads both labels indicated by the `aria-labelledby` attribute
170 | 
171 | <label for="car_4" id="carlabel_4">Car</label>
172 | <input type="text" id="car_4" aria-labelledby="carlabel_4 carmakedescription_4" /><br/>
173 | <span id="carmakedescription_4"><i>Please enter Make and Model</i></span>
174 | 
175 | ```html
176 | <label for="car_4" id="carlabel_4">Car</label>
177 | <input type="text" id="car_4" aria-labelledby="carlabel_4 carmakedescription_4" /><br/>
178 | <span id="carmakedescription_4"><i>Please enter Make and Model</i></span>
179 | ```
180 | 
181 | **Screen reader reads input as:** `Car Please enter Make and Model Edit text`
182 | <hr>
183 | 
184 | #### With aria-describedby pointing at `carmakedescription`
185 | 
186 | JAWS reads both the label and the description. So does VoiceOver, but there is a slight delay before it reads the description.
187 | 
188 | <label for="car_5">Car</label>
189 | <input type="text" id="car_5" aria-describedby="carmakedescription_5" /><br/>
190 | <span id='carmakedescription_5'><i>Please enter Make and Model</i></span>
191 | 
192 | ```html
193 | <label for="car_5">Car</label>
194 | <input type="text" id="car_5" aria-describedby="carmakedescription_5" /><br/>
195 | <span id='carmakedescription_5'><i>Please enter Make and Model</i></span>
196 | ```
197 | 
198 | **Screen reader reads input as:** `Car Edit text Please enter Make and Model`
199 | <hr>
200 | 


--------------------------------------------------------------------------------