Accessibility Guides for attention deficit

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.

When a web page uses CSS media queries like @media (orientation: portrait) or @media (orientation: landscape) to force content into a single orientation, it prevents the page from responding to the user’s actual device position. This is checked by the axe rule css-orientation-lock.

Why this matters

Many users physically cannot rotate their devices. People with mobility impairments may have their phone or tablet mounted to a wheelchair, bed, or desk in a fixed orientation. Users with low vision may prefer landscape mode to enlarge text, while others may find portrait easier to read. Locking orientation removes their ability to choose what works best for them.

Beyond motor and vision disabilities, orientation locking also affects users with cognitive disabilities and dyslexia who may rely on a particular layout for readability. Sighted keyboard users who use external displays or stands may also be impacted.

This rule relates to WCAG 2.1 Success Criterion 1.3.4: Orientation (Level AA), which requires that content not restrict its view and operation to a single display orientation unless a specific orientation is essential. Essential use cases are rare — examples include a piano keyboard app, a bank check deposit interface, or a presentation slide display where the orientation is integral to the functionality.

How to fix it

1. Remove orientation-locking CSS. Look for @media queries that use the orientation feature combined with styles that effectively hide or completely rearrange content for only one orientation (e.g., setting display: none or width: 0 on the body or main content).
2. Use responsive design instead. Rather than checking orientation, use min-width or max-width media queries to adapt your layout to available space. This naturally accommodates both orientations.
3. Test in both orientations. Rotate your device or use browser developer tools to simulate both portrait and landscape modes. Verify that all content remains visible and functional.
4. Only lock orientation when essential. If your application genuinely requires a specific orientation for core functionality (not just aesthetic preference), document the rationale. This is the only valid exception.

Examples

Incorrect: Locking content to portrait only

This CSS hides the main content area when the device is in landscape orientation, effectively forcing users to use portrait mode:

<style>
  @media (orientation: landscape) {
    .content {
      display: none;
    }
    .rotate-message {
      display: block;
    }
  }
  @media (orientation: portrait) {
    .rotate-message {
      display: none;
    }
  }
</style>

<div class="content">
  <h1>Welcome to our site</h1>
  <p>This content is only visible in portrait mode.</p>
</div>
<div class="rotate-message">
  <p>Please rotate your device to portrait mode.</p>
</div>

Incorrect: Using transform to force portrait layout in landscape

<style>
  @media (orientation: landscape) {
    body {
      transform: rotate(-90deg);
      transform-origin: top left;
      width: 100vh;
      height: 100vw;
      overflow: hidden;
      position: absolute;
    }
  }
</style>

This forcibly rotates the entire page, fighting against the user’s chosen orientation and creating a confusing, inaccessible experience.

Correct: Responsive layout that works in both orientations

<style>
  .content {
    padding: 1rem;
  }
  .grid {
    display: grid;
    grid-template-columns: 1fr;
    gap: 1rem;
  }
  @media (min-width: 600px) {
    .grid {
      grid-template-columns: 1fr 1fr;
    }
  }
</style>

<div class="content">
  <h1>Welcome to our site</h1>
  <div class="grid">
    <div>
      <p>Column one content.</p>
    </div>
    <div>
      <p>Column two content.</p>
    </div>
  </div>
</div>

This approach uses min-width instead of orientation, adapting the layout based on available space. The content remains fully accessible and readable whether the device is held in portrait or landscape.

Correct: Using orientation queries for minor style adjustments (not locking)

<style>
  .hero-image {
    width: 100%;
    height: 200px;
    object-fit: cover;
  }
  @media (orientation: landscape) {
    .hero-image {
      height: 300px;
    }
  }
</style>

<img class="hero-image" src="hero.jpg" alt="A scenic mountain landscape">

Using orientation media queries is acceptable when you’re making minor visual adjustments without hiding or restricting access to content. The key is that all content and functionality remain available in both orientations.