October 2024

November 2024

Tysvær

Screen reader users will see links on a page listed without context, 
so you should ensure the same link text is not used to point to different web
addresses.

For example:

```html
<p>
    Learn the latest about our products: 
    <a href="/products/news">News</a>
</p>

<p>
    Learn the latest about our services: 
    <a href="/company/news">News</a>
</p>
``` 

To a screen reader who is listing links, they will only hear:

* News
* News

These links appear to be the same, but they both behave differently. 
One solution, which doesn't require the page design to change, is to add an 
`aria-label` for each link:

```html
<p>
    Learn the latest about our products: 
    <a href="/products/news" aria-label="Product news">News</a>
</p>

<p>
    Learn the latest about our services: 
    <a href="/company/news" aria-label="Company news">News</a>
</p>
``` 

Which will be heard as:

* Product news
* Company news

To pass this checkpoint, make sure that links which point to different pages 
have distinct text inside them, or that they specify ARIA labels (`aria-labelledby` or
`aria-label`), or they use hidden text only visible to screen readers
(e.g. `<span class="sr-only">...</span>`) to distinguish them from each 
other.

If links point to the same page (e.g., they redirect or use tracking
parameters, but are functionally equivalent to the user) you can ignore
this issue.

a-duplicate-link-text-for-different-destinations

To comply with the strictest accessibility standard (WCAG AAA), the colour of text must 
strongly contrast with its background color, so that people with significant visual impairments 
can read it.

