search

PublicisSapient / enable-a11y

MIT License
11 stars 5 forks source link

readme

enable-a11y

A place to learn and share with developers what makes web work accessible. This includes a list of demos to show how aria roles function with screen readers.

Official Enable Website

Getting Started

Prerequisite Installations

Note: Any changes to these prerequisites will need to be reflected in the GitHub Actions in order to run the CI/CD checks.

Optional installations (since npm run server will run an express server)

Setup

  1. Run the following commands in your Terminal or Terminal equivalent program:

    git clone git@github.com:PublicisSapient/enable-a11y.git
cd enable-a11y
    nvm use

    This instructs nvm to use the Node version specified in the .nvmrc file located in the project root directory.

    Note: If the specified version has not been installed yet, nvm will advise to install it after running the command above.

    npm clean-install

    Note: Using clean-install instead of just install installs the exact package versions listed in the package-lock.json, and therefore has guaranteed compatibility.

  2. Start the local server using:

    npm run start

  3. Open http://localhost:8888 in your browser to see the local version of the site.

  4. Make sure everything is installed correctly by running the automated tests using npm run test.

    See the Chromedriver issues section if you encounter an error related to Chromedriver.

    Make sure your local server is running in another terminal before running npm run test.

Tests

Tools used for testing

Read the Enable Code Quality article for the full details behind the testing tools being used and how.

Commands

If you are noticing that the jest tests are taking a long time, you might want to run npm run jest-debug-memory-leak. If the heap size for each test group increases a lot, there is a memory leak in the tests. More information about that can be found at in the article Your Jest Tests are Leaking Memory by David Chanin

Hint: Make sure the local server is running first using the npm run start command.

Chromedriver issues

Your version of Chrome needs to match the chromedriver package version. You can find your version of Chrome (ie. 121.x.xxxx.xxx) by checking the version number inside the "About Chrome" dialog in Chrome.

If there is a problem with running Chromedriver, because you have an error like "SessionNotCreatedError: session not created: This version of ChromeDriver only supports Chrome version XXX", then you should ensure your chromedriver is installed with the right version.

You can change the version of chromedriver installed with this project by using npm install -D chromedriver@XXX, and replacing XXX with the same version of Chrome you already have installed (ie. npm install -D chromedriver@121).

Links at the Chrome for Testing availability webpage allow you to download a separate "Chrome for Testing" application, and/or the associated chromedriver files.

You can also download a chromedriver version zip file from here: https://chromedriver.storage.googleapis.com/index.html and then install it using:

npm install -D chromedriver --chromedriver_filepath=/path/to/chromedriver_mac64.zip

(you may need to change the PATH variable)

If you still have problems with Chromedriver, you may want to read the Stack Overflow article Session Not Created: This version of ChromeDriver only supports Chrome version 98.

Development

Contributing code

If you would like to contribute to this project, please feel free to raise a Pull Request! See the documentation at Creating a pull request from a fork for instructions.

Style Notes

  1. All font-sizes are converted to rems. This is done via LESS. If you want a font-size of 20px, then you would do the following:

    div {
 font-size: (20 / @px);
}

    The @px variable is set to 16rem, which is also the base font size

  2. If we hide custom components and use CSS to create custom facades for them, we must ensure that these facades will be discoverable to users navigating by touch. For more information about being inclusive of users navigating by touch, please read Inclusively Hiding & Styling Checkboxes and Radio Buttons by Sara Soueidan.

Adding An External NPM Module To The Front-End Code

If you are adding examples to this repository and need support of an external NPM module for the front-end (like a JavaScript library), then you should add the library to the nodeFiles array in the file promote-node-modules-to-server.js.

For example, when I added the glider-js library to Enable so I can use it in the Carousel demos, I added the files I needed for the front-end to nodeFiles with these two lines:

const nodeFiles = [
  'node_modules/indent.js/lib/indent.min.js',
  'node_modules/glider-js/glider.js',
  'node_modules/glider-js/glider.css',
  'node_modules/text-zoom-event/dist/textZoomEvent.module.js',
  'node_modules/dialog-polyfill/index.js',
  'node_modules/jquery/dist/jquery.min.js',
  'node_modules/jquery-validation/dist/jquery.validate.min.js',
  'node_modules/accessibility-js-routines/dist/accessibility.module.js',
  'node_modules/wicg-inert/inert.min.js'
]

When you start the project with npm run server, the files in the nodeFiles array will be placed in the enable-node-libs directory in the project root. Use this directory to load the files in your scripts, css, or HTML files.

Pre-commit hook error - "npx: command not found"

If you encounter an error when trying to commit some code from within an IDE (like VS Code, IntelliJ, GitHub Desktop, etc.), and the error is about the npx command not being found, you should try running the command in the terminal instead. This issue is due to the PATH values not being set as expected in the IDE in order for npx to be recognized. See https://stackoverflow.com/questions/67115897/vscode-github-desktop-pre-commit-hook-npx-command-not-found for more information.

VNU validation error

If your build is failing due to an invalid error with VNU (i.e. a false positive), you can update 'data/vnu-filters' with the corresponding error message. This will ignore these invalid errors and allow your build to complete.

Pull Request from fork not completing CI/CD tests

If you are trying to contribute to the Enable site from a forked version of this repository, and the automatic tests in your Pull Request only ever show "Some checks haven't completed yet" and "Expected - Waiting for status to be reported" (see an example in the image below), then you may need to update the settings in your forked repository. The "Allow all actions and reusable workflows" option within the Actions section of the settings should be selected. Please go to the Using GitHub Actions to Run the Tests in the CI/CD Pipeline section on this site for more details on how to find this option. After changing the setting, you will need to retrigger the actions by making another commit.

View of a GitHub PR with the "Some checks haven't completed yet" message

I Made a New Component! How do I make sure it is available on NPM

You will need to update the version number that NPM broadcasts as the latest version number. Please use np to do this (it is what we have used in the past). This should be done by development lead of the Enable project (as of this writing, this is Zoltan Hawryluk).

Strcutured Data Markup

Structured Data Markup is a way to label or tag the content on your website so that search engines and other platforms can better understand it.

The Article and HowTo tags are two types of structured data markup that help search engines understand specific kinds of content.

Article Tag:

This is used to mark up articles, blog posts, or other written content. By using the Article tag, we help search engines identify the main parts of your article, like the headline. This can make your article show up better in search results, sometimes with extra features like the headline or image preview.

HowTo Tag:

This is used for content that gives step-by-step instructions on how to do something. When you use the HowTo tag, search engines can display your instructions in a more detailed way, often showing each step directly in the search results.

Example of checkbox in the meta-info.json, where the mainEntity can be an array of 'Article' and 'HowTo' objects extracted from page:

"checkbox.php": {
    "title": "How to Create Accessible Checkboxes",
    "desc": "Here is a step-by-step guide to creating accessible checkboxes",
    "url": "https://www.useragentman.com/enable/checkbox.php",
    "mainEntity":[
      {
      "type": "Article",
      "title": "A real styled HTML5 checkbox",
      "desc": "You can style an HTML5 checkbox using CSS easily.",
      "url": "https://www.useragentman.com/enable/checkbox.php#a-real-styled-html5-checkbox--heading"
      },
      {
      "type": "HowTo",
      "title": "Step-by-Step to make the styled checkboxe accessible",
      "desc": "See the dropdown to highlight each of the individual steps that make the styled checkboxe accessible",
      "url": "https://www.useragentman.com/enable/checkbox.php#developer-walkthrough-1"
      },
  ]
}

References

When testing using screen readers, these resources may be of help to you: