SiteLint documentation and guidelines

Verify abbreviation expansions

Description

This rule verifies that all abbreviations in the page content have a mechanism available to identify their expanded form or meaning. Abbreviations such as acronyms, initialisms, and shortened words can be ambiguous for users who rely on assistive technologies, have cognitive disabilities, or are not familiar with domain-specific terminology. A mechanism may include the <abbr> element with a title attribute, providing the expansion in text upon first use, linking to a glossary definition, or using a dedicated abbreviations section. The requirement is defined in WCAG Success Criterion 3.1.4 Abbreviations (Level AAA).

This rule performs a manual check: it flags the page for review rather than automatically detecting unexpanded abbreviations. Because abbreviation usage is context-dependent and language-specific, automated detection alone cannot reliably determine whether every shortened form has an appropriate expansion. A manual review ensures that domain-specific acronyms, industry jargon, and abbreviations introduced dynamically are all properly explained.

Disabilities impacted

  • Visual (blindness, low vision) – Screen reader and Braille display users hear or feel each letter of an abbreviation individually. Without an expansion mechanism, they must guess the meaning or rely on context, which is especially problematic for unfamiliar or domain-specific acronyms. The <abbr> element with a title is announced by many screen readers, but support is not universal.
  • Cognitive (learning disabilities, memory impairments) – Users with cognitive disabilities may have difficulty recalling the meaning of abbreviations, particularly when multiple different abbreviations appear in the same document or when the same abbreviation has different meanings in different contexts. Providing explicit expansions reduces cognitive load and improves comprehension.
  • Language and comprehension (non-native speakers) – Users who are not fluent in the document’s language may not recognise common abbreviations that native speakers take for granted. An explicit expansion or glossary link makes the content accessible without requiring external dictionary lookups.

Why it matters

Abbreviations are a natural part of written language, but they create a barrier when their meaning is not readily discoverable. WCAG 3.1.4 (Level AAA) requires that a mechanism exists for identifying the expanded form of any abbreviation. This is not about removing abbreviations but about ensuring that every user can access their meaning. Failing to meet this criterion blocks conformance at the AAA level. Beyond compliance, providing abbreviation expansions improves usability, search engine understanding of content, and the overall clarity of technical documentation. Because this rule is a manual check, the reviewer must examine the page holistically and confirm that every abbreviation has a corresponding expansion available.

Coding problems and solutions

Common coding problems

  • Missing <abbr> element – Abbreviations are wrapped in a <span> or plain text without any semantic markup, providing no machine-readable expansion.
  • Missing or empty title attribute – The <abbr> element is used but the title attribute is omitted, left empty, or contains the same text as the abbreviation, offering no additional information.
  • Inconsistent expansion on first use – The expanded form is provided in prose on first occurrence but omitted on subsequent occurrences, leaving later instances unexplained.
  • Abbreviation defined only via CSS or visual cues – The expansion is hidden off-screen, styled with ::before / ::after pseudo-elements, or otherwise made invisible to assistive technology.
  • Reliance on <acronym> (deprecated) – The deprecated <acronym> element is used instead of the standard <abbr> element.

How to fix it

Use the <abbr> element with a title attribute

Note that support for the title attribute varies across screen readers. For instance, VoiceOver by default has Hints set to “Never” or “Speak after delay”, which may prevent the title from being announced. Do not rely solely on title for critical information.

Correct example
<p>
  The <abbr title="World Health Organization">WHO</abbr>
  published new accessibility guidelines today.
</p>
Incorrect example
<p>
  The WHO published new accessibility guidelines today.
</p>

Provide the expansion in prose on first use

Correct example
<p>
  The Document Object Model (<abbr title="Document Object Model">DOM</abbr>)
  is a cross-platform API. The <abbr title="Document Object Model">DOM</abbr>
  represents the page structure as a tree of nodes.
</p>
Incorrect example
<p>
  The DOM is a cross-platform API. The DOM represents
  the page structure as a tree of nodes.
</p>
Correct example
<p>
  The <a href="/glossary#wai-aria"><abbr title="Web Accessibility Initiative – Accessible Rich Internet Applications">WAI-ARIA</abbr></a>
  specification defines roles and attributes.
</p>
Incorrect example
<p>
  WAI-ARIA defines roles and attributes that enhance accessibility.
</p>

Use aria-describedby to point to an expansion (dynamic content)

Correct example
<p>
  <abbr id="api-abbr" aria-describedby="api-def" title="Application Programming Interface">API</abbr>
</p>
<p id="api-def" hidden>Application Programming Interface – a set of
  functions and protocols for building software.</p>
Incorrect example
<p>
  <span class="abbr" title="API">API</span>
</p>

Use a dedicated abbreviations section for documents with many abbreviations

Correct example
<section aria-labelledby="abbr-heading">
  <h2 id="abbr-heading">Abbreviations used in this document</h2>
  <dl>
    <dt><abbr title="Cascading Style Sheets">CSS</abbr></dt>
    <dd>Cascading Style Sheets</dd>
    <dt><abbr title="HyperText Markup Language">HTML</abbr></dt>
    <dd>HyperText Markup Language</dd>
  </dl>
</section>
Incorrect example
<!-- No abbreviations section at all -- the reader must guess -->
<p>
  This document covers WCAG, ARIA, HTML, CSS and JS best practices.
</p>

Known Limitations

  • Single-page applications (SPAs) – Dynamic content loaded via JavaScript may inject abbreviations without corresponding <abbr> elements or expansion mechanisms. The rule depends on the DOM at audit time; client-side rendering that adds abbreviations after the audit runs will be missed.
  • Shadow DOM – Abbreviations inside closed shadow roots are not visible to the rule’s selector and will not be evaluated. Open shadow roots are traversable but require additional handling in the audit logic.
  • Same abbreviation, multiple meanings – The rule cannot automatically verify that the expansion is contextually correct in every instance. A title attribute may be present but contain an incorrect or misleading expansion, which requires a manual review.
  • Non-HTML content (PDF, SVG, MathML) – The rule only inspects HTML elements. Abbreviations inside embedded SVG, MathML, or PDF content must be checked with separate tools or manual review.
  • Manual verification required – Because this rule issues a manual check, it does not automatically detect violations. The reviewer must examine the page and confirm that all abbreviations have a suitable expansion mechanism.

Resources

Rule

  • Audit: accessibility
  • Standard: WCAG
  • Level: AAA
  • Success Criteria: 3.1.4
  • Rule ID: abbreviations