`<callout>` element for callouts/alerts/admonitions

[LeaVerou]

What problem are you trying to solve?

Callouts (aka admonitions or alerts) like notes, tips, warnings, etc. are very common in documents. However, there is no clear way to mark them up correctly, and the ways authors devise often suffer from poor accessibility (talking about it with @matatk, it’s important that they are marked up with a sectioning element, so that screen reader users know where the callout ends, but plain divs are used more often than not).

What solutions exist today?

Every design system invents their own, and the vast majority use divs. A few examples:

• GitHub uses divs
• Just the docs uses <blockquote>
• Coda uses divs as well
• Notion also uses divs
• W3Schools proposes divs too
• Foundation uses div + h5
• Bootstrap
• Shoelace
• W3C specs (example) use divs + CSS ::before for the label
• Same with WHATWG specs (example)

How would you solve it?

An MVP could simply be a new <callout> element with proper semantics and some light base styling by default.

Ideally, you want this to provide more value to authors than semantics, to motivate them to use it. One wya to do that is to support a slot for labels, and an optional type attribute, with predefined values (note, tip, warning, example etc.) or custom (which would be the default), and a label attribute. The predefined callout types would produce an automatically localized label and slightly different styling. For things that require formatting, where an attribute is not sufficient, authors can use the label slot directly.

Later, we could increase the value proposition further, via an icon slot and an icon attribute, which can take either a string (for emojis), a URL, or certain keywords.

Anything else?

Prior art:

• https://toast.al/posts/softwarecraft/2023-08-29_semantic-markup-for-callouts
• https://www.stylemanual.gov.au/structuring-content/text-boxes-and-callouts

[zcorpan]

A new element would require some parser changes (to make it close p elements).

ARIA has a note role, which might be close enough? https://w3c.github.io/aria/#note

[domenic]

I think it's a good idea to pave a cowpath like this.

However, can you say more about how the proposed element would be an accessibility improvement? /cc @whatwg/a11y

It sounds like you're suggesting it be a sectioning element. Concretely, do you mean that like a <section>-with-a-name, it would map to the region ARIA role? If so, what accessible name would it have?

[jimmyfrasche]

If I am reading a text that contains callouts I may read a sentence or two and decide it does not apply to me and skip down to continue reading the main text. Later, I may realize I should have read it and scan up looking at the callouts for the one I skipped. I imagine the equivalent actions for screen readers would be a key combo to exit the current callout to the main text and some means to navigate by callouts.

[domenic]

I find that imagining how screen readers behave can be counterproductive.

[hidde]

Another accessibility benefit of standardised callouts/alerts/admonitions could be (the potential of) personalisation, for cognitive disabilities, and more useful rendering in reader modes.

[patrickhlauke]

i'll admit i'm not quite sure how a proposed <callout> with default (by the sound of it?) styles for warnings etc (which authors will then likely immediately want to override to match their particular look and feel) and slots would be exposed in a sensible way to assistive tech in a way that's better than a hand-rolled section with an accessible name (and an appropriate role which will depend on the nature of the "callout"). maybe it's the "don't need to even hand-roll it anymore" part that is the point here, but i'm not sure how it would be any better for AT unless screen readers also did lots of work implementing and announcing these callouts in a different and more useful way.

[LeaVerou]

@domenic @patrickhlauke

I will let the a11y experts comment on the specifics of the semantics (@matatk ? @alice?), my understanding is merely that divs are insufficient and blockquotes are flat out wrong, yet these are what is most frequently used right now.

Authors are much more willing to use HTML elements than ARIA as it also provides DX benefits. The default UA styling is merely further motivation (if done well). It seems very clear from the current state of things that asking authors to hand roll it doesn't work well. It's also entirely possible the underlying AT doesn't provide great primitives for callouts — that’s another reason to have an element: the element can be associated with the current state of the art in and once the underlying technology improves, the element semantics can be upgraded transparently, upgrading the web for AT users in one fell swoop, rather than having to painfully educate authors once more.

[patrickhlauke]

I will let the a11y experts comment on the specifics of the semantics

good to know that I don't count as an a11y expert... ;)

[LeaVerou]

I will let the a11y experts comment on the specifics of the semantics

good to know that I don't count as an a11y expert... ;)

