googlecodelabs/angular-accessibility

Build more accessible Angular apps: Dumpling Shop demo

Build more accessible Angular apps : Dumpling Shop demo

Demo for the Build more accessible Angular apps codelab.

Get set up

Run npm install to install the dependencies required to run the server.

Run git checkout get-started to use the get-started branch for the codelab. All solutions can be found in the main branch.

Run ng serve --hmr to run the server.

Open a browser tab to http://localhost:4200. The app will automatically reload if you change any of the source files.

Disclaimer

This is a demo from @twerske and the Angular team, and not an officially supported Google product.

angular-accessibility's Issues

BUG: Outdated packages

The app needs to be updated quite a bit. Angular deprecated support for protractor a few versions back. Might want to check out https://goo.gle/state-of-e2e-in-angular for details. Similarly, tslint has been replaced by eslint. And core-js-pure just puts up a messaging telling you not to even use it any more.

That's if you can get past step one, since npm install fails. I had to to npm install --force just to get it to work.

Step 12 has errors

replace 'cdk-high-contrast' with 'cdk.high-contrast' as is used in the master branch.

Tutorial Feedback

First of all, thanks so much for this. I'll be able to use this as a training too for my team as we're starting to build up an a11y competency in our dev team. I went through the entirety and found a few things I'd like to offer back.

The numbered list represents the feedback for each step as it's numbered in the tutorial.

1. ✅✅ Great intro
2. ✅✅ Good setup instructions
3. ✅❌ Good walkthrough for getting the tools set up. However
   • The .eslintrc.json file already has the configs in it
   • My Lighthouse results differ: [shop: 89, about: 96, find: 91]
   • Please explain how you identified your list of issues to fix based on the tools and manual testing. Learning how to compile a list is the basis for identifying fixes
4. ✅👨🏼‍💻 Intro to this tool was really helpful. A modification to prevent redundancy if you like:

    // Routes
    { path: 'shop', component: ShopComponent, data: { title: 'Our Shop' } },
    { path: 'about', component: AboutComponent, data: { title: 'Our Story' } },
    { path: 'locate', component: LocationComponent, data: { title: 'Find Us' } },

    // app component
    this.router.events
        .pipe(...)
        .subscribe((title) => {
            const uniqueTitleParts = new Set<string>([title, appTitle]);

            this.titleService.setTitle(
                Array.from(uniqueTitleParts).join(' | ') // or ' - ' if you prefer
            );
        });

5. ✅✅ Great demo of how to discover and rectify contrast issues though, this does feel very material specific. If you haven't used material before it ends up as a copy/paste and then move on feeling. Maybe referencing the material docs would be helpful

6. ✅❌ Does a great job at demonstrating the separation between semantics and styles in the component.

   • However, per the html spec, heading hierarchy should start at h1. When I went looking for the h1, I found it in the nav component where it's used to style the name of the app which is an incorrect usage based on the html spec.
   • and, I believe, per WCAG 1.3.1 and 2.4.6
   • The way the h1 is being used doesn't represent the page, it represents the site.
     From my research, I believe the h1 should be a part of the main landmark element. Strategies for correcting this when it comes to making a proper page outline, are to place it in the DOM and potentially hide it for visual users using a screen-reader-only class. I believe the proper content of the h1 should be what I have in the title property of the suggested route config above (not containing the entire text of the title but just the most relevant piece).

7. ❓ I'm split on this one. The solution definitely does make the interaction accessible and I think the design is ultimately better but, in the redesign, I feel like we lost 2 things:

   • The information about vegan options is lost
   • We didn't see how to actually address the a11y of the existing design
   • The color contrast that results from the code snippet using color="primary" does not meet contrast requirement. Changing it to color="accent" does meet the contrast requirement.

8. ✅❌ The concept is well conveyed. However:

   • while Voiceover is active in Chrome, I am unable to move the slider using the controls dictated to me by Voiceover (or any other key combo).
     • This is likely a material issue though.
   • The color contrast that results from the code snippet using color="primary" does not meet contrast requirement. Changing it to color="accent" does meet the contrast requirement and matches the screenshot provided in the tutorial.

9. ✅✅

10. ✅✅ Potentially linking to the directive docs could enhance this

