Skip to content

Addition: update figure role allowances - #415

Merged
scottaohara merged 9 commits into
gh-pagesfrom
issue-412
Feb 13, 2023
Merged

Addition: update figure role allowances#415
scottaohara merged 9 commits into
gh-pagesfrom
issue-412

Conversation

@scottaohara

@scottaohara scottaohara commented Apr 16, 2022

Copy link
Copy Markdown
Member

closes #412

As discussed in w3c/dpub-aria#42 (comment), doc-example is a dpub variant of the figure role. This role being the same as figure but with the opportunity of being exposed as an "example" for its role description, needs to be an allowed role for the figure element.

create test case

Expected results:
doc-example is an allowed role for <figure role=doc-example>...<figcaption>...</figcaption>
figure results in a warning as unnecessary for <figure role=figure>...<figcaption>...</figcaption>
no other roles are allowed if a figcaption is a child of a figure element.


Preview | Diff

closes #412

As discussed in w3c/dpub-aria#42 (comment), `doc-example` is a dpub variant of the `figure` role.  This role being the same as `figure` but with the opportunity of being exposed as an "example" for its role description, needs to be an allowed role for the `figure` element.
@scottaohara scottaohara added needs implementation commitment Cannot merge into spec until implementations in conformance checkers has been confirmed. needs changelog entry once 2 implementations land, we can merge and note it in our changelog. labels Apr 16, 2022
Comment thread index.html Outdated
@stevefaulkner
stevefaulkner self-requested a review July 13, 2022 12:30
@scottaohara

Copy link
Copy Markdown
Member Author

merging as arc toolkit and axe do not report errors when using this role on figure element

@scottaohara scottaohara added Meets 2 implementations req Indicates that a spec change has met the necessary 2 implementations needed to merge. and removed needs implementation commitment Cannot merge into spec until implementations in conformance checkers has been confirmed. needs changelog entry once 2 implementations land, we can merge and note it in our changelog. labels Feb 13, 2023
@scottaohara
scottaohara merged commit 0f29858 into gh-pages Feb 13, 2023
@scottaohara
scottaohara deleted the issue-412 branch February 13, 2023 15:20
chutchins25 added a commit to dequelabs/axe-core that referenced this pull request Jul 29, 2026
A figure with a child figcaption is now limited to its implicit figure
role and the DPub doc-example role, per ARIA in HTML (w3c/html-aria#415).
A figure without a figcaption continues to allow any role.

Closes #3443
straker added a commit to dequelabs/axe-core that referenced this pull request Aug 4, 2026
…5240)

Restricts the roles allowed on a `<figure>` element when it has a child
`<figcaption>`, per the ARIA in HTML update.

## What & why

Per [ARIA in HTML](https://www.w3.org/TR/html-aria/) (`#el-figure`,
[w3c/html-aria#415](w3c/html-aria#415)):

- A `figure` **with** a valid `figcaption` descendant allows **no role
other than `figure`**, plus the DPub role **`doc-example`**.
- A `figure` **without** a `figcaption` allows **any role** (though
`figure` itself is NOT RECOMMENDED) — unchanged.

axe previously modeled `figure` with a flat `allowedRoles: true` and an
inline comment admitting it couldn't match the figcaption case. This
replaces that with a `variant` using a `condition` matcher.

## Implementation notes

- The implicit `figure` role still passes via the existing
`allowImplicit` short-circuit, so the with-figcaption branch only needs
`allowedRoles: ['doc-example']`.
- The matcher checks **direct children** (`vNode.children?.some(...)`),
not a descendant walk: HTML's content model only permits `figcaption` as
the first/last child of `figure`, and a direct-child check avoids a
nested-`<figure>` false match (an inner figure's figcaption wrongly
restricting the outer figure).

## Behavior change

A `<figure>` with a `<figcaption>` and an explicit role other than
`figure`/`doc-example` (including `role="none"`/`role="presentation"`)
now flags on `aria-allowed-role` (minor impact). This is spec-correct
but will surface new findings for existing users.

## Tests
- `get-element-spec` unit — variant resolution with/without figcaption.
- `is-aria-role-allowed-on-element` and `aria-allowed-role` check units
— incl. an open **Shadow DOM** case.
- `aria-allowed-role` virtual-rule — figcaption-child cases (built with
`SerialVirtualNode`) plus the no-figcaption default.
- `aria-allowed-role` integration HTML/JSON — pass (`doc-example`,
implicit `figure`) and violation (`group`) cases; existing no-figcaption
pass retained as a regression anchor.

Closes #3443

---------

Co-authored-by: Steven Lambert <2433219+straker@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Meets 2 implementations req Indicates that a spec change has met the necessary 2 implementations needed to merge.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Correction: allow doc-example role on figure with figcaption

2 participants