Settle down Patrick ;) I pinged two specific a11y experts because they are or have been on the TAG, as I wanted to capture that particular perspective in the thread (especially since the proposal came out of a convo with one of them). In case it's not obvious, I was not implying that the parentheses in my comment were an exhaustive list of all a11y experts in the world (they’re not even an exhaustive list of the ones I know personally!).

[scottaohara]

Generally agree that this would be nice, but I'd modify the proposal a bit, as currently the proposed use cases for this single element could actually touch on a few different potential roles / potential elements.

for instance, if done "right" now, a warning/alert could be (for example) a role=region, group, alert, or status depending on the type of content it represents (if it's meant to act as a live region or not could be a factor, or the severity of the information presented could determine the role someone were to use - if they aren't just throwing divs around).

if it's a note/example, like what is used in the WHATWG/W3C specs, then role=note would be appropriate (i've actually wanted a 'note' element for awhile now.)

I know it was referenced as one of the 'wrong' things (and likely is misused in a lot of cases) but a "callout" could potentially even be a correctly used blockquote, if it actually represents a quote from another source.

In my opinion, it would be good to have a distinction here (and thus maybe this could be a proposal for 2 elements), rather than considering all the mentioned use cases a single 'callout'.

For instance, if there was a <note> and a <callout> (or <notification>?), then it could make it clear to someone using AT that the first represents additional information, while the second represents important "callouts" that may even need to be acted upon. Having them all under the same implicit role would make this distinction less clear / would prevent the possibility of AT allowing people to navigate to the different content by the type of content. Or in other words, one element for all the different types of callouts could be useful, but if one needed to be more granular, then they'd still just need to reach for the ARIA roles that are more appropriate - or potentially use the new element 'incorrectly' since a better suited ARIA role existed for the use case.

If <note> was added, the cow path of <div class=note>Note: ...</div> could be paved to use an existing role. For the other scenarios, whatever role is decided upon as the base (an existing role or potentially a 'new' one), regardless of how AT 'could' work with it, it would be a benefit to be able to consistently expose it - so then AT could do whatever they wanted with it, which they can't now due to the variability of implementations which don't even necessarily have any meaningful ARIA semantics to expose.

And then people use the existing elements, styled as they wish, for the remaining use cases that 'could' be 'callouts'.

[LeaVerou]

@scottaohara Wouldn't <callout type="note"> cover the use cases for <note>? Given that these are usually styled in a very similar way, I think there's some value in grouping them under a single element, but it sounds like type should be part of the MVP, and that a generic <callout> would not be useful? Are there any useful semantics that could apply to <callout> in general? (so they can apply to custom callouts)

[scottaohara]

@LeaVerou

Wouldn't <callout type="note"> cover the use cases for <note>?

Yes, potentially. That is if using the type attribute to modify the semantics of the element is a desired pathway forward. My understanding/recollection was that when popup was being proposed as an element, that using type to adjust its semantics to match the kind of popover it was meant to be (per its content/use case) wasn't desired. This seems like it'd be similar. But if I was incorrect in my understanding, or that has changed, then sure... one element with types that could modify the visual style and in some cases the ARIA semantics.

...and that a generic <callout> would not be useful? Are there any useful semantics that could apply to <callout> in general? (so they can apply to custom callouts)

If by 'generic' you mean one type of potential role that could be used to apply to all of these / all of these non-note types... eh? That seems like it'd be a miss if that was the desired route and could overlap with existing elements like article or section then.

I did mention some roles that these sorts of callouts could be marked up as in my previous comment. but the callouts that are more 'important' (warnings, errors/alerts, potentially dynamic info messages) could be exposed as status and alert roles (ideally with a way to indicate if they should be treated as an auto-live region, or not). They could potentially repurpose the region or complementary landmark roles (which are already handled by section and aside)... but I personally think it makes more sense for someone to be very mindful about when they use landmarks... the more landmarks that are added to page, the less useful they end up being...

The 'tips, examples and notes' could all arguably be under the note role. They're not as important the draw attention to as the above mentioned types. They generally would not be desired to be live regions, and also not landmarks.

But, going any further down those rabbit holes probably need to have the original question answered, if it's desired for type to change an element's role and thus its potential usage and the type of content that would be expected within it. If type is fine, then we can work this out. If that is not, then it's probably better to go with different elements, and let people style them how they want (which can be similar to each other if they so choose)