The [contrast ratio](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html#contrast-ratiodef)
must be at least 7:1 for body text, and 4.5:1 for large text.

A far less demanding version of this check (1.4.3) exists for WCAG AA. All websites should aim to 
meet the easier AA standard at a minimum. The AAA standard is desirable but far more challenging,
and may not be practical for your website.

aaa-text-contrast

All interactive components on a page, such as buttons or fields, should ideally be large enough 
to be easily used by people with motor impairments. 

This ensures people with motor impairments can easily click or tap on the element.

The recommended size is 44 x 44 CSS pixels, with some exceptions:

* **Equivalent available** - the functionality provided by
  the control is available elsewhere, and large enough, on the same page.
* **Inline text** - the control appears inside a sentence or block of text. 
* **User Agent control** - the size of the target is determined by the user agent 
  and is not modified by the author. Generally this is not the case for web content.
* **Essential** - the size of the target is essential to the information being conveyed,
  e.g. a tutorial demonstrating what a small button looks like. This exception is rare.

## Applying this check

Nearly all websites will fail this check by default. The minimum size requirement
is larger than most links and controls on most websites.

This is the much stricter version of the WCAG 2.2 AA check for target size. Most websites
should focus on the AA check before considering this AAA check:

* [Target Size (Minimum)](https://w3c.github.io/wcag/understanding/target-size-minimum.html)

## Methodology

This check is run on both the mobile and desktop versions of every page. Results
for each may differ.

1. All interactive elements are identified, including buttons, links, and form controls. 
2. If an element is preceded or followed directly by a non-empty text node, the control
   is ignored.
3. If an element is not normally visible, it is ignored. This includes elements which 
   are positioned offscreen or cropped (e.g. for 'screen-reader only' text).
4. If an element is a link, and another visible link on the page points to the same URL, with 
   that other link meeting the size requirements, the element is ignored.
5. Otherwise, the element must have a minimum size of 44 x 44 CSS pixels.

## Troubleshooting

Silktide only records the first 100 instances of a failure on a page. Because failures
of this check are common, it is possible that your page has more than 100 failures, but
only the first 100 will be shown.

## Further reading

* [Target Size (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced)

ensure-reasonable-target-size

Forms should always contain a submit button, otherwise some people using
accessible technologies may not be able to submit the form.

Submit buttons are `<input>` elements with a type attribute of `submit` or
`image`, or `<button>` elements with type `submit`. 

## Rationale 

Many users expect to be able to press enter in a form to submit it. However,
this is not always possible.

Users of some assistive technologies may (depending on the technology) only
be able to press a button to submit the form. In the absence of a submit
button, the user may not be able to submit the form.

In addition, the absence of a submit button suggests that the form may 
provide an automatic 'change of context', i.e. major change to the user 
interface without the user choosing to do so. This can be highly disorientating
to some users.

## Further reading

See [Technique H32](https://www.w3.org/TR/WCAG20-TECHS/H32.html).

form-submit-required

Avoid opening links in a new tab or window. Where you must do this, include an explanation
in the text of the link.

## Why this matters

Opening links in a new tab or window breaks the back button and can be disorientating for 
novice web users, and the visually impaired. Generally you should avoid opening links in a
new tab or window, but if you have to, you should include text explaining that this will happen.

## How to fix

An explanation must be clear in the accessible text for the link. For example:

```html
<a href="products.html" target="_blank">
    Products (opens in new window)
</a>
```

Or, for an image inside a link:

```html
<a href="products.html" target="_blank">
    <img src="products.jpg" alt="Products (opens in new window)">
</a>
```

Rather than updating all of your links manually to do this, you can add a simple CSS
selector, such as:

```css
a[target="_blank"]:after {
    content: " (opens in new window)";
}
```

Note that doing this with an icon, is not sufficient to pass this check. The text must be
readable by screen readers.

Alternatively you can override the link text for accessible technologies (like screenreaders),
so that the appearance of the link does not change. For example:

```html
<a href="products.html" target="_blank" aria-label="Products (opens in new window)">
    Products
</a>
```

Note that if you do this, the `aria-label` will replace the text content of the link completely,
so it must still make sense in isolation.

## Terminology

Although it is common to say "opens in new window", almost all browsers now use tabs, and
so this terminology is potentially confusing. You may prefer: "opens in new tab".

## Methodology

1. Silktide considers all links on a page with a `target` attribute of `_blank`.
2. For each link, Silktide considers the screen-readable text of the link, which includes:
   * The text content of the link
   * Any `alt` text inside any images inside the link
   * Any `aria-label` or `aria-labelled-by` text
   * The `content` of the pseudo-elements `:before` and `:after`
3. This text is analysed for the presence of common text, including "opens new tab"
    and "opens new window". If the text is not found, the link fails the test.

## Further reading

Generally best practice is to avoid opening links in a new tab or window.  

The W3C provides detailed guidance on 
[when opening a link in a new window may be appropriate](https://www.w3.org/TR/WCAG20-TECHS/G200.html).

link-text-explains-open-in-new-window

Every page should have a clearly defined heading, known as a "H1" (Heading 1).

A `H1` is the main heading of the page. It helps accessibility by allowing uses to
skip to the main content of the page. It helps all users identify what the page is about. 
It helps SEO by giving special emphasis to the topic of the page.

It is not enough to simply include large text. Headings must be coded 
[semantically](https://html.com/semantic-markup/) as `<h1>` tags, like so:

```html
<h1>This is a heading</h1>
```

Note that headings must contain some machine readable text to be considered valid. 
For example, this heading is not valid:

```html
<h1>
    <img src="company-logo.png">
</h1>
``` 

But with the addition of `alt` text, this heading is valid:

```html
<h1>
    <img src="company-logo.png" alt="About Company Inc.">
</h1>
``` 

Generally we recommend you just use plain text for your headings.
See [Technique H42](https://www.w3.org/TR/WCAG20-TECHS/H42) for more details.

missing-h1

Webpages should provide a way to skip to the main content of the page. There are 
several ways to accomplish this.

The most common solution is a "Skip to content" link:

```html
<a href="#main">Skip to main content</a>
...
<div id="main">
<h1>Welcome to this page</h1>
```

This link is usually hidden from users unless selected, so it doesn't need to compromise the look of 
your page.

Alternatively, you can use the `<main>` HTML landmark:

```html
<main>
<h1>Welcome to this page</h1>
``` 

or an ARIA role of `main`:

```html
<div role="main">
<h1>Welcome to this page</h1>
``` 

Generally best practice is to combine these approaches, using `<main>` landmark with a link pointing to it:

```html
<a href="#main">Skip to main content</a>
...
<main id="main">
<h1>Welcome to this page</h1>
```

This approach will be most widely supported by screen readers and understood by the highest number of users.

# Justification

Many users of assistive technology are only able to experience content sequentially - that is, they must
step through each part of the page, one part at a time. Often this is a slow process, potentially 
hampered by a physical impediment.

Most web pages have a header containing branding and navigation on every page. Stepping through 
this repetitive part of the page can be hugely frustrating for users of assistive technology. For example, 
a blind user may have to listen to hundreds of navigation links before they can reach the content on a page.

Adding a means to skip directly to the page content massively enhances the experience for these users.

Skip to content links do not need to be visible to everyone. A common implementation means they are only 
experienced by users via the tab key or other assistive technology 
(see [skipping to navigation links](https://webaim.org/techniques/skipnav/) from WebAIM). 

# Methodology

It is not sufficient to include a "skip to content" link. The link must work, and it must appear early
enough in the page to be useful.

* If the page has less than 500 visible characters, it does not require a "skip to content" link.
* If the page has a main landmark (e.g. `<main>` or `role="main"`) it does not require a "skip to content" link.
* Silktide looks for a link with a fragment (e.g. `#main`) pointing to a lower part of the page. The link 
  must not be adjacent to other text nodes. 
* The fragment must point to an ID that exists, or this check will raise an error.
* The link must appear before 500 visible characters of text in the page, or this check will raise an error.

The text inside the link is not considered, as this test must support a wide range of languages.

# Learn more

More about [skipping to navigation links](https://webaim.org/techniques/skipnav/) from WebAIM and 
see [W3C's recommended technique](https://www.w3.org/TR/2016/NOTE-WCAG20-TECHS-20161007/G1).

skip-to-content

wcag-22.score

wcag-22-a.score

wcag-22-aa.score

wcag-22-aaa.score

website.pages

website.documents

All interactive components on a page, such as buttons or menus, should be far enough apart 
from other interactive areas, to avoid them being used by mistake. 

This ensures people with motor impairments can easily click or tap on the right element.

## Methodology

This check is run on both the mobile and desktop versions of every page. Results
for each may differ.

1. All interactive elements are identified, including buttons, links, and form controls.
2. If an element is not normally visible, it is ignored. This includes elements which
   are positioned offscreen or cropped (e.g. for 'screen-reader only' text).
3. If an element is larger than 24 CSS pixels in both dimensions, it passes.
4. Otherwise, the element is compared to all other elements on the page.
5. The minimum horizontal gap between the element is calculated as 24 CSS pixels,  
   minus the width of the element.
6. The minimum vertical gap between the element is calculated as 24 CSS pixels,  
   minus the height of the element.
7. If another element falls within the minimum horizontal or vertical gap, the 
   element fails, unless both are links that point to the same place.

## Further reading

This is part of the draft WCAG 2.2 specification and is subject to change.

* [Target Size (Minimum)](https://w3c.github.io/wcag/understanding/target-size-minimum.html)

ensure-minimum-target-size

The first heading in a PDF document should be a Heading 1. 

Failure to meet this indicates that either:

1. Headings are incorrectly structured (e.g. H2 before H1)
2. Or, the order of elements in the PDF is incorrect

## More information

See [PDF9: Providing headings by marking content with heading tags in PDF documents](https://www.w3.org/TR/WCAG20-TECHS/pdf.html#PDF9)
from the WCAG specification.

pdf-headings-h1-first

Headings in a PDF should follow the sequence Heading 1 > Heading 2 > Heading 3 without skipping intermediate headings.

It is acceptable to 'go back' to previous styles/headings but the sequence should then continue without missing headings.

See [WCAG](https://www.w3.org/TR/WCAG20-TECHS/pdf.html#PDF9)

pdf-headings-order

PDF files should have headings.
 See [WCAG](https://www.w3.org/TR/WCAG20-TECHS/pdf.html#PDF9)

Priority	Recommendation	Progress
	Allow users to quickly skip to content WCAG 2.0 A 2.4.1	52%
	Ensure every page contains a top-level heading WCAG 2.0 A 1.3.1	54.1%
	Ensure interactive components are far enough apart WCAG 2.2 AA 2.5.8	97.8%
	Ensure links explain they open in a new tab WCAG 2.0 AAA 3.2.5	32%
	Add a submit button to all forms WCAG 2.0 A 3.2.2	46%

Tysvær

Accessibility

WCAG Levels

Recommendations

The best free accessibility checker