Accessibility: How to dismiss occurrences of accessibility issues

Modified on: Thu, 30 Nov, 2023 at 6:29 PM

How can I dismiss occurrences of accessibility issues?
Getting a CSS selector from browser DevTools (Advanced)
How do I keep track of the dismissed occurrences?
Does the Accessibility score improve if I dismiss occurrences?
Can I dismiss an entire check?

You may want to hide occurrences of issues that you cannot work on to give a focused view of priorities, manage your workload or report on progress.

This may include dismissing occurrences where third-party code is causing specific accessibility issues that you are not able to fix. It may also include instances where you believe there is a false positive result.

If this happens you can report it to us, and we will remove it from your list while we investigate it.

Note: False positives are reviewed manually, which can take several days or weeks. You can check the status of false positives reported at Accessibility > Activity. Feel free to contact customer support if you have questions about the review status.

You can find the dismiss options under a cogwheel in the page report.

dismiss option under a cogwheel in page report

How can I dismiss occurrences of accessibility issues?

1. Dismiss an occurrence as can’t fix.

Note that the decision is applied only to the exact matches of the occurrence. In practice, the underlying code needs to be 100% same, for us to apply the decision to occurrences across other pages as well.

If you dismiss an occurrence, you have decided to hide all the precise matches of a specific occurrence from the platform. When you have dismissed an occurrence, you will see a note about the dismissed occurrence on the Activity page, Accessibility > Activity.

option to dismiss an occurrence as can’t fix.

2. Dismiss an occurrence as a false positive.

In the rare case you encounter a false-positive report, we would love to hear about it, so that we can provide you with the most accurate assessment of issues. That is why, besides the possibility of dismissing as "can’t fix", you can also dismiss as a "false positive". When you "dismiss as a false positive", all the exact matches of the specific occurrence will be hidden from the platform, and we will be notified to investigate the potential bug further. You will be able to see on the Activity page if the bug is confirmed by Siteimprove. In cases where an occurrence is confirmed manually as false positive by Siteimprove, you will be rewarded the missing accessibility points. Reporting a false positive to us will result in improved checks, not only for the rest of your website(s) but for everyone.

Option to dismiss an occurrence as a false positive

3. Dismiss in bulk using a CSS selector (Advanced).

So far this article has discussed dismissing one occurrence at a time. Whether you are dismissing as “can’t fix” or as “false positive,” you can do this in bulk by using a CSS (Cascading Style Sheets) selector.

Applying a CSS selector will dismiss:

All matching occurrences on the current page
All pages on your site
All current and future occurrences

This is especially useful when your site has dynamic content. If you were to dismiss one occurrence at a time, this could take a lot of repetitive clicking – not only in the moment, but also whenever new content appears on your site.

Another use case for CSS selectors is selecting third-party components or parts of your website that are out of scope – for example, a chat widget or social media wall. Decision for this occurrence screenshot with code in the Advanced Options.

CSS Selector Examples

Example 1: Matching by CSS class

If your HTML looks like this...

...then the CSS selector .class1 will match "div #1" (it will not match any other elements).

Example 2: Matching by multiple CSS classes

The CSS selector .class3 will match "div #1" and "div #2".

The CSS selector .class1.class3 will match "div #1".

Note: There is no space character between ".class1" and ".class3".

Example 3: Matching by HTML element name and CSS class

.class1 will match "the div" and "the h2".

div.class1 will match "the div".

h2.class1 will match "the h2".

Example 4: Matching descendant elements

div a.class1 will match "link #1".

div.a will match "link #1" and "link #2" (But we discourage this, because it is an "overly broad" CSS selector in that it uses only HTML element names, not CSS classes. See the “commentary” section below.)

p a.class1 will match "link #3".

.class2 will match "link #2" and "link #4".

.class3 .class2 will match "link #4"

Note: There is a space between ".class3" and ".class2". This space makes it match descendants rather than multiple classes. Multiple classes are covered in example 2.

Example 5: Matching immediate child elements with ">"