[LeaVerou]

@scottaohara I think with <popup> the issue was that there were no useful semantics without type, which is why I asked if there are any useful semantics for <callout> that has a custom type.

the more landmarks that are added to page, the less useful they end up being...

Agreed. Is there any way to prioritize landmarks? If not, should there be?

The 'tips, examples and notes' could all arguably be under the note role.

Agreed. Though I still think the distinction could be useful for AT users from a UX perspective: I imagine an AT user may choose to e.g. skip tips or examples in a document but may still want to read notes. A sighted user can easily do that as they're styled differently. So perhaps all three could still be using a note role, but announced differently?

For custom callouts, I was envisioning things that are too purpose/domain-specific to be standardized. E.g. in my book I had callouts called "Future" which described future web standards developments:

Is there value in these types of callouts using a separate element? Presumably the benefit of AT users being able to skip that kind of content easily still applies?

[scottaohara]

@LeaVerou i had a much longer response to specifically answer/dig into some of your previous comment, but I think maybe that makes more sense to discuss separately, if you want.

Rather, I will respond by saying that, I do appreciate/want this proposal to progress. If type can be used to allow users to determine the semantics, then great. we can work out what each type could be, though there would likely be overlap in the underlying ARIA semantics, and there would need to be clear author guidance as to what would be appropriate for each callout type.

But I think to hopefully address your question about a generic/custom callout - this is where there is exact overlap with popup I mentioned. If there's no known/defined purpose for such content, but it is important to emphasize, is this not just a section or article element that is styled to look like a callout? Potentially even a div with a heading. If roles are based on the type, and then there's a ? for what a generic/custom version looks like - to me that says it's up to the developer to figure that out and potentially reach for the correct element instead and apply styling to that. I mean, the styles that consistently apply to these elements are largely variations of background colors and maybe a border or icon. Not a big LOE to create using the appropriate element.

[domenic]

To make @scottaohara's point a bit more concrete, from my perspective this proposal is blocked on explaining the exact accessibility benefits, in the form of ARIA mappings for each potential state of the element. Especially if (as some have suggested) this involves new roles, or modifying AT behavior in a way that goes beyond roles, then that would be a significant lift which we've rarely succeeded with in the past.

The best ARIA mappings I can see right now are just the same as that which section has, so, if people believe a dedicated element is a good idea here, please suggest something better.

[hidde]

That sounds like you're reducing accessibility to ARIA mappings? Even if those are non existent, distinctions can be helpful beyond AT, including for personalisation, COGA and reader modes, which can all improve accessibility for specific users (sorry for almost repeating myself), regardless of whether this would go the separate element or type route.

[annevk]

The benefits have to be concrete, not speculative, and cannot depend on as-of-yet unrealized downstream inventions. If your new markup idea requires implementation work beyond browsers it will have to be enormously compelling (and likely it isn't).

[aardrian]

This was opened with assertions conveyed from an IRL conversation, but not everyone in that conversation has weighed in with all the potential scenarios / benefits they discussed. That might be useful.

Seeing this construct in print as a sighted reader is often confusing to me because sometimes it is redundant with the content (a visual flair to repeat a particular statement), sometimes a parenthetical thought, sometimes a de facto footnote, and so on.

IMO, <figure> and <blockquote> can already do the lifting on some / most of these. Some of the other artifacts of print design I cited, also IMO, don't warrant landmarks.

To @hidde's question, if we want to expose these in any meaningful way to SR users then ARIA mappings are where to start. COGA SR users would be included in that. Otherwise, can you identify how you think a new element / type might help other users (that are not strictly visual affordances an author could do or undo on their own)?

[hidde]

Anne said:

The benefits have to be concrete, not speculative, and cannot depend on as-of-yet unrealized downstream inventions.

ok

Adrian said:

Otherwise, can you identify how you think a new element / type might help other users (that are not strictly visual affordances an author could do or undo on their own)?

Helpfulness that I was thinking of would be in that software/plugins could make visual affordances that could be consistent across websites, rather than different everywhere.

But to @annevk's point that is very much not concrete and would require implementation work beyond browsers (except maybe for browser reader mode use case, that's in a browser).

