Accessibility Guides for WCAG 2.1 (AA)

Why This Matters

The autocomplete attribute does more than enable browser autofill — it programmatically communicates the purpose of a form field to assistive technologies. This information is critical for several groups of users:

• Screen reader users rely on the announced field purpose to understand what information is being requested. Without a valid autocomplete value, the screen reader may not convey this context clearly.
• Users with cognitive disabilities benefit from browsers and assistive tools that can auto-populate fields or display familiar icons based on the field’s purpose, reducing the mental effort required to complete forms.
• Users with mobility impairments benefit from autofill functionality that minimizes the amount of manual input required.
• Users with low vision may use personalized stylesheets or browser extensions that adapt the presentation of form fields based on their declared purpose (e.g., showing a phone icon next to a telephone field).

This rule maps to WCAG 2.1 Success Criterion 1.3.5: Identify Input Purpose (Level AA), which requires that the purpose of input fields collecting user information can be programmatically determined. The autocomplete attribute is the standard mechanism for satisfying this requirement in HTML.

How the Rule Works

The axe rule autocomplete-valid checks that:

1. The autocomplete attribute value is a valid token (or combination of tokens) as defined in the HTML specification for autofill.
2. The value is appropriate for the type of form control it is applied to (e.g., email is used on an email-type input, not on a checkbox).
3. The tokens are correctly ordered when multiple tokens are used (e.g., a section name followed by a hint token followed by the field name).

The rule flags fields where the autocomplete value is misspelled, uses a non-existent token, or is applied in an invalid way.

How to Fix It

1. Identify all form fields that collect personal user information (name, email, address, phone number, etc.).
2. Check if the data type matches one of the 53 input purposes defined in WCAG 2.1 Section 7.
3. Add the correct autocomplete value to each matching field. Make sure:
   • The value is spelled correctly.
   • It is appropriate for the input type.
   • If using multiple tokens, they follow the correct order: optional section name (section-*), optional shipping or billing, optional home, work, mobile, fax, or pager, and then the autofill field name.
4. Set autocomplete="off" only when you have a legitimate reason to disable autofill — and note that this does not exempt you from the rule if the field still collects identifiable user data.

Common autocomplete Values

Here are some of the most frequently used values:

Examples

Incorrect: Missing or Invalid autocomplete Values

<!-- Missing autocomplete attribute entirely -->

<label for="name">Full Name</label>
<input type="text" id="name" name="name">

<!-- Misspelled autocomplete value -->

<label for="email">Email</label>
<input type="email" id="email" name="email" autocomplete="emal">

<!-- Invalid autocomplete value -->

<label for="phone">Phone</label>
<input type="tel" id="phone" name="phone" autocomplete="phone-number">

In the examples above, the first field has no autocomplete attribute, the second has a typo (emal instead of email), and the third uses a non-standard value (phone-number instead of tel).

Correct: Valid autocomplete Values

<label for="name">Full Name</label>
<input type="text" id="name" name="name" autocomplete="name">

<label for="email">Email</label>
<input type="email" id="email" name="email" autocomplete="email">

<label for="phone">Phone</label>
<input type="tel" id="phone" name="phone" autocomplete="tel">

Correct: Using Multiple Tokens

When a form has separate shipping and billing sections, you can use additional tokens to distinguish them:

<fieldset>
  <legend>Shipping Address</legend>
  <label for="ship-street">Street Address</label>
  <input type="text" id="ship-street" name="ship-street"
    autocomplete="shipping street-address">

  <label for="ship-zip">Postal Code</label>
  <input type="text" id="ship-zip" name="ship-zip"
    autocomplete="shipping postal-code">
</fieldset>

<fieldset>
  <legend>Billing Address</legend>
  <label for="bill-street">Street Address</label>
  <input type="text" id="bill-street" name="bill-street"
    autocomplete="billing street-address">

  <label for="bill-zip">Postal Code</label>
  <input type="text" id="bill-zip" name="bill-zip"
    autocomplete="billing postal-code">
</fieldset>

Correct: Named Sections with section-*

You can use custom section names to group related fields when the same type of data appears multiple times:

<label for="home-tel">Home Phone</label>
<input type="tel" id="home-tel" name="home-tel"
  autocomplete="section-home tel">

<label for="work-tel">Work Phone</label>
<input type="tel" id="work-tel" name="work-tel"
  autocomplete="section-work tel">

By using valid, correctly applied autocomplete values, you ensure that assistive technologies can communicate the purpose of each field to users, browsers can offer reliable autofill, and your forms meet the requirements of WCAG 2.1 Success Criterion 1.3.5.

