search

department-of-veterans-affairs / va.gov-cms

Editor-centered management for Veteran-centered content.
https://prod.cms.va.gov
GNU General Public License v2.0
98 stars 69 forks source link

[AXE-CORE] Heading levels should increase by one #9571

Open bkjohnson opened 3 years ago

bkjohnson commented 3 years ago

508-defect-2

User Story or Problem Statement

A CMS content editor adds content to a page using <h3> tags as the main non-title content heading. They also check (or don't uncheck) the box that says "Include table of contents". This results in only 1 <h2> being on the page which says "On this page", and this is unexpected behavior. If the box is not checked, then the headings go from <h1> to <h3>, which is a problem for screen reader users.

Details

Background issues:

Here is a screenshot of part of the content editor experience:

image

The "component" will only be rendered if data in the content model says to render it.

Based on the documentation for the "On this page" component, it is being used incorrectly on this specific page, and likely others. However, the improper use is due to there being no other <h2> elements on the page, which is because of bad content coming from the CMS.

The content on the page should have a minimum of two H2 section titles to use the On this page jump link.

Acceptance Criteria

Environment

Steps to Recreate

  1. Enter https://www.va.gov/pittsburgh-health-care/health-services/surgery-service/ in browser
  2. Notice that there are no other headings under "On this page"
  3. Inspect the page and notice that "Surgery Service" is an <h1>, "On this page" is an <h2>, and "Contact info" is an <h3>
  4. None of the <h3> elements are children of the <h2>.

Proposed Solution (if known)

Modify the axeCheck Cypress command and/or the 16 sitemap tests where axeCheck is being called to:

  1. Throw errors on the heading-order rule in the best-practice tag
  2. (optional) exclude the "On this page" component from the checks

If excluding the component and its <h2>On this page</h2> isn't possible, then the design system team will be able to change the component to not render the <h2> if there are no others on the page, leading to an appropriate failure for the a11y tests.

Screenshots or Trace Logs

With the best-practice tag enabled the tests are saying that the page is missing an <h1>, but aren't picking up on the heading-order issue:

https://github.com/department-of-veterans-affairs/content-build/runs/3429054614?check_suite_focus=true#step:9:3990

This may be related to the page being inside of an <iframe> in Cypress.

heading-order was getting triggered on other pages though: https://github.com/department-of-veterans-affairs/content-build/runs/3429054717?check_suite_focus=true#step:9:2506

noahgelman commented 2 years ago

@bkjohnson If there is a heading issue, you can pass a different heading, like an <h2> instead of an <h3> and use a CSS class that makes it look like an a header with the <h3> design if that's what you want. We have those classes for this reason. It happens often

bkjohnson commented 2 years ago

I'm aware of the CSS classes for styling headings as other levels. The issue here is content is being delivered from the CMS that already has this violation. At that point the content build could try to recognize this and replace <h3>s with <h2>s where appropriate, but the hope is for the CMS to deliver correct content to begin with.

bkjohnson commented 2 years ago

Also, several months ago I wrote a script to create a list of files where this violation occurs. I've run it sporadically, with the most recent being today. Here are the results:

This is all content that is on va.gov. For example, https://www.va.gov/western-colorado-health-care/work-with-us/internships-and-fellowships/psychiatric-mental-health-nurse-practitioner-residency

Missing h2 between h1 and h3

Without anything in place to prevent this the number of files with improper content will continue to grow.

noahgelman commented 2 years ago

@timwright12 Do you have an opinion on this? You've worked with axe rules recently

timwright12 commented 2 years ago

@noahgelman @bkjohnson I would like to see us start to take some steps to identify and remediate this issue.

Heading order relates to:

If there's even a gray area here related to compliance, we should take steps to try and fix it. This seems like a pretty widespread issue within the site content; if we can work with @cmaeng and the CMS team on a remediation path I think that would be best.

@cmaeng do you think we can all chat about this one? The issue seems to be getting worse with time. cc @timcosgrove

Some more information about heading order: https://www.w3.org/WAI/WCAG21/Techniques/general/G141.html

To facilitate navigation and understanding of overall document structure, authors should use headings that are properly nested (e.g., h1 followed by h2, h2 followed by h2 or h3, h3 followed by h3 or h4, etc.).

cc @mchelen

cmaeng commented 2 years ago

@timwright12 yup, let's chat. i'll reach out in slack to coordinate. will want to include @timcosgrove @kevwalsh @swirtSJW

kevwalsh commented 2 years ago

@bkjohnson This is great, thanks so much for this data.

Do you mind

  1. running it again and getting the latest data?
  2. providing the full output from this script, so that we can analyze it for patterns and opportunities.

We have a sense about where these problems are coming from (My hunch is mostly pages built with the "VAMC detail page" content type, which is used extensively by VAMC editors for content that doesn't have a defined content model, and editors have ability to choose headings in a rich text editor).

We'll need a "how might we" with some hypotheses about what will most quickly move the needle on these, and i'd like to start tracking metrics to see what's working. Here's a POC of what the metrics might be.

Heading_errors_data_-_Google_Sheets

In the future, we might want to create charts like this specific to each vector, like per product, per content type, or even per user, if we find that it's a few users who are creating a disproportionate number of these.

FWIW, one hypothesis is that editors think h2 is too big and so they choose h3 for purely aesthetic reasons, without understanding the ramifications.

timwright12 commented 2 years ago

Release tools action item ticket: https://github.com/department-of-veterans-affairs/va.gov-team/issues/37996

bkjohnson commented 2 years ago

@kevwalsh here's the latest results from the script:

And here's the full output:

heading_order_violations_2022-04-20.txt

I'm not the only one that can run this - yarn list-heading-order-violations on the find-heading-order-violation branch will create the list of files.

davidconlon commented 2 years ago

@bkjohnson - might need a little help understanding two of the entries and where to route them:

FYSA - I've routed these items to the content team for manual remediation:

The others are part of the VAMC product that we will be discussing shortly of a path forward for both educations and (hopeful) some sort of automated remediation/prevention.

bkjohnson commented 2 years ago

I'm also not sure who owns the "session-expired" page, but I would guess the auth team since they redirect to it.

https://staging.va.gov/dst shows the "Veterans Community Care Program Eligibility Tool":

DST page

I don't really know anything about this or why "dst" is used, but it wasn't obvious to me why this was in the list. I looked at the markup and saw why the script was flagging it:

image

davidconlon commented 2 years ago

Do we know which team owns that codebase for DST? Looking at the content I'm wondering if this is old and crufty, never launched, and needs to be removed or if this is something new. I tried the form and it does nothing.

bkjohnson commented 2 years ago

I don't know who owns that page or if it's old or new.

davidconlon commented 2 years ago

@bkjohnson @mchelen Update: We're working through a plan for the content that is in the CMS, but the DST page needs to be routed/remediated by another team as it is not in the CMS.

davidconlon commented 2 years ago

Heading-levels-sliced-and-diced.xlsx

Attaching my slice and dice for different ways to solve this problem.

bkjohnson commented 2 years ago

The DST page is coming from the vagov-content repo - so it looks like something that's old and can be removed.

cmaeng commented 2 years ago

transferring this issue over to the va.gov-cms repo for our new Accessibility Lead, @laflannery , to take a look at.