Maybe a comparable case is WCAG's 1.3.5; some also cited personalisation/COGA as the main reason for including it (see John Foliot's reply in this thread. But that too is (arguably) speculative. If speculative is outside of scope here, please do ignore my comment above.

[LeaVerou]

@aardrian

This was opened with assertions conveyed from an IRL conversation, but not everyone in that conversation has weighed in with all the potential scenarios / benefits they discussed. That might be useful.

I’ve already pinged @matatk to weigh in, though not sure what his availability is.

---

Re: concrete benefits (beyond what @hidde mentioned, which I agree with):

1. Even if we do conclude that the ARIA roles are the same as what other elements are mapped to, the fact that the UA knows that this is a callout and not a generic section means it can announce the callout label (e.g. "Note", "Warning" etc) in a way that makes it easier to navigate content (I'll let the a11y experts weigh in on what that would be) without the author having to do the heavy lifting to make that happen.
2. The point about future inventions was not to justify the value proposition of <callout>, but as an additional benefit: that IF said future inventions happen, all <callout>s on the web can be automatically upgraded at once.

[matatk]

Hello everyone :-). Thanks @LeaVerou for the ping, and starting this discussion.

Regarding calling out the callout to assistive technology, I think it's important to demarcate the bounds of the note, so some sort of role is appropriate. However, a document structuring role (such as note or article) that doesn't create a landmark region would be best. Because the callout is an integral part of the text in which it lives, it shouldn't be a separate landmark region, but having the ability to skip over/between them does sound useful. If a document had many notes, and they used landmark roles, that would put a lot of noise into the landmark structure and navigation, as @scottaohara mentioned. Hopefully this helps to answer @domenic's comment on roles.

I wasn't able to find any current info on how well role=note is supported by AT—and it'll be a little while before I could do any serious testing, but maybe others on this thread have.

I'm wondering if we'd want to do anything to indicate the relative importance of the note—e.g. do we want to distinguish between warnings and notes, for example? I imagine that the ARIA WG has discussed this, when they created the note role—we should check out what was discussed there. Also I think @scottaohara's comment about having potentially two elements expands on this.

I also think we should carefully consider @patrickhlauke's point, that there are a lot of ways notes etc. are used, and we should be able to demonstrate that we're making an improvement in a large number of those use cases, particularly for AT users. Maybe we can do some querying of the HTTP Archive to check on common patterns?

tl;dr of my thoughts for now...

• This feels like a neat addition (somewhat in the spirit of HTML5 elements that provide implicit landmarks). We'll need to enumerate and get consensus on some key use cases, and the accessibility benefits. I also wonder if it's something that has come up in OpenUI's developer surveys as a possible area for improving consistency.

• I like @hidde's idea about affording consistent signposting/rendering of certain constructs across sites—in the APA WG's Adapt TF, we are working on a couple of different projects that do this in other areas (one is about bringing AAC symbols to web content—using the symbols set the user knows, and the other is about making navigation around sites easier, by making it more consistent).

• It seems like we have already talked about notes, tips, warnings, and maybe other things. We should check out ARIA WG's past discussions on this (which I'm sure must've happened, and resulted in role=note).