Some users need to adjust text spacing to make content readable. People with low vision may increase letter or word spacing to reduce visual crowding. People with cognitive disabilities, dyslexia, or attention deficit disorders often struggle to track lines of text that are tightly spaced — increasing line-height, letter-spacing, or word-spacing can make reading significantly easier.

When text-spacing properties are set inline with !important, they gain the highest specificity in the CSS cascade. This means user stylesheets, browser extensions, and assistive technology tools cannot override those values. The text becomes locked into a fixed spacing that may be difficult or impossible for some users to read.

This rule relates to WCAG 2.1 Success Criterion 1.4.12: Text Spacing (Level AA), which requires that no loss of content or functionality occurs when users adjust:

• Line height to at least 1.5 times the font size
• Spacing following paragraphs to at least 2 times the font size
• Letter spacing to at least 0.12 times the font size
• Word spacing to at least 0.16 times the font size

If inline !important declarations prevent these adjustments, the content fails this criterion.

How to Fix It

The fix is straightforward: do not use !important on inline style attributes for line-height, letter-spacing, or word-spacing. You have a few options:

1. Remove !important from the inline style declaration. Without !important, users can override the value with a custom stylesheet.
2. Move styles to an external or embedded stylesheet. This is generally the best approach because it separates content from presentation and gives users more control through the cascade.
3. If !important is truly necessary, apply it in a stylesheet rather than inline. Inline !important styles are virtually impossible for users to override, while stylesheet-level !important can still be overridden by user !important rules.

Note that other inline style properties like font-size are not flagged by this rule — only the three text-spacing properties (line-height, letter-spacing, word-spacing) are checked.

Examples

Incorrect: Inline styles with !important

These examples fail because !important on inline text-spacing properties prevents user overrides.

<!-- line-height with !important — cannot be overridden -->

<p style="line-height: 1.5 !important;">
  This text is locked to a specific line height.
</p>

<!-- letter-spacing with !important — cannot be overridden -->

<p style="letter-spacing: 2px !important;">
  This text has fixed letter spacing.
</p>

<!-- word-spacing with !important — cannot be overridden -->

<p style="word-spacing: 4px !important;">
  This text has fixed word spacing.
</p>

<!-- Mixed: word-spacing is fine, but letter-spacing has !important -->

<p style="word-spacing: 4px; letter-spacing: 2px !important; line-height: 1.8;">
  Even one !important on a spacing property causes a failure.
</p>

Correct: Inline styles without !important

These examples pass because users can override the inline values with a custom stylesheet.

<!-- line-height without !important — overridable -->

<p style="line-height: 1.5;">
  Users can adjust this line height with a custom stylesheet.
</p>

<!-- letter-spacing without !important — overridable -->

<p style="letter-spacing: 2px;">
  Users can adjust this letter spacing.
</p>

<!-- word-spacing without !important — overridable -->

<p style="word-spacing: 4px;">
  Users can adjust this word spacing.
</p>

<!-- Multiple spacing properties, all without !important -->

<p style="word-spacing: 4px; letter-spacing: 2px; line-height: 1.8;">
  All three spacing properties can be overridden by the user.
</p>

<!-- font-size with !important is fine — not a text-spacing property -->

<p style="font-size: 200%;">
  This does not trigger the rule.
</p>

Best practice: Use an external stylesheet instead

<!-- HTML -->

<p class="readable-text">
  Styles are defined in the stylesheet, giving users full control.
</p>

/* CSS */
.readable-text {
  line-height: 1.8;
  letter-spacing: 0.05em;
  word-spacing: 0.1em;
}

By keeping text-spacing styles in a stylesheet, you make it easy for users to apply their own overrides while maintaining your default design.

Color contrast is one of the most common accessibility barriers on the web. When text doesn’t stand out enough from its background, it becomes difficult or impossible to read for many users. People with low vision experience reduced contrast sensitivity, meaning everything appears roughly the same brightness, making it hard to distinguish outlines, edges, and details. Approximately 1 in 12 people cannot see the full spectrum of colors — about 8% of men and 0.4% of women in the United States have some form of color vision deficiency. Nearly three times as many people have low vision compared to total blindness. Without sufficient contrast, these users simply cannot read your content.

This rule maps to WCAG 2.1 Success Criterion 1.4.3: Contrast (Minimum), which is a Level AA requirement. It is also referenced in WCAG 2.0, WCAG 2.2, the Trusted Tester methodology, EN 301 549, and RGAA. The user impact is considered serious because insufficient contrast directly prevents users from perceiving text content.

How Contrast Ratios Work

Contrast ratio is calculated by comparing the relative luminance of two colors on a scale from 1:1 (no contrast, e.g., white on white) to 21:1 (maximum contrast, black on white). WCAG defines two thresholds:

• Normal text (below 18pt or below 14pt bold): minimum 4.5:1 contrast ratio
• Large text (at least 18pt / 24px, or at least 14pt bold / 19px): minimum 3:1 contrast ratio

“Large text” is defined this way because larger characters have wider strokes that are easier to read at lower contrast levels.

What This Rule Checks

The color-contrast rule in axe-core examines each text element on the page and compares the computed foreground text color against the computed background color. It accounts for background color transparency and opacity. Elements that are found to have a 1:1 contrast ratio are flagged as “incomplete” and require manual review.

This rule does not flag:

• Text elements with a background-image (these require manual testing)
• Text that is visually hidden by other overlapping elements
• Images of text
• Text inside disabled controls (including child elements of disabled buttons)

Some foreground scenarios are harder for automated tools to evaluate, including CSS gradients, pseudo-element backgrounds, backgrounds created with CSS borders, and elements repositioned off-screen with CSS.

How to Fix It

1. Identify the failing elements by running axe. Each violation will report the current contrast ratio and the colors involved.
2. Adjust the foreground color, background color, or both until the required ratio is met (4.5:1 for normal text, 3:1 for large text).
3. Use a contrast checker tool like the axe DevTools browser extension, the WebAIM Contrast Checker, or the built-in color contrast analyzer in browser developer tools to test color combinations before deploying.
4. Test with real content — sometimes dynamic content or themed components produce contrast issues that static checks miss.

Examples

Insufficient contrast (fails)

This light gray text on a white background has a contrast ratio of approximately 2.6:1, which fails the 4.5:1 requirement.

<p style="color: #aaaaaa; background-color: #ffffff;">
  This text is hard to read.
</p>

Sufficient contrast (passes)

Darkening the text color to #595959 against a white background achieves a contrast ratio of approximately 7:1, meeting the requirement.

<p style="color: #595959; background-color: #ffffff;">
  This text is easy to read.
</p>

Large text with lower contrast requirement (passes)

Large text (18pt or larger) only needs a 3:1 contrast ratio. This example uses #767676 on white, which has a ratio of approximately 4.5:1 — well above the 3:1 threshold for large text.

<h1 style="font-size: 24pt; color: #767676; background-color: #ffffff;">
  Large heading text
</h1>

Semi-transparent background (fails)

Transparency can reduce effective contrast. Here, the semi-transparent white background doesn’t provide enough contrast depending on what’s behind it.

<div style="background-color: #cccccc;">
  <p style="color: #777777; background-color: rgba(255, 255, 255, 0.3);">
    Text with a semi-transparent background.
  </p>
</div>

Semi-transparent background fixed (passes)

Increasing the background opacity or adjusting colors restores sufficient contrast.

<div style="background-color: #cccccc;">
  <p style="color: #333333; background-color: rgba(255, 255, 255, 0.85);">
    Text with a more opaque background.
  </p>
</div>

Using CSS classes (passes)

In practice, you’ll likely use CSS classes rather than inline styles. Ensure your design system tokens and theme colors meet contrast requirements.

<style>
  .card {
    background-color: #1a1a2e;
  }
  .card-text {
    color: #e0e0e0;
  }
</style>

<div class="card">
  <p class="card-text">
    Light text on a dark background with good contrast.
  </p>
</div>

The <meta name="viewport"> element controls how a page is displayed on mobile devices, including its dimensions and scale. Two parameters within its content attribute can restrict zooming:

• user-scalable="no" — Completely disables pinch-to-zoom and other user-initiated scaling on the page.
• maximum-scale set below 2 — Caps how far a user can zoom in, preventing them from reaching the 200% zoom level required by WCAG.

Both of these restrictions create serious barriers for people with low vision. Many users depend on zooming to enlarge text and interface elements to a readable size. When zooming is disabled or limited, these users may be unable to use the page at all. Screen magnification tools and native browser zoom are fundamental assistive strategies, and restricting them undermines the accessibility of the entire page.

This rule relates to WCAG 2.0/2.1/2.2 Success Criterion 1.4.4: Resize Text (Level AA), which requires that text can be resized up to 200% without loss of content or functionality. By blocking zoom below that threshold, you fail this criterion. This success criterion exists because the ability to enlarge content is one of the most basic and widely used accessibility features across all platforms.

How to Fix

1. Remove user-scalable="no" from the content attribute of your <meta name="viewport"> element. If present, either delete it or set it to user-scalable="yes".
2. Remove or increase maximum-scale. If you use maximum-scale, set it to at least 2 (which allows 200% zoom). Better yet, remove it entirely to allow unrestricted zooming.
3. Test on mobile devices after making changes. Verify that pinch-to-zoom works and that content remains usable when zoomed to 200%.

Examples