div a.class1 will match "link #1" and "link #2".

div > a.class1 will match "link #2".

div > span > a.class1 will match "link #1".

Example 6: HTML element wildcard "*"

div.class1 * will match "text 1", "text 2", "text 3", "text 4", and "text 5".

div.class1 span * will match "text 2".

div.class1 > * > i will match "text 2" and "text 4".

Example 7: Multiple CSS selectors separated by comma

div.class1 span will match "text 1".

div.class1 span * will match "text 2".

div.class1 span,div.class1 span * will match "text 1" and "text 2".

Example 8: Match by ID with "#"

<div id="id1">text 1</div>
<div id="id2">
text 2

#id1 will match "text 1"

#id2 will match "text 2".

#id2 p will match "text 3".

#id3 will also match "text 3".

CSS Selectors – Additional Commentary

It's important that your CSS selector matches the correct elements. It needs to match the exact HTML element that Siteimprove is flagging (not the parent element of it or a child element of it). In technical terms, CSS selectors don’t act recursively. As you type in your CSS selector, Siteimprove tells you how many occurrences it matches on the current page (as shown by "Matches 1 element" in the screenshot above). This number of matches refers to the current page only. There is currently no way to see how many elements your CSS selector matches throughout the site.

It's also important that your CSS selector doesn't match more elements than it needs to. If you are dismissing as “can’t fix,” then a CSS selector that is too broad will remove more occurrences from your issue list than you wished to. If you are dismissing as “false positive,” then a CSS selector that is too broad is more likely to match "true positives" in addition to false positives, so the human at Siteimprove that reviews your false positive report might reject it. The best CSS selectors narrow down the elements that they match by using one or more CSS classes in combination with HTML element names – the more specific the better.

There are more advanced CSS selector techniques than what is discussed in this article. Learn more at the Mozilla Developer Network and in the W3 schools.

Getting a CSS selector from browser DevTools (Advanced)

So far this article has discussed how to write your own CSS selector from scratch. Now we'll discuss an alternative: getting a CSS selector from browser DevTools.

If you're unfamiliar with DevTools, we recommend that you first read our introduction to DevTools then read the documentation for DevTools specific to your browser.

This article will focus on the Chrome browser, but the same techniques apply to all major browsers.

In DevTools you can get a CSS selector for any element. In Chrome, at the time of writing, the process is: right-click on the page > Inspect, then in DevTools under the "Elements" tab, right-click on the element, then choose Copy > Copy selector. ("Copy selector" here means "Copy CSS selector".) In other browsers, the process is similar. Firefox gives you two options here:"Copy > CSS Selector" and "Copy > CSS Path." Both are worth trying. Once you do that, there will be a CSS selector in your clipboard.

For example, if we go to the siteimprove.com home page in Chrome, then get a CSS selector for the main heading ("Capture attention..."), this is the CSS selector that we will get:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

Siteimprove website with the header highlighted, the right click selected and Copy > Copy selector highlighted from the pop out menu

At this point, different browsers will give you different CSS selectors - sometimes very different. This is to be expected, because there is no single correct answer to the question "what is the CSS selector for this element?" In truth, the browser is answering a different question: "what is a CSS selector for this element?" There are many correct answers to that question, and different browsers will give you different correct answers.

For example, in Firefox, for the same element on the siteimprove.com home page, the result of the "Copy > CSS Selector" function is this:

.hero__content > h1:nth-child(1)

The result of Firefox's "Copy > CSS Path" function is this:

html.no-js.js-focus-visible body.GTM--initialized div.page-wrapper main#main.content-main div div div div.hero.theme-white-text-dark-gray-background div.grid.pb0 div.col.col-6.col-md-12.col-y-center div.hero__content.clear h1

Both of those CSS selectors that Firefox gave us are so different from the CSS selector that Chrome gave us, they're unrecognizable. But all three CSS selectors are correct, and we can work with any one of them for our goal of dismissing occurrences in the Siteimprove platform.