• My feeling is that we should steer clear of potentially overloading landmark regions, or live regions (it feels like there's a risk of confusing DX there), but we should be willing to explore various options. I've not thought too much about type yet, but maybe that is a way to avoid both overloading existing roles, and adding too many new ones.

HTH!

[zcorpan]

• It seems like we have already talked about notes, tips, warnings, and maybe other things. We should check out ARIA WG's past discussions on this (which I'm sure must've happened, and resulted in role=note).

I did some spec archeology for role=note. It was in the ARIA 1.0 First Public Working Draft:

https://www.w3.org/TR/2008/WD-wai-aria-20080806/#note

Before that, it was in the first version of XHTML Role Attribute Module FPWD from 2006:

https://www.w3.org/TR/2006/WD-xhtml-role-20060725/#s_role_module_attributes

Before that, it was in XHTML 2 from 2005 (but not in 2004):

https://www.w3.org/TR/2005/WD-xhtml2-20050527/xhtml2.html#col_Role

I found https://annevankesteren.nl/2005/04/role-attribute which links to https://lists.w3.org/Archives/Public/w3c-wai-ig/2005AprJun/0127 which might be the first public discussion preceding the role attribute and the note role existing in a spec.

I also found this email which is W3C Member-only: https://lists.w3.org/Archives/Member/w3c-html-wg/2005JanMar/0012.html which says that the role attribute was proposed by the accessibility community (but no reference). There's some reference to "TEI, DocBook, Digital Talking Book, and other document vocabularies", but I haven't tried to dig into the making of those vocabularies.

The only discussion in GitHub w3c/aria I could find is https://github.com/w3c/aria/issues/1629 and PR https://github.com/w3c/aria/pull/1639

[scottaohara]

Appreciate you commenting @matatk.

As an FYI, I've requested this be discussed during the next ARIA wg call to gather other thoughts/feedback so I can succinctly report on that. I've been saving further comments to this thread until after that discussion.

[aardrian]

@matatk

I wasn't able to find any current info on how well role=note is supported by AT—and it'll be a little while before I could do any serious testing, but maybe others on this thread have.

I very quickly tested role="note" five different ways across seven browser/SR combos (edited to add macOS & iPadOS): https://cdpn.io/aardrian/debug/YzgjbLO

Desktop

Firefox 122:

• Shows all as "Note" in the accessibility tree.
• Shows an accName only for those using aria-label and aria-labelledby.

with NVDA 2023.3:

• Makes no announcement of region entrance or exit.
• Is not listed in landmarks list.

Chrome 121:

• Shows all as "Note" in the accessibility tree.
• Shows an accName only for those using aria-label and aria-labelledby.

with JAWS 2024:

• Announces "note" when entering and exiting.
• Announces accName only when using aria-label.
• Not exposed in regions list.
• Not navigable as regions.

Edge 121:

• Shows all as "Note" in the accessibility tree.
• Shows an accName only for those using aria-label and aria-labelledby.

with Narrator Win11 23H2:

• Makes no announcement of region entrance or exit unless labeled via aria-label.
• Announces accName only when using aria-label.
• Not exposed in landmarks list.
• Not navigable as landmarks.

Safari 17.3:

• Shows all as "Note" in the accessibility tree.
• Shows an accName only for those using aria-label and aria-labelledby.

with VoiceOver / macOS 14.3:

• Makes no announcement of region entrance or exit.
• Is not listed in landmarks / regions list.

Mobile:

Chrome 120 with TalkBack 14.1:

• Makes no announcement of region entrance or exit unless labeled via aria-label.
• Announces accName only when using aria-label.
• Not navigable as landmarks.

Firefox 121 with TalkBack 14.1:

• Makes no announcement of region entrance or exit.
• Announces no accName.
• Not navigable as landmarks.

Safari / iPadOS 17.3 with VoiceOver:

• Makes no announcement of region entrance or exit.
• Announces no accName.
• Not navigable.

[zcorpan]

Thanks @aardrian! So if I understand correctly, only JAWS does something interesting for unlabelled role=note:

Announces "note" when entering and exiting.

Is this useful? What is ideal?

OP says it's important for SR users to know where the callout ends.

Would it be good for other kinds of callouts (e.g. tips, warnings, cautions) to be announced as "Note", or should those be separate (new) roles?

[scottaohara]

We only briefly discussed this in the ARIA wg yesterday. Ran out of time.

Only going to comment at this point that all the mentioned types are not appropriate for role=note. Notes/tips/examples would be fine under that single role though.

[aardrian]

@zcorpan

only JAWS does something interesting for unlabelled role=note

Does something, yes. Whether or not users consider that helpful or interesting is a different story.

Is this useful? What is ideal?

No idea. Depends on context.

OP says it's important for SR users to know where the callout ends.

I don't agree with that as a blanket statement, since context is critical. Maybe start this conversation with how regions are exposed (using accNames) so there is some parity.

Would it be good for other kinds of callouts (e.g. tips, warnings, cautions) to be announced as "Note", or should those be separate (new) roles?

IMO, probably not. Partly because those are so broad that I think they may map to existing roles -- depending on context.

Scott answered while I was typing. I would like the ARIA WG to have a chance to mull this.

[toastal]

@aardrian

Seeing this construct in print as a sighted reader is often confusing to me because sometimes it is redundant with the content (a visual flair to repeat a particular statement), sometimes a parenthetical thought, sometimes a de facto footnote, and so on.

Sounds like you are talking about a pullquote, not a callout

[toastal]

Is there room to include something like what I called <cot> for callout out title that fits in the realm of <label>, <caption>, <figcaption>, <summary>? This feels like a meta element that is required to constructor (or override) a “proper” callout. I think it could be nice if one could skip it & the user agent (UA) could provide a nice default title/label/caption, but it would seem odd to not visually see one. …Or is the proposed idea to purely use some role, type, kind attribute & only let the UA decide how to display it? EDIT: I see it’s all proposed as attributes after re-reading, but that would not allow sub elements if needed (strong, ruby, etc.) which I suppose is worth discussing if that should be something that is allowed or not.

As a largely-able-body user of TUI browser & browser reader modes, allowing a user agent to give me a nice user experience help in these environments as well where existing <div>-based (or <table>, or often-semantically-incorrectly <aside>, or always-semantically-incorrectly <blockquote>) solutions can’t provide since <div>s have no semantic meaning. It can be hard to catch a callout actually being, well, called out if it looks like the rest of the body.

(Also, are there any avenues for public discussion that don’t involve proprietary Microsoft GitHub software? I would like to participate as I’ve been called out under “Prior art”, but I don’t enjoy the lack of freedom/privacy on this platform)

[aardrian]

@toastal

Sounds like you are talking about a pullquote, not a callout

Mostly I was acknowledging that OP cited her book for analogous patterns. Since I have not read that book and therefore lack that context, I spoke about more generalized patterns I have seen in print instead (one of which would indeed be a pull quote).

[LeaVerou]

@toastal

Sounds like you are talking about a pullquote, not a callout

Mostly I was acknowledging that OP cited her book for analogous patterns. Since I have not read that book and therefore lack that context, I spoke about more generalized patterns I have seen in print instead (one of which would indeed be a pull quote).

Fair enough, I just updated the comment to include a picture.

[LeaVerou]

@toastal wrt <cot> I think we should figure out the proper semantics of the element first. Also note:

For things that require formatting, where an attribute is not sufficient, authors can use the label slot directly.

[toastal]

Ah, it was the term ‘slot’ that threw me off. When I was pitching ideas, I wasn’t sure how locked-in certain elements/attributes were to their current context (<label> for form elements, type for inputs).

[aardrian]

@LeaVerou

Fair enough, I just updated the https://github.com/whatwg/html/issues/10100#issuecomment-1924338192 to include a picture.

Thanks!

Cited image: A book open to pages 56 and 57, in chapter 2 "Backgrounds & Borders." The two pages broadly discuss and demonstrate CSS to make tiling background patterns. One of the pages is mostly taken up by a white-on-black block that discusses future support and code for conic gradients in CSS.

IMO, that is an <aside> in HTML and a complementary landmark role in ARIA. I don't see how that example would warrant a new element or role in HTML/ARIA.

[LeaVerou]

@aardrian

Cited image: A book open to pages 56 and 57, in chapter 2 "Backgrounds & Borders." The two pages broadly discuss and demonstrate CSS to make tiling background patterns. One of the pages is mostly taken up by a white-on-black block that discusses future support and code for conic gradients in CSS.

Thanks! Updated the comment with that much better alt text 😄

IMO, that is an <aside> in HTML and a complementary landmark role in ARIA. I don't see how that example would warrant a new element or role in HTML/ARIA.

Fair enough, I will try to unearth some of the other custom callouts I have seen over the years. It is also entirely possible we find that the cost-benefit of supporting custom callouts is not worth it, and we decide to focus on the predefined ones (in which case it may be preferable to spec these as separate elements, e.g. <note>, <tip>, <warning> etc.).

[jimmyfrasche]

The O'Reilly books provide nice examples of more or less what I've been picturing in my head

(I am not a photographer, sorry)

[patrickhlauke]

The O'Reilly books provide nice examples of more or less what I've been picturing in my head

so "A Brief Aside" / sidebars would use the <aside> element

W3C documents have examples of notes - they're not strictly asides, they fall within the logical flow of their parent content, but are intended to catch the reader's attention / indicate importance

https://www.w3.org/TR/WCAG22/#audio-control

Similarly, Bootstrap uses coloured blocks/notes to draw attention to something in most cases, rather than mentioning something in passing/as an aside.

https://getbootstrap.com/docs/5.3/components/navs-tabs/#base-nav

As the semantic distinction between a "note" and a "warning" or similar seems fairly difficult to pin down, I'd be in favour of at least exploring the possibility of a <note> element that maps to role="note", and which is differentiated from <aside> by the fact that it's not wrapping around ... well ... a related but distinct piece of side content, but content that is in fact part of the regular content flow, but "highlighted" to draw attention to an important point.

[toastal]

MkDocs (not an endorsement) https://squidfunk.github.io/mkdocs-material/reference/admonitions/ has some atypical additions question, success, failure, example, bug. I think abstract & quote are more obviously ill-suited, but the rest I could see arguments for & against whether these semantically are callout or more emphasis is on visual harmony than semantics. Is there still value in allowing this visual representation—especially when one has access to say role=complementary. Related: is it inevitable that folks will start using the element ‘incorrectly’ or ‘unsemantically’ (as many have seen already with

&

) as user agent support would give you a nice-looking titled box & is there a way to prevent and/or accommodate for such usage even if usage is unsemantic (e.g. custom types are not role=note, etc.) -- toastal ไข่ดาว | https://toast.al PGP: 7944 74b7 d236 dab9 c9ef e7f9 5cce 6f14 66d4 7c9e