Incorrect: Zooming is completely disabled

<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">

The user-scalable=no parameter prevents users from zooming in at all.

Incorrect: Maximum scale is too restrictive

<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1.5">

Setting maximum-scale to 1.5 limits zoom to 150%, which is below the required 200% threshold.

Correct: Zooming is fully allowed

<meta name="viewport" content="width=device-width, initial-scale=1">

By omitting both user-scalable and maximum-scale, the browser’s default zoom behavior is preserved and users can zoom freely.

Correct: Explicitly allowing zoom with a sufficient maximum scale

<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=yes, maximum-scale=5">

Here, user-scalable=yes explicitly permits zooming, and maximum-scale=5 allows up to 500% zoom, well above the 200% minimum.

Correct: Setting maximum-scale to exactly 2

<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=2">

A maximum-scale of 2 allows 200% zoom, meeting the minimum WCAG requirement. Allowing higher values is even better, but 2 is the minimum acceptable value.

What This Rule Checks

The axe rule meta-viewport inspects the <meta name="viewport"> element in your document’s <head> and verifies two things:

1. The user-scalable parameter is not set to no (or 0).
2. The maximum-scale parameter, if present, is not less than 2.

If either condition is violated, the rule flags the page as having a zoom restriction that may prevent users with low vision from accessing content.

Screen readers rely on language information to select the correct pronunciation engine for content. Each language has its own sound library with unique pronunciation rules, intonation, and phonetic patterns. When a screen reader encounters a lang attribute with a valid value, it seamlessly switches to the appropriate library. But when the value is invalid — for example, lang="egnlish" instead of lang="en" — the screen reader cannot identify the language and falls back to its default, reading the foreign-language text with completely wrong pronunciation.

This primarily affects blind users and deafblind users who depend on screen readers, as well as users with cognitive disabilities who may rely on text-to-speech tools. Imagine hearing Spanish text pronounced with English phonetic rules — it would be nearly incomprehensible.

Note that this rule specifically checks lang attributes on elements within the page (not the <html> element itself, which is covered by a separate rule). It applies whenever you use the lang attribute to indicate that a section of content is in a different language than the rest of the page.

Related WCAG Success Criteria

This rule maps to WCAG 2.0 / 2.1 / 2.2 Success Criterion 3.1.2: Language of Parts (Level AA). This criterion requires that the human language of each passage or phrase in the content can be programmatically determined, except for proper names, technical terms, and words of indeterminate language. Using a valid language code is essential to meeting this requirement — an invalid code fails to programmatically convey the language.

This rule is also referenced by the Trusted Tester methodology, EN 301 549, and RGAA.

How to Fix It

1. Use valid language codes. Language values must conform to the BCP 47 standard. In practice, this means using two- or three-letter codes from the IANA Language Subtag Registry. Common examples include en (English), fr (French), es (Spanish), de (German), zh (Chinese), ar (Arabic), and ja (Japanese).

2. Check for typos. Invalid values are often caused by misspellings (e.g., lang="enlish") or using full language names instead of codes (e.g., lang="French" instead of lang="fr").

3. Use dialect subtags when appropriate. You can specify regional variants such as en-US (American English), en-GB (British English), or fr-CA (Canadian French). The primary subtag alone is also valid.

4. Set the dir attribute for RTL languages. If you’re marking content in a right-to-left language like Arabic or Hebrew, pair the lang attribute with dir="rtl" to ensure correct text rendering.

Examples

Incorrect: Invalid language code

<p>Welcome to our site. <span lang="spn">Bienvenidos a nuestro sitio.</span></p>

The value spn is not a valid language subtag. Screen readers cannot identify this as Spanish.

Incorrect: Full language name instead of code

<p>Here is a quote: <q lang="Japanese">素晴らしい</q></p>

The value Japanese is not a valid BCP 47 language code.

Correct: Valid two-letter language code

<p>Welcome to our site. <span lang="es">Bienvenidos a nuestro sitio.</span></p>

The value es is the valid language subtag for Spanish.

Correct: Valid language code with regional subtag

<p>The Canadian term is <span lang="fr-CA">dépanneur</span>.</p>

The value fr-CA correctly identifies Canadian French.

Correct: RTL language with direction attribute

<p>The Arabic word for peace is <span lang="ar" dir="rtl">سلام</span>.</p>

The value ar is the valid subtag for Arabic, and dir="rtl" ensures proper text directionality.

Correct: Multiple language switches on one page

<p>
  In English we say "goodbye," in German it's
  <span lang="de">Auf Wiedersehen</span>, and in Japanese it's
  <span lang="ja">さようなら</span>.
</p>

Each inline element uses a valid language code, allowing the screen reader to switch pronunciation engines as needed.