In one paragraph
Deprecated ARIA roles must not be used means an effective role matched the legacy-role list in this checker. Prefer supported alternatives that preserve the content's meaning, often ordinary native list markup. Deprecation does not establish that every browser has already stopped supporting the role or that removal has a fixed date. Review the actual structure and avoid replacing specialised semantics mechanically.
Why it matters
Deprecated features are discouraged for new authoring and have recommended alternatives. Their current handling depends on specifications and implementations; the finding is not proof that the page is broken for every user today.
The directory role has no useful distinction from ordinary list semantics in the relevant guidance. Digital Publishing ARIA also deprecates doc-biblioentry and doc-endnote because of their relationship with list-item requirements. Suitable publishing sections can remain while their entries use appropriate native list structure.
Do not confuse an individual endnote entry with the broader doc-endnotes section, or a bibliography entry with the bibliography region. Replacing every doc-prefixed role with list would discard distinctions the task still needs.
How WebAuditOS evaluates this finding
The supplied aria-deprecated-role rule resolves the effective recognised token and checks it against its documented list: directory, doc-biblioentry, and doc-endnote. A fallback beginning with a still-recognised deprecated token can therefore retain the deprecated result.
The source maps minor impact to a low-severity warning. Unknown-role validation is separate, and hidden or unsampled content can remain outside the observed state. A warning does not predict a browser removal date or validate every other publishing role.
How to fix it
- Inspect the reported effective role and the component or publishing tool that generates it. Check the final DOM rather than only a configuration field in an editor.
- For an ordinary reference list or table of contents, prefer suitable native list elements. For example:
<nav aria-label="Contents"><ul><li><a href="#installation">Installation</a></li></ul></nav>Use a real matching destination and an appropriate navigation context. The example is not a reason to add a landmark to every short list.
- For bibliography entries and endnotes, review current DPUB guidance. Preserve useful section identities and link relationships while using native list entries where appropriate. Do not confuse singular deprecated item roles with still-meaningful containing structures.
- Remove a redundant deprecated explicit role when native semantics already provide the intended meaning, or select the proper replacement according to the actual host and task.
- Review ordered fallback tokens. Merely appending a replacement after a recognised deprecated token may leave the old role selected. Do not combine incompatible behaviours in one fallback list.
- Update the source generator so new exports do not reintroduce the role. Check publishing themes, plugins, and conversion pipelines as well as hand-written templates.
- Test reading order, item relationships, note navigation, backlinks, and keyboard access. A vocabulary change must not disconnect readers from the passage or reference they need.
- Rescan valid-role, parent-child, and deprecation checks. Keep version and compatibility decisions documented without describing deprecation as an automatic severe outage.
What the fix can break
A global search-and-replace can alter section roles that were not deprecated. Match exact attributes and review publishing context.
CSS or scripts may rely on the old role as a selector. Move implementation dependencies to an appropriate maintained mechanism while preserving semantics.
Do not use presentational roles simply to stop the warning. The goal is a supported equivalent, not removal of the list relationships.
Questions
Does deprecated mean unsupported everywhere today?
No. It means authors should avoid the feature and use suitable alternatives; implementation support can persist.
Should every doc-prefixed role be removed?
No. Review the specific deprecated entries and preserve appropriate section and link semantics.
Why did adding a second role not clear the warning?
A recognised first token may still be the effective deprecated role. Inspect fallback processing.
Which related checks help?
Review valid roles, required children, and the automation limits guide.
What severity does this get in the report?
Low, shown as a warning. An axe finding takes its severity from the impact axe reports for the element that failed, and the report maps critical and serious to high, moderate to medium, minor to low. axe declares this rule minor, so it arrives as low - and low-severity axe findings are listed as warnings rather than failures.