[scottaohara]

At this time the ARIA wg thinks the scope of this proposal is too broad. Though these types of callouts are all similarly styled, it does not mean they are semantically equivalent. For those diverging semantics, many of the proposed types could be handled just fine by current HTML elements (e.g., a named section, or aside) or by using a role=[appropriate role here] on a container element. Sometimes, it may even be desired to have the container map to generic as the importance of the content could surfaced via a heading, and the start of a new section of content (via its own heading) would be sufficient to indicate to a user that the prior section (callout) has ended.

It was understood that a type could arguably change the semantics to match the use case, but this didn't do much to change the group's trepidation to the element. Even the idea of adding a specific <note> element had mixed support, leanings towards worry it could be misunderstood to be used for all the use cases this proposal was trying to cover.

Here are the minutes from the aria call. Not everything said was captured in the minutes, hence my general summary in this comment.

We acknowledge the issue that this proposal was trying to take care of (people styling divs rather than providing meaningful semantics for their content), but it seems more of an issue that authors are not using the tools already available to them.

[ggrossetie]

but it seems more of an issue that authors are not using the tools already available to them.

Could you please expand on that? As mentioned by Lea Verou, it seems that there is no consensus on the best way to catch the reader's attention / indicate importance using existing tools.

Are you suggesting that https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/note_role is enough?

<div role="note" aria-labelledby="note-label">
  <strong id="note-label">Important</strong>
  <p>While werewolves are hardy community members, keep in mind the following dietary concerns:</p>
  <ol>
    <li>They are allergic to cinnamon.</li>
    <li>More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.</li>
    <li>Celery makes them sad.</li>
  </ol>
</div>

[toastal]

Would be nice if a unique ID for the whole document wasn’t required for every callout title. These can be a pain to generate & I don’t think you can reference relatively, no?

[LeaVerou]

Would be nice if a unique ID for the whole document wasn’t required for every callout title. These can be a pain to generate & I don’t think you can reference relatively, no?

That is a general problem with ARIA. I have a few ideas on how it could be solved, but not sure there's desire to evolve that part of the web platform.

[scottaohara]

@ggrossetie it's been mentioned multiple times in this thread that the different types proposed fall into different existing semantics (either HTML elements or ARIA roles). Per your assumption that i was saying role=note was enough, i specifically mentioned that was not the case.

@toastal, that's assuming every callout needs to be named, and particularly for notes, that may not be the case. For instance, unless there is a specific visible heading/label, a note wouldn't benefit from a name. And generically naming it as a note would result in its name and role being duplicative of each other. For other cases, like exposing important notifications (alerts, warnings, other important info) then yah, you could name a section and thus get it to expose the region landmark. If IDs are a bother, then you could always just use aria-label - often times these messages don't even have a visible heading/label, so that's what a lot of people would probably do anyway. You could also set it via JS el.ariaLabel = 'foo' or use a querySelector to target the element you want to get the name from and then get its textContent.