11. ✅👨🏼‍💻 Intro to this service is was great! A couple of things that could improve it though:

    • Change the text from Select color: ${color} to Selected color: ${color}
    • Link to the docs of the service.
    • The docs do a great job of calling out why the service exists (testing) over using aria-live and would be good to include here.

12. ✅❌ I appreciated bringing high-contrast mode to light but, at least on my Mac, I could not find a way to turn on high-contrast mode for firefox. Links to documentation on how to test these things would really enhance this section.

Step 12: cdk-high-contrast error

Hi! the Step12 have an error, on the code you show this:

@import '~@angular/cdk/a11y';

.purchase-button {
    border-radius: 5px;
    background-color: mat.get-color-from-palette(mat.$pink-palette, A100);

    @include cdk-high-contrast {
      outline: solid 1px;
      background-color: mat.get-color-from-palette(mat.$pink-palette, 50);
    }
}

:host-context(.dark-theme) {
  .purchase-button {
    background-color: mat.get-color-from-palette(mat.$light-green-palette, A100);

    @include cdk-high-contrast {
      outline: solid 1px;
      background-color: mat.get-color-from-palette(mat.$light-green-palette, 50);
    }
  }
}

But the cdk-high-contrast it's an error and you should show it as: cdk.high-contrast, and the import should be: @use '@angular/cdk', this is the good one:

@import '@angular/cdk';

.purchase-button {
    border-radius: 5px;
    background-color: mat.get-color-from-palette(mat.$pink-palette, A100);

    @include cdk.high-contrast {
      outline: solid 1px;
      background-color: mat.get-color-from-palette(mat.$pink-palette, 50);
    }
}

:host-context(.dark-theme) {
  .purchase-button {
    background-color: mat.get-color-from-palette(mat.$light-green-palette, A100);

    @include cdk.high-contrast {
      outline: solid 1px;
      background-color: mat.get-color-from-palette(mat.$light-green-palette, 50);
    }
  }
}

Issues & suggestions

Hi! Thanks for the codelab! It was interesting and useful. Below are some issues & suggestions:

1. Setup

1. Issue: While completing this codelab on a MacBook, I ran into an issue following the setup steps.
   The issue: npm install (step 5) fails due to conflicting peer dependencies. Running npm install --force works. It seems like either dependencies or instructions should be updated.
2. Improvement: It would be useful to additionally specify (before or during step 5) that installing npm is a prerequisite for running npm install.

5. Ensure adequate color contrast
Conceptual: Although we fixed the contrast for the home/view type icons, we haven't solved all the high contrast issues on the page i.e. the number picker. It's strange to mark it as 'Done'

7. Create selectable controls with Angular Material
Conceptual: although we have solved the a11y concern, we had to change the intended content of the page. It would be great to show how we can use a11y to improve experience without changing what we need to convey.

10. Control focus with FocusTrap
Issue: For me, the focus is already trapped and does not exit the dialog. Adding cdkFocusInitial did not change anything.
Also, Focus is now initially set on Change Color in the dialog! doesn't make sense because there is no element Change Color.

11. Announce changes with LiveAnnouncer
Improvement: In src/app/shop/color-picker/color-picker-dialog/color-picker-dialog.component.ts, Inject and MAT_DIALOG_DATA should be additionally imported (this might be worth putting into the snippet).

12. Enable HighContrast mode
Issue: Copying code directly produces SassError: Undefined mixin. for cdk-high-contrast(). As per Angular Material docs it should be cdk.high-contrast(), and then the page works.

Additional suggestions:

1. Improvement: It would be useful to separate ungrouped line changes into different snippets (even within the same file).
2. Improvement: // TODO: #5. Ensure adequate color contrast in the codebase should have a tailing period to align with the codelab (to search for TODO in the codebase). Same goes for the following TODOs.

Full Keyboard accessibility

This was a great tutorial to get me started with accessibility. One thing I was trying to do was to completely navigate the sight with just using the keyboard with text to speech turned on. When displaying the navigation page "Our Story" I could not get into the page content so the screen reader would read the page. I am thinking the way this should work is by clicking the navigation menu item (using the enter key) the focus should go into the page content. Then I'm not sure how I would go from the page content back to the main navigation. Since I am new to focusing on Accessibility and just using the keyboard I might be missing something.

Any thoughts would be appreciated.

Hi, can I ask you a question?

Hi, can I ask you a question?