Whatever the CSS selector is that the browser gave you, it will match the element that you clicked on. But that might be the only element that it matches. When you're doing a "dismiss" with a CSS selector, you will generally want to match several elements rather than just one. So you need to modify the CSS selector to make it match more elements.

In DevTools you can modify the CSS selector and see how many elements on the page that it matches. You can do this in your browser DevTools "Elements" tab or its equivalent, where there is generally a "Find" function (often accessed with "Ctrl+F") which lets you enter a CSS selector and see how many elements on the page that it matches.

Here are some examples of experimental modifications worth trying. Each is a modification of the CSS selector from our example above, which was:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

Remove the "#" ID step:

Before:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

After:

div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

Replace the ID with an element type "main":

Before:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

After:

main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

Remove "nth-child" step:

Before:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

After:

#main > div > div⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀> div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

Remove the match for the CSS class "col-md-12":

Before:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

After:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-y-center > div > h1

Remove the matches for all CSS classes, to match on element names only:

Before:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

After:

#main > div > div:nth-child(1) > div > div > div > div > div > h1

Remove the matches for element names, to match on CSS classes only:

Before:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

After:

#main > div > div:nth-child(1) > div > div > *.grid.pb0 > *.col.col-6.col-md-12.col-y-center > div > h1

Remove one ">":

Before:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

After:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div ⠀⠀h1

Remove all ">":

Before:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

After:

#main ⠀⠀div ⠀⠀div:nth-child(1) div div div.grid.pb0 div.col.col-6.col-md-12.col-y-center ⠀⠀div ⠀⠀h1

Replace "nth-child" with "nth-of-type":

Before:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

After:

#main > div > div:nth-of-type(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

Replace the last step with a "*":

Before:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

After:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > *

Remove the first few steps:

Before:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

After:

div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

Use in conjunction with ",":

Before:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1

After:

#main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h1, #main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h2, #main > div > div:nth-child(1) > div > div > div.grid.pb0 > div.col.col-6.col-md-12.col-y-center > div > h3

This video shows the process of CSS selector experimentation in Chrome

After you've figured out, in DevTools, the CSS selector that you want to use for your dismissal, then you can paste that CSS selector into the Siteimprove platform. This is explained above in the "How can I dismiss occurrences of accessibility issues?" > "Dismiss in bulk using a CSS selector (Advanced)" subsection of this article.

How do I keep track of the dismissed occurrences?

You can access all the decisions that you have made on the Activity overview page at Accessibility > Activity.
Here you can see the full list of decisions taken as well as:

Who took them
When they were actioned
Why the occurrence was dismissed
Which pages are affected by it

You may also undo your decisions on the activity page.

Activity overview page at Accessibility > Activity

You are also able to filter the issues lists by dismissed occurrences, should you wish to gain an overview of the dismissed occurrences by issue.

Does the Accessibility score improve if I dismiss occurrences?

Dismissing occurrences as can’t fix will not impact your accessibility score. The accessibility score is used as an industry benchmark that is aimed at providing an accurate description of the level of accessibility across industries. Hiding valid issues does not mean that the accessibility of your site has improved. It just means that certain issues are not in your focus, for valid reasons.

Instead, if you have set up a Site Target, representing your organizational accessibility goal, this will get lower to reflect the dismissed issues.
Of course, if you have found a real false positive, that Siteimprove has validated, you will be rewarded with the accessibility points immediately. We appreciate the help you provide to us when you report a false positive, since the score calculation will become more accurate for everyone in the process.

Can I dismiss an entire check?

It is not possible to exclude an entire issue check from the platform using the dismiss feature. Ignoring an issue entirely might lead to dismissing a number of valid occurrences that impact the accessibility of your site. New occurrences of that issue emerging after this point would also be missed from your list. We recommend always reviewing individual occurrences carefully before making the dismiss decision.

Instead of dismissing valid issues, Account Owners can create focus by filtering out groups of issues, like AAA or best practice checks, using the Site Target feature. You can read more about setting a Site Target here.

Did you find it helpful? Yes No