As an FYI, there are some other efforts in ARIA to retrieve name from encapsulation, rather than needing specific IDs for certain roles. But it's easier said than done (and also off topic for this thread).

@LeaVerou you can always bring those ideas to ARIA so they can be discussed.

[ggrossetie]

@scottaohara I understand that, but the WG ARIA seems to suggest that there are already tools to manage the different types of callouts. I wanted to have concrete examples. For a note, an example, or a tip, is the structure I proposed semantically correct/recommended? And what is the semantic difference between a note and an important callout? In both cases, the author emphasizes a specific point. The qualifier important might be "subjective"; it's a note that the author considers important or more important than a classic note.

For other cases, like exposing important notifications

In my opinion, a notification and a callout are not the same. A notification is a short-lived, contextual information generally in response to a user action. It's also not closely related to the content since notification are often displayed as a popover on a corner of the screen. I guess <aside> is already good enough for notifications.

[aardrian]

@ggrossetie He provided at least 5 concrete methods. It's impossible to know what maps to the ideas in your head unless you have examples and their surrounding context.

And what is the semantic difference between a note and an important callout?

A note is exposed to users as I documented above (what your refer to as semantics and which mostly impacts only SR users). I still have no clarity what qualifies as a "callout" other than print media examples and references to some libraries. So your question is impossible to answer owing to the apples / oranges comparison.

This issue is, IMO, slowly turning into tech support for existing HTML and ARIA. If you can pull together a series of concrete examples then perhaps this is a discussion (not issue) to raise with the ARIA WG. If nothing else, it could be useful for others struggling with how to map what already exists.

[patrickhlauke]

A notification is a short-lived, contextual information generally in response to a user action.

We're getting to the usual problem of the vagueness and overlap of language and terminology here, I fear (and yes, for dynamic notifications, we're probably thinking more along the lines of role="alert", role="status", and similar ... but I think in this discussion here, we're thinking more about static scenarios)

[ggrossetie]

If you can pull together a series of concrete examples then perhaps this is a discussion (not issue) to raise with the ARIA WG. If nothing else, it could be useful for others struggling with how to map what already exists.

I can provide a series of concrete examples. In fact, there are many examples in the wild: Wikipedia, MDN, specifications (WebGL, WHATWG, AsciiDoc...), books written with DocBook (when admonitions are used)... What is the recommended channel?

[aardrian]

@ggrossetie ARIA WG discussion (not issue): https://github.com/w3c/aria/discussions

[LeaVerou]

@scottaohara

@LeaVerou you can always bring those ideas to ARIA so they can be discussed.

I started writing this as an ARIA proposal, then ended up posting it here, as the problem applies more generally to HTML and I don't think it would be a good path to come up with an ARIA-specific solution: https://github.com/whatwg/html/issues/10143 If you think there's value in me cross-posting it to https://github.com/w3c/aria, I'd be happy to do so.

@aardrian

This issue is, IMO, slowly turning into tech support for existing HTML and ARIA.

That’s …the wrong attitude. 😕 From a UI design point of view, if users keep struggling to use an interface properly, the fault lies with the interface, not the users. If nearly everyone on the web is getting callouts wrong, the solution is not to wiggle a finger at them telling them to get it right dammit, it's to simplify the syntax so they can get it right without too much knowledge/effort.

[aardrian]

@LeaVerou

That’s …the wrong attitude. 😕

I was responding to the request for an explanation of the differences in semantics. Which is why I redirected to an ARIA WG discussion because, counter to your earlier suggestion, there is indeed "desire to evolve that part of the web platform." It just needs participation and a willingness to understand how it is already exposed and what that means for users.

From a UI design point of view, if users keep struggling to use an interface properly, the fault lies with the interface, not the users.

Authors. If authors are struggling to fit their mental model into something that will make sense for users (the people consuming the web content authors create), then yes, better documentation, revised specs, and so on can help. Part of why I suggested moving the convo for those specific cases they cited.

If nearly everyone on the web is getting callouts wrong, the solution is not to wiggle a finger at them telling them to get it right dammit, it's to simplify the syntax so they can get it right without too much knowledge/effort.

I don't think I did that? I was trying to keep this thread from being an ARIA / AAPI explainer is all. But if that is the perception then I am happy to step back. I have no interest in wasting anyone's time.