w3c
Guidelines for aria-level attribute
Initial draft of content for issue #259 to provide a guidance section on aria-level.
Might still need some discussion related to this open issue on ARIA: w3c/aria#915
Preview link
View the content in compare branch using rawGitHack
I don't think this section needs to be blocked on https://github.com/w3c/aria/issues/915 - we can update APG if necessary when ARIA changes, and have an open issue for APG to track that issue: https://github.com/w3c/aria-practices/issues/1156
As far as I can tell, the next step for this PR is review.
https://github.com/w3c/aria/issues/915 has been resolved, and I've now updated this PR.
The layout of some of the code snippets seems a little wonky and it seems like they don't wrap. Should they/is that an issue of the preview?
Otherwise, looks good to me. 👌
@zcorpan said
That's a known bug of the diff preview.
I had thought as much, thanks for clearing that up friendo!
Thank you for the review, @carmacleod! I've addressed your comments.
I think you're right that the remediation use case example shouldn't add landmark regions.
@mcking65 In section 8.2 for listitem role, wouldn't a better example be for lists that are partially rendered list do to size/length of the list and or bandwidth limitations of the device. This I believe this is one of the primary reason for other similar attributes like aria-posinset and aria-setsize to be included in ARIA.
@mcking65 In section 8.1 Heading Role, what if someone wants to use a aria-level value greater than 6? For example, in some type of document with a high level of nesting. Is that going to be allowed? If not we should state the allowed range i 1 to 6, if allowed there should be some type of guidance on values greater than 6.
WCAG ARIA12 assumes that heading arial-level can be greater than 6. See: https://github.com/w3c/aria/issues/1050
And MDN says:
If you must use the heading role and aria-level attribute, do not go over level 6 so that you are consistent with HTML. Although theoretically you can go higher, and some screen readers may support it, the results can be unpredictable with other browser/screen reader combinations.
JAWS does not support aria-level > 6 (https://github.com/FreedomScientific/VFO-standards-support/issues/301), but NVDA does
The ARIA Authoring Practices (APG) Task Force just discussed Guidance on aria-level.
The full IRC log of that discussion
<MarkMccarthy> TOPIC: Guidance on aria-level<zcorpan> GitHub: https://github.com/w3c/aria-practices/pull/1109
<zcorpan> Link to preview https://pr-preview.s3.amazonaws.com/w3c/aria-practices/pull/1109.html#aria-level
<MarkMccarthy> Matt_King: i see carmacleod, you reviewed this. i have a couple of questions related to this that'd I'd like to ask the group
<MarkMccarthy> Matt_King: on section 8
<MarkMccarthy> Matt_King: some people might be annoyed by this, but we have describing hiearachacal struction inside section 8, but i feel it might be nicer for those scanning by heading if we mentioned aria-level
<MarkMccarthy> Matt_King: in other words, a little redundancy may be helpful for those scanning by heading, to make sure you're in the right place
<MarkMccarthy> Matt_King: can be some work to scan back up
<MarkMccarthy> jongunderson: I think that's a good idea. search engines will pick up better too
<MarkMccarthy> carmacleod: true
<MarkMccarthy> +1 Jon
<MarkMccarthy> Matt_King: kudos to Simon, I love the use case of using the heading role vs. element, putting it in SVG. awesome
<MarkMccarthy> zcorpan: thank you!
<MarkMccarthy> jongunderson: i'm not sure about the listitem example
<MarkMccarthy> Matt_King: the idea being you're quoting a portion of a list that's nested deeply. is it not clear? or do you disagree with the use case?
<MarkMccarthy> jongunderson: I just don't really get it. why would I care what the original order is?
<MarkMccarthy> zcorpan: so, if the original list has several nested lists, then you'd get a little more context of the original
<MarkMccarthy> Matt_King: you'd have to read the last paragraph really close. do you have a better example? It might not be super realistic
<MarkMccarthy> jongunderson: what's the blockquote for?
<MarkMccarthy> Matt_King: idea being you're showing a snippet of the list not the entire list
<MarkMccarthy> jongunderson: if you're using aria-level on a listitem and that item isn't in a container, what's gonna happen?
<MarkMccarthy> jongunderson: other examples like this - if you have a long list of stuff and the DOM only has some of it. wouldn't it have ULs instead of blockquotes?
<MarkMccarthy> jongunderson: using -posinset and -setsize in addition to -level?
<MarkMccarthy> Matt_King: but are those supported on list elements (ULs for example)?
<MarkMccarthy> jongunderson: yeah
<MarkMccarthy> Matt_King: that might make this clearer
<MarkMccarthy> Matt_King: it'd be nice to have an example that makes it more apparent why this is needed. just hard to come up with a good one
<MarkMccarthy> Matt_King: they don't come up IRL very often
<MarkMccarthy> zcorpan: a table of contents list that's broken into chapters in books?
<MarkMccarthy> Matt_King: like 1.1 in the listitem or something?
<MarkMccarthy> zcorpan: right, but only viewing a subset of table of contents for the book. not including the top level chapters, but semantically you'd still see them as second level items
<MarkMccarthy> Matt_King: that might be clearer
<MarkMccarthy> zcorpan: i can try to change that
<MarkMccarthy> Matt_King: I have a question on the one with tree
<MarkMccarthy> s/tree/treeitem
<MarkMccarthy> Matt_King: it'd be nice to have a clear example we're using a tree for something interactive
<MarkMccarthy> Matt_King: suggestions?
<MarkMccarthy> Matt_King: or similar concerns?
<MarkMccarthy> [silence]
<MarkMccarthy> Matt_King: well, Simon, combobox will be a higher priority than this for now. we'll circle back!
<MarkMccarthy> Matt_King: thanks everyone for today
<MarkMccarthy> RRSAgent, make minutes
<RRSAgent> I have made the request to generate https://www.w3.org/2019/11/05-aria-apg-minutes.html MarkMccarthy
<MarkMccarthy> zakim, who is here?
<Zakim> Present: jongund, ZoeBijl, Bryan_Garaventa
<Zakim> On IRC I see siri, Zakim, RRSAgent, Matt_King, jongunderson, MarkMccarthy, zcorpan, carmacleod, MichaelC, Jemma_, github-bot, yatil, jamesn, ZoeBijl, trackbot
<MarkMccarthy> RRSAgent, make minutes
<RRSAgent> I have made the request to generate https://www.w3.org/2019/11/05-aria-apg-minutes.html MarkMccarthy
<MarkMccarthy> zakim, who is here?
<Zakim> Present: jongund, ZoeBijl, Bryan_Garaventa, MarkMccarthy, carmacleod, jamesn, zcorpan
<Zakim> On IRC I see siri, Zakim, RRSAgent, Matt_King, jongunderson, MarkMccarthy, zcorpan, carmacleod, MichaelC, Jemma_, github-bot, yatil, jamesn, ZoeBijl, trackbot
<MarkMccarthy> RRSAgent, make minutes
<RRSAgent> I have made the request to generate https://www.w3.org/2019/11/05-aria-apg-minutes.html MarkMccarthy
I have addressed the comments. 2 examples are new. Please review. 🙂
@JAWS-test ARIA doesn't put any limit to aria-level currently. Is the limitation in JAWS only for heading? Should aria-practices mention it?
ARIA doesn't put any limit to aria-level currently. Is the limitation in JAWS only for heading?
Yes, only for heading.
Should aria-practices mention it?
I don't think so, because other errors of AT are not mentioned either. I think it would be good if the ARIA specification explicitly states that aria-level can also be greater than 6 for heading.
OK. I see that you have filed https://github.com/w3c/aria/issues/1050 already.
The HTML diff service gave a 500 error when the PR preview ran. Now the service seems to be OK again, so I'll close and reopen to rerun PR preview.
@jongund you had some comments about the examples in https://github.com/w3c/aria-practices/pull/1109#issuecomment-550030262 . The examples have been changed since that telecon. Would you like to review? Thanks!
@zcorpan I would recommend changing the class names in the following example:
<div role="heading" aria-level="2" id="room-definition" class="heading-small">Definition of a Room</div>
to
<div role="heading" aria-level="1" class="main-section">Housing Specification</div>
<div role="heading" aria-level="2" id="room-definition" class="sub-section">Definition of a Room</div>
Try not to re-enforce the idea that headings are about big text and smaller text, headings should be about labeling sections and sub-sections in a semantically meaningful way.
@zcorpan
I think the section 8.2 should also talk more specially when only part of a longer list is rendered due to size of the list, screen real estate or bandwith issues, these examples would also include aria-posinset and aria-setsize. This is an example is a list of potential search categories:
<h1>Subject Search Terms</h1>
<ul>
<li aria-level="1" aria-posinset="5" aria-setsize="21">Life Sciences</li>
<li aria-level="2" aria-posinset="1" aria-setsize=""10">Andrology</li>
<li aria-level="2" aria-posinset="2" aria-setsize=""10">Animal Physiology</li>
<li aria-level="2" aria-posinset="3" aria-setsize=""10">Biochemistry</li>
<li aria-level="2" aria-posinset="4" aria-setsize=""10">Bioinformatices</li>
</ul>
Same type of example of partial rendering would be useful for treeitem eample.
@jongund
I would recommend changing the class names in the following example:
This is under "Remediation" - the assumption is that the original markup is bad, but can't be changed other than adding ARIA. Maybe it could explain this better, by using another code snippet for what the original markup is (and that it's bad), and saying what the constraints are more clearly.
The ARIA Authoring Practices (APG) Task Force just discussed aria-level guidance.
The full IRC log of that discussion
<MarkMccarthy> TOPIC: aria-level guidance<zcorpan> GitHub: https://github.com/w3c/aria-practices/pull/1109
<carmacleod> mck: pr is getting close to ready
<zcorpan> ARIA issue about this https://github.com/w3c/aria/issues/1050
<carmacleod> mck: should we allow aria-level > 6?
<carmacleod> simon: some screen reader (s) don't support levels > 6
<carmacleod> jamesn: does it just say "heading" without level?
<carmacleod> simon: not sure
<zcorpan> https://github.com/FreedomScientific/VFO-standards-support/issues/301
<carmacleod> simon: perhaps we should advise authors not to use > 6
<zcorpan> https://github.com/w3c/aria-practices/pull/1109#issuecomment-550029120
<carmacleod> mck: I would be fine with a note saying it's not defined what screen readers will do
<MarkMccarthy> +1 to Matt's suggestion
<carmacleod> simon: according to html, it is possible to have section with h1 to arbitrary depths
<MarkMccarthy> s/Matt's suggestion/Matt's suggestion of a note
Regarding what screen readers do with levels beyond 6, here's a test file I put together back in October.
tldr; seems the levels are correctly exposed at the platform level, but can be erratic when announced by screen readers. for example, any heading beyond 6 can be announced as an h2 depending on the screen reader & browser pairing.
I have added a note about heading levels > 6.
I have also tried to address @jongund's comments.
Looks good. The note about > 6 is useful - thanks.
I see that class="example" was used, which gives the example a light orange background and a vertical orange bar in the left margin. I see this style in older versions of the APG (and only on <pre> elements), but it's not used in the current version. We should ask the group if it was intentionally removed.
The ARIA Authoring Practices (APG) Task Force just discussed aria-level.
The full IRC log of that discussion
<MarkMccarthy> TOPIC: aria-level<MarkMccarthy> Matt_King: people were questioning whether or not to use this with list item
<MarkMccarthy> Matt_King: do these examples in the list item section make sense without context; are they useful?
<carmacleod> https://pr-preview.s3.amazonaws.com/w3c/aria-practices/pull/1109.html#aria-level_listitem_role
<MarkMccarthy> Matt_King: i think I want to have aaron leventhal read this, esp. the tree one
<MarkMccarthy> carmacleod: that's a good idea
<MarkMccarthy> jamesn: yep
<MarkMccarthy> Matt_King: i think there was a different approach to doing tree
<MarkMccarthy> Matt_King: like making a treegrid out of a table, and there -isn't- a way for the browser to calculate the values
<MarkMccarthy> Matt_King: i'm not 100% sure how the browser calculates that. we might be able to come up with better examples for row and tree. i'm really murky on the list item one
<MarkMccarthy> Matt_King: we know it's supported etc., but is the better guidance not to inclulde it because it doesn't give value
<MarkMccarthy> jamesn: i've never seen a good use of it on list item
<MarkMccarthy> jamesn: i'd hate to see someone do what's in the example
<MarkMccarthy> Matt_King: don't want to suggest anything to the world any of us think is awful
<MarkMccarthy> jamesn: i don't even understand the example. you can't just -do- that
<MarkMccarthy> carmacleod: in the PR comments, jon said: I think the section 8.2 should also talk more specially when only part of a longer list is rendered due to size of the list, screen real estate or bandwith issues, these examples would also include aria-posinset and aria-setsize. This is an example is a list of potential search categories:
<MarkMccarthy> Matt_King: but even if you had a list that was only partially rendered; if I got to it and it said nesting level 5 with -nothing- around it, then what does that even mean?
<MarkMccarthy> Matt_King: specifically, JAWS says something like 'nested list of 5 items' or something like that
<MarkMccarthy> Matt_King: tables tell you the nesting level, not sure with ilsts. but i'm imagining hearing "nested list" and not seeing anything else around it. i'd be really confused
<MarkMccarthy> jamesn: so we'd need an aria property that this element is partially rendered, and the cursor needs to sync up with the DOM to fetch the right content. we don't have anything like that
<MarkMccarthy> Matt_King: a lot of times when something is visually partially rendered, it's in the DOM --
<MarkMccarthy> jamesn: no, not always
<MarkMccarthy> Matt_King: presumably, you could get to previous and next, right?
<MarkMccarthy> jamesn: not...necessarily
<MarkMccarthy> carmacleod: if you're in a virtual buffer, you won't hit that
<MarkMccarthy> Matt_King: so then, we're talking about feeds technically
<MarkMccarthy> jamesn: yes, but they're not feeds. what we need is a more generic way of doing feeds
<MarkMccarthy> Matt_King: when it comes to APG guidance that is correct -today-, is using aria-level valuable on a list item?
<MarkMccarthy> jamesn: yes... potentially. if i'm going through lists with other navigable content. if the thing at level one gets scrolled out of the DOM and only level 2 things are there, it's better to keep it level 2 than reset it to level 1
<MarkMccarthy> Matt_King: i can agree it's theoretically better, so it's better authors do the best they can - even if there's no way to to make that information consumable in a very useful way
<MarkMccarthy> jamesn: i agree it's not perfect. but it's better than those things changing due to content disappearing
<MarkMccarthy> jamesn: this happens all the time
<MarkMccarthy> Matt_King: we don't have an example of this in the APG. is there an example of something in the wild we could mimic?
<MarkMccarthy> MarkMccarthy: something like facebook's news feed? or reddit?
<MarkMccarthy> Matt_King: well facebook uses the right elements for the news feed etc., or amazon's menu bars, etc.
<MarkMccarthy> jamesn: the ones you see a lot are grids, where rows scroll in and out
<MarkMccarthy> Matt_King: well that's a widget, and we can kind of handle that
<MarkMccarthy> jamesn: yes, if someone is using table commands in their screen reader
<MarkMccarthy> Matt_King: with NVDA and VO, as long as there's focusable elements in the table cells, then they'll go through with no problem
<MarkMccarthy> jamesn: so that's something screen readers are doing based on inference, or trying to fix behavior
<MarkMccarthy> Matt_King: not quite, it's the grid responding to focus; when the last item is focused the grid loads more. NVDA and VO drag focus with the reading cursor
<MarkMccarthy> jamesn: either way, there's lists where this happens, but i'm having trouble of thinking examples
<MarkMccarthy> jamesn: maybe something like google docs where you only get a small amount rendered in the DOM at one time
<MarkMccarthy> Matt_King: for this to work in a list, you'd need a massive list where the beginning is truncated
<MarkMccarthy> jamesn: we do that, with trees as well
<MarkMccarthy> carmacleod: like a filesystem
<MarkMccarthy> Matt_King: dropbox. but they load a new page for each folder
<MarkMccarthy> Matt_King: i wonder if box or another one does something like that. uses a list but shows the whole tree
<MarkMccarthy> jamesn: our tree view does this
<MarkMccarthy> Matt_King: jamesn, do you have any direct suggestions on how to make the list items section of aria-level better or right?
<MarkMccarthy> jamesn: yeah. something with aria level 1 and aria level 2 with no UL between them - not sure why we have both levels with nothing between
<MarkMccarthy> Matt_King: so, it's clear we need more work here. i don't actually know what to change. suggestions welcome
<MarkMccarthy> jamesn: i know the idea is to cover all scenarios, but if -we're- struggling to think of use cases, i wonder if we should even include it?
<MarkMccarthy> carmacleod: i thought that too
<MarkMccarthy> Matt_King: me too. not having it at all seems a problem, but...
<MarkMccarthy> jamesn: we could acknowledge it. something like "it's allowed, please submit one, but we can't think of one or might deprecate in the future" FOR EXAMPLE
<MarkMccarthy> carmacleod: [chuckles]
<MarkMccarthy> github: https://github.com/w3c/aria-practices/pull/1109
<MarkMccarthy> zakim, who is here?
<Zakim> Present: Matt_King, MarkMccarthy, carmacleod, siri, JamesNurthen
<Zakim> On IRC I see carmacleod, siri, MarkMccarthy, Zakim, RRSAgent, Matt_King, zcorpan, MichaelC, github-bot, ZoeBijl, jamesn, yatil, trackbot
<MarkMccarthy> RRSAgent, make minutes
<RRSAgent> I have made the request to generate https://www.w3.org/2020/02/25-aria-apg-minutes.html MarkMccarthy
<MarkMccarthy> zakim, please part
<Zakim> leaving. As of this point the attendees have been Matt_King, MarkMccarthy, carmacleod, siri, JamesNurthen
<siri> - /me thank you
The ARIA Authoring Practices (APG) Task Force just discussed Guidance / aria-level.
The full IRC log of that discussion
<MarkMccarthy> TOPIC: Guidance / aria-level<MarkMccarthy> mck: in the PR i included a link to a preview
<MarkMccarthy> https://raw.githack.com/w3c/aria-practices/issue259-aria-level-guidance/aria-practices.html#aria-level
<MarkMccarthy> MarkMccarthy: link is above
<MarkMccarthy> group: [reading through some of the text]
<MarkMccarthy> mck: problematic bit is we don't know what to say for listiem
<MarkMccarthy> s/listiem/listitem
<MarkMccarthy> mck: basically - is what's being presented in section 8.2 realistic?
<MarkMccarthy> Jemma: any thoughts BGaraventa
<MarkMccarthy> jongund: unless it's a fragment of a larger list, why would we do this?
<MarkMccarthy> BGaraventa: like sublists?
<MarkMccarthy> jongund: no, like this is a deeper list --
<MarkMccarthy> siri: it has aria-level 2, should it be 1? do we need to keep aria-levels on an OL?
<MarkMccarthy> jongund: maybe these aren't the best examples, don't want to confuse people if we can help it
<MarkMccarthy> jongund: maybe using div and listitem. do browsers compute the levels with that combination?
<MarkMccarthy> mck: not sure if it's required that they do but i think they consistently do
<MarkMccarthy> mck: usually, screen readers don't reveal the depth to you, but maybe the nesting level in the beginning of the announcement
<MarkMccarthy> mck: it's not on the LI it's on the UL
<MarkMccarthy> mck: i wonder if this allows you to create a nested list without a nested parent list element?
<MarkMccarthy> mck: like three list items with the same parent, but different levels
<MarkMccarthy> siri: that's the last example they had; i think it's really confusing to have sibling LIs but different levels
<MarkMccarthy> CurtBellew: +1
<MarkMccarthy> siri: i also won't usually recommend going more than 2 levels, and screen readers won't group by level, they'll just read total LIs
<MarkMccarthy> mck: right it's not read like a tree or interactice listitem
<MarkMccarthy> s/interactice/interactive
<MarkMccarthy> mck: seems odd that screen readers can't/won't query that info, but you can nest as far as info architecture requires
<MarkMccarthy> mck: bigger question is, what do we say about using aria-level on listitems? it's supported but...no practical examples of its use
<MarkMccarthy> mck: that doesn't seem like good guidance. we could recommend people not do it, but that also would need a rationale
<MarkMccarthy> mck: only circumstance is a big list that doesn't fit in the DOM and how AT keeps track of the nesting. never seen that in a static list
<MarkMccarthy> Jemma: spec says in RARE scenarios; problem is we're trying to find those rare scenarios, rather than practical uses. or, if the rare scenarios are indeed rare/theoretical, do we really need it?
<MarkMccarthy> mck: +1. if it's truly a rare scenario.... is it so rare we can't come up with a realistic one to share?
<MarkMccarthy> Jemma: that's what i'm saying!
<MarkMccarthy> mck: that's how it feels to me
<MarkMccarthy> jongund: the only examples is if you're creating list items out of divs, but that's about it
<MarkMccarthy> CurtBellew: but then wouldn't you put it on the UL?
<MarkMccarthy> mck: well, if the roles are applied correctly, browsers should calc it appropriately
<MarkMccarthy> CurtBellew: i see
<MarkMccarthy> jongund: only place is in a tree widget or something...
<MarkMccarthy> mck: but that's treeitem right?
<MarkMccarthy> jongund: i know - so maybe it shouldn't be allowed on listitem
<MarkMccarthy> Jemma: [chuckles]
<MarkMccarthy> mck: well, a situation where a portion of the list scrolls in and out... only a piece of it is in the DOM...
<MarkMccarthy> Jemma: last time, sarah said microsoft is proposing something to address that... but anyway
<MarkMccarthy> mck: BGaraventa have you encountered any real life scenarios for this?
<MarkMccarthy> BGaraventa: not personally, which isn't to say there isn't one or a reason, but I have no direct experience
<MarkMccarthy> jongund: if we don't have a good example, it's probably not a good use of time - we have lots of other problems we -can- solve. maybe it's just an artifact of listitem
<MarkMccarthy> CurtBellew: an example with divs?
<MarkMccarthy> jongund: well, it's a matter of if browsers need to calc it or just advisory
<MarkMccarthy> CurtBellew: makes sense
<MarkMccarthy> jongund: and mck you said the level doesn't play into the UX of lists, really, right?
<MarkMccarthy> mck: well, with a partial list. say the second half of a structure with two levels of nesting - if you didn't present the proper level of nesting...
<MarkMccarthy> jongund: so then how about this - if a list is only partially represented AND it's important, then this can be used. i can rewrite this section to match up with that
<MarkMccarthy> Jemma: +1
<MarkMccarthy> mck: something where there's a couple levels and the first portion is cut off so the first thing you come to is a list item at the second level of nesting.
<MarkMccarthy> mck: what's weird to me - if the whole thing isn't in the DOM, would you encounter a list item without a parent list? or an invalid list structure?
<MarkMccarthy> mck: becuase that results in -other- problems
<MarkMccarthy> github: https://github.com/w3c/aria-practices/pull/1109
<MarkMccarthy> BGaraventa: if you're gonna directly add a list item into something, the browser will auto calc the number of children when a node is added or removed, always at the same level.
<MarkMccarthy> BGaraventa: so i can't really see a logical reason for different levels
<MarkMccarthy> mck: just trying to picture the incomplete DOM thing. you'd need a whole list anyway, so a browser would calc the correct level...
<Jemma> s/sarah said microsoft/one of CSUN presentations by Microsoft
<MarkMccarthy> BGaraventa: and the a11y tree isn't computed after the DOM is done
<MarkMccarthy> mck: so now i'm thinking about raising an issue with aria about not having this on LI
<MarkMccarthy> BGaraventa: +1
<MarkMccarthy> siri: +1
<MarkMccarthy> CurtBellew: +1
<Jemma> +1
<MarkMccarthy> mck: okay, so i'll raise that issue. this seems impossible.
<Jemma> no aria level for li!
<MarkMccarthy> mck: so if there's consensus, maybe we'll leave this out.
<MarkMccarthy> mck: or 1.3 if nothing else
<MarkMccarthy> zakim, who is here?
<Zakim> Present: mck, Jemma, jongund, CurtBellew, MarkMccarthy, Bryan_Garaventa, siri
<Zakim> On IRC I see jongund, BGaraventa, siri, CurtBellew, Jemma, MarkMccarthy, Zakim, RRSAgent, mck, Michael, github-bot, jamesn, ZoeBijl, trackbot
<MarkMccarthy> RRSAgent, make minutes
<RRSAgent> I have made the request to generate https://www.w3.org/2020/03/31-aria-apg-minutes.html MarkMccarthy
Suggested edits to section 9.4: Add the following sentences: The rows with aria-level=2 represent responses to the last previous row with aria-level=1 and visually this relationship is typically displayed the rows with aria-level=2 indented. aria-level in this example is providing the information of the response relationship that is represented visually by indenting.
Thanks, @jongund I understand better why the response is aria-level="2"
