Rendering as a <div> gives this element no semantics.
I’m not sure why this is listed as a con. If there is no existing element with the correct semantics, then neutral semantics is the best you can do. No thing is better than the wrong thing.
Overall though, I think the proposed <callout> element is a good idea and solves a real problem.
That’s a understandable perspective. It’s better to have no semantics compared to the wrong semantics. Ideally, I want to see an element with semantic meaning, so that’s how I see it as a con.
Overall though, I think the proposed element is a good idea and solves a real problem.
Is there any real reason we can’t do something like <div semantics="callout"> ? Things that don’t understand it can treat it like a div, and things that do understand it can do something special with it.
Without standardization like the <details> element, user agents can’t make assumptions about what that attribute means. As such It would be foolish to render every <div class="note"> as a callout. With a full proposal with implied semantics, user agents could give us a nice user experience without the burden of CSS (or with the ability to more easily style it).
I’d suggest looking into the doc-notice, doc-tip, and doc-exampleDPUB-ARIA roles. I’m a big fan of DPUB-ARIA and I do not think it is used enough. I believe Google’s Talkback has the most robust support for it put of any AT I’m familiar with.
I’m not convinced that a cot element is necessary. I think a heading with aria-labelledby would work better as a way to name a callout, and an attribute (or DPUB-ARIA role) could better specify the type of callout.
Funnily enough, I’m thinking about my own proposal for a spoiler element which also has similar structure to—but different semantics from—the details element.
I’d never heard of DPUB-ARIA. That might be a better route that HTML microdata.
The labledby attribute needs a unique ID to work tho, no? I’d also be concerned about ordering it the element in any fashion other than the first element (like <summary>) but obviously axing an element would make it simpler. Not sure…
The labledby attribute needs a unique ID to work tho, no?
Yes, it does. But this does feel more like a heading, semantically speaking.
I’d also be concerned about ordering it the element in any fashion other than the first element
summary is just a button with no other semantics, and has UI-related reasons to come first: you can’t put a toggle after some of the content being toggled without things getting messy.
aria-label works too; I just naturally prefer labelledby for a number of reasons.
I have a bad habit of skipping the label because it’s a pain to create & keep track of a pile of unique IDs just for the sake of bookkeeping for ARIA… I wish you could specify a selector relative to the parent :(. Would this mean I’d now need another tool going over my markup to create GUIDs? This is the biggest reason I like having a specific element inside like <summary> is to <details> and <legend> is to <fieldset> because it remove a lot of the noise of ID soup. I understand that it would just be a plaintext element & a stretch to suggest two elements, but as an HTML writer I’d be happier to use due to ergonomics. Are these ergonomics for writing rarely considered since usually documents are consumed not read? (I honestly don’t know the practice)
The thing where using ARIA well requires unique IDs is a huge pain point, and it’s not clear to me that the spec authors are aware of how annoying this is for people making non-trivial webpages. At this point, I have my workarounds in place, but it would be nice if there was someone at the standard bodies working on it.
When using custom HTML elements, you should include a hyphen somewhere in the name to avoid the mentioned problem of colliding with new standard elements.
The customElements.define method throws an error if you try to define a custom element without a hyphen.
TBH, I think the thing where people do cutesy stuff like “call-out” is a mistake. There is only a single global namespace for custom elements, so you shouldn’t reserve a name based on a real word. You should make the first part a unique namespace, and then the second part is the actual name of the element. In this case, it would be “toastal-callout”, but as I argue elsewhere in this comments section, it doesn’t really make sense to “prototype” with a custom element here. The point is to go to the standard bodies and nail down semantics for the element. Otherwise, it’s not better than just having <div class="callout">.
Posted it on the asciidoctor issue and copying it here as well:
I feel like blockquote and aria-hidden="true" (for both screen readers and tui browsers) is the “right” answer here. Quoting MDN (emphasis mine):
Adding aria-hidden=“true” to an element removes that element and all of its children from the accessibility tree. This can improve the experience for assistive technology users by hiding:
Purely decorative content, such as icons or images
Are you referring to, like, decorative pull-quotes that repeat content in the body? If we’re pushing the spec, <blockquote> is supposed to come from a different source which would lessen the likelihood of duplication.
Forgive the off-topic question, but I couldn’t find an answer on the site itself. Why is the “th” digraph represented as ð in some places and þ in others?
ð is the ‘th’ in the, this, that, other (voiced dental fricative)
þ is the ‘th’ in both, thing, thought, three (voiceless dental fricative)
Historically English used both symbols interchangeably, but most words (that aren’t “with”) don’t use the sounds interchangeably. This setup is also how Icelandic uses Ð & Þ. If English were to reintroduce these symbols (personally in favor), I would prefer seeing this setup as it disambiguates the sounds for ESL speakers/readers and gives English a strong typographic identity (think how ñ makes you immediately think Spanish) for one of it’s unique characteristics: using dental fricatives.
Noteworthy: English has words like Thailand, Thomas, Thames that have ‘th’ that aren’t dental fricatives which helps disambiguate those as well before we get another US president saying “Thighland” based on spelling.
Additionally ‘ð’ on its own is “the” allowing the definite article to have a single-symbol representation like the indefinite article “a”. (I made this up, but I like the symmetry).
A more historically authentic way to compress “the” into a single column would be to put the “e” atop the “th”-symbol… although I don’t know that that would render legibly on an eth, as opposed to overlying the eth’s ascender.
Yes. 😅 Historically “&” was a part of the alphabet, but throwing even more symbols onto a keyboard makes less sense if it can be helped. I suppose a twin-barred “ð” could work, but at smaller resolutions, good luck. I would still value ð being the base tho, since it is voiced & I think following the ð/þ has more benefit than choosing þ to have both voiced & voiceless sounds.
If curious, you can try to read that linked post where the whole content uses ð & þ. It doesn’t take long for it to ‘click’ & personally I think it reads smoothly, but for a broad audience (which that post is not), I wouldn’t put such a burden on the copy. But around the periphery & in personal stuff, I don’t mind being the change I would like to see.
I now have a slightly ridiculous desire to build a “shadow page” into my in-progress site generator that rewrites English to use this so that every post has a version available in this mode. It is surprisingly delightful!
It could get tricky maintaining because you’d it’s not as simple as s/th/þ/g. I’m actually a bit surprised someone enjoyed let alone preferred reading like that. I figured most would be annoyed.
Yeah, the fun part would be building some actual understanding of the underlying language issues. The dumb-but-probably-actually-works version is just a regex over words, where you can add to it over time. The smarter version would actually use some kind of stronger language-aware approach that actually has the relevant linguistic tokens attached. Fun either way!
(I suspect the number of people who appreciate this is indeed nearly zero, but… I and three of my friends are the kind of people to love it. 😂)
In modern English, th has two different sounds (think vs this) but before that we used proper letters to distinguish those two sounds. It would be þink and ðis if we still used them.
What’s the thinking behind having both a kind attribute and a <cot> element? They seem redundant to me.
Specifically, the attribute has a vibe like “this value should be one of the predefined values from the list,” and the element feels very free-form. I know you explicitly specified that the kind can be anything, but this is the feeling I get from the fact that it’s an attribute and hence contains only “plain” text. The web is all about flexibility and people pushing the boundaries, so I suspect that in practice people would use <cot> far more than kind.
You might argue that setting an attribute value allows you to apply different CSS to tips, notes, warnings, etc., but I would point out that that usage seems redundant with the more general class attribute, which is already also supported on <callout>. If your idea was that the kind could be used by browsers to apply a certain default style to warnings, another style to tips, and so on, then that might make sense. In general I think this proposal would be strengthened if you included a concrete example of the user-agent CSS that browsers might use to render <callout> and <cot> and the various kinds.
The <cot> & kind should be seen as not redundant the moment we switch the document into a non-English language where the title text probably will no longer match. While classes would still work for styling, I can’t think of a scenario where the user agent changed its default rendering based on a class (might even go against a spec). Yes as you noted, I would prefer it if a user agent could change color or maybe ::marker to match a certain list of kinds—as you might see the functionality of <input type="text"> render and behave different to <input type="number">. I also mentioned that a kindcould set an implied <cot> based on locale, but I feel it should be overridable (hence the element)—but that could get complicated.
More examples would be nice, but that could get tedious, clash with the site styles, and importantly would require all the research into comparison of the visual output of callouts which is even more varied than the markup options.
Then the user agent is free to strip the element as it is “complementary” content. Most callouts aren’t complementary, but warnings or other notes directly related.
Sorry that wasn’t worded right & I was out at lunch.
As noted in the post, <aside> elements have an implicit complementary role which means that content needs to be standalone (not stripped out).
complementary role
A landmark that is designed to be complementary to the main content that it is a sibling to, or a direct descendant of. The contents of a complementary landmark would be expected to remain meaningful if it were to be separated from the main content it is relevant to.
There are various types of content that would appropriately have this role. For example, in the case of a portal, this can include but not be limited to show times, current weather, related articles, or stocks to watch. If the complementary content is completely separable from the main content, it might be appropriate to use a more general role.
With the exception of some ‘tips’, a callout is rarely standalone & not like “show times, current weather, related articles, or stocks to watch”. A callout is something directly related to the body copy of the article and thus isn’t suited for an <aside>. I also mentioned this reasoning in Asciidoctor’s issue tracker which has caused moving forward with <aside> to halt while considering a possibly better option.
You should define what a callout is or link to a definition.
How is it different from an , a , an or a . Is it a box? A speech bubble? Does it need an icon? Does it need a border? Can it be ignored and the text inlined or does that destroy the text for example because it now repeats something?
Was the opening three sentences of the abstract not sufficient?
As the name may imply, callouts (sometimes called “admonitions”) call out a specific text from the content.
They are meant to draw priority attention to specific text.
Often you see accompanying labels such as: tip, note, attention, warning, caution, danger, important.
How you design is up to a lot of room for interpretation & there isn’t a standard per se other than something box-like with a one-word label/title and body text. Icons could be done via ::marker as mentioned, but it doesn’t have to be a requirement. The text itself has a few I my personally-designed callouts without any icons.
Luckily in HTML5, we are allowed to create our own arbitrary elements & attributes to achieve desired results
The html5 parsers may be able to handle this, but please don’t do this. We have a mechanism for extending the data class of an html element, and it’s class. So <div class="callout">
I want the implicit role of note & the ability for reader modes to be able to render it as well as conform to a callout title. Using a <div> will never safely be able to make such assumptions. New elements get proposed, and that’s what I would like to see.
It’s my understanding that by default, unknown elements get treated like divs by user agents (largely HTML5 parsers), in which case, you may as well name you elements something meaningful to yourself (with the explicit role as suggested in the post already) & hope it catches on. Right now I’m trying to dogfood it, because I seriously am interested in making this an RFC with some guidance/collaboration.
Would it make sense to prototype it as an actual custom element instead of a mystery tag? You could even inherit from an element that has some of the properties you want already.
I feel like this is something people miss in the discussion of WC: custom elements do not and cannot have semantics because anyone can define or redefine any tag. At best, it can be like microdata where there is a generally accepted use for a tag and search engines can just assume that’s what it’s being used for. But the whole point of custom elements are that they’re custom, so it makes no sense to try to impose a semantic on them after the fact.
I wholeheartedly agree. But we are talking about prototyping in preparation for proposing a new element. Custom Elements seem like they would be useful for the prototyping part.
What do you think it would be prototyping? Adding a semantic means that screen readers and search engines can understand what a tag means. How does having a customElement help with that? If screen readers and search engines are going to take the time to support something, it should be the actual tag you want. That was the lesson of the experimental CSS -webkit properties that all turned out to be permanent once they were in production.
I wouldn’t be surprised if they have other uses, but the main place I see callouts is in the middle of news articles, where they stick an excerpt of the very article I’m already reading. It’s very obnoxious.
I’m not sure why this is listed as a con. If there is no existing element with the correct semantics, then neutral semantics is the best you can do. No thing is better than the wrong thing.
Overall though, I think the proposed
<callout>element is a good idea and solves a real problem.That’s a understandable perspective. It’s better to have no semantics compared to the wrong semantics. Ideally, I want to see an element with semantic meaning, so that’s how I see it as a con.
Hearing this from even one soul made my day tho!
Is there any real reason we can’t do something like
<div semantics="callout">? Things that don’t understand it can treat it like a div, and things that do understand it can do something special with it.That’s basically what an ARIA role attribute does. It’s a good stop gap, but it’s better to have a real element for the semantic.
Without standardization like the
<details>element, user agents can’t make assumptions about what that attribute means. As such It would be foolish to render every<div class="note">as a callout. With a full proposal with implied semantics, user agents could give us a nice user experience without the burden of CSS (or with the ability to more easily style it).Right, I was suggesting a standardized attribute for it.
Interesting proposal! Some thoughts:
doc-notice,doc-tip, anddoc-exampleDPUB-ARIA roles. I’m a big fan of DPUB-ARIA and I do not think it is used enough. I believe Google’s Talkback has the most robust support for it put of any AT I’m familiar with.cotelement is necessary. I think a heading witharia-labelledbywould work better as a way to name a callout, and an attribute (or DPUB-ARIA role) could better specify the type of callout.Funnily enough, I’m thinking about my own proposal for a
spoilerelement which also has similar structure to—but different semantics from—thedetailselement.Originally posted on https://seirdy.one/notes/2023/08/29/thoughts-on-callout-semantics/ (POSSE).
I’d never heard of DPUB-ARIA. That might be a better route that HTML microdata.
The labledby attribute needs a unique ID to work tho, no? I’d also be concerned about ordering it the element in any fashion other than the first element (like
<summary>) but obviously axing an element would make it simpler. Not sure…Yes, it does. But this does feel more like a heading, semantically speaking.
summaryis just a button with no other semantics, and has UI-related reasons to come first: you can’t put a toggle after some of the content being toggled without things getting messy.aria-labelworks too; I just naturally preferlabelledbyfor a number of reasons.I have a bad habit of skipping the label because it’s a pain to create & keep track of a pile of unique IDs just for the sake of bookkeeping for ARIA… I wish you could specify a selector relative to the parent :(. Would this mean I’d now need another tool going over my markup to create GUIDs? This is the biggest reason I like having a specific element inside like
<summary>is to<details>and<legend>is to<fieldset>because it remove a lot of the noise of ID soup. I understand that it would just be a plaintext element & a stretch to suggest two elements, but as an HTML writer I’d be happier to use due to ergonomics. Are these ergonomics for writing rarely considered since usually documents are consumed not read? (I honestly don’t know the practice)The thing where using ARIA well requires unique IDs is a huge pain point, and it’s not clear to me that the spec authors are aware of how annoying this is for people making non-trivial webpages. At this point, I have my workarounds in place, but it would be nice if there was someone at the standard bodies working on it.
When using custom HTML elements, you should include a hyphen somewhere in the name to avoid the mentioned problem of colliding with new standard elements.
The
customElements.definemethod throws an error if you try to define a custom element without a hyphen.TBH, I think the thing where people do cutesy stuff like “call-out” is a mistake. There is only a single global namespace for custom elements, so you shouldn’t reserve a name based on a real word. You should make the first part a unique namespace, and then the second part is the actual name of the element. In this case, it would be “toastal-callout”, but as I argue elsewhere in this comments section, it doesn’t really make sense to “prototype” with a custom element here. The point is to go to the standard bodies and nail down semantics for the element. Otherwise, it’s not better than just having
<div class="callout">.Posted it on the asciidoctor issue and copying it here as well:
I feel like
blockquoteandaria-hidden="true"(for both screen readers and tui browsers) is the “right” answer here. Quoting MDN (emphasis mine):Are you referring to, like, decorative pull-quotes that repeat content in the body? If we’re pushing the spec,
<blockquote>is supposed to come from a different source which would lessen the likelihood of duplication.Oh crap, I didn’t understand what “call out” meant exactly. My bad.
Words are hard. ;)
Forgive the off-topic question, but I couldn’t find an answer on the site itself. Why is the “th” digraph represented as ð in some places and þ in others?
Noted in: https://toast.al/posts/techlore/2023-07-03_weblog-rebuilt
Historically English used both symbols interchangeably, but most words (that aren’t “with”) don’t use the sounds interchangeably. This setup is also how Icelandic uses Ð & Þ. If English were to reintroduce these symbols (personally in favor), I would prefer seeing this setup as it disambiguates the sounds for ESL speakers/readers and gives English a strong typographic identity (think how ñ makes you immediately think Spanish) for one of it’s unique characteristics: using dental fricatives.
Noteworthy: English has words like Thailand, Thomas, Thames that have ‘th’ that aren’t dental fricatives which helps disambiguate those as well before we get another US president saying “Thighland” based on spelling.
A more historically authentic way to compress “the” into a single column would be to put the “e” atop the “th”-symbol… although I don’t know that that would render legibly on an eth, as opposed to overlying the eth’s ascender.
Yes. 😅 Historically “&” was a part of the alphabet, but throwing even more symbols onto a keyboard makes less sense if it can be helped. I suppose a twin-barred “ð” could work, but at smaller resolutions, good luck. I would still value ð being the base tho, since it is voiced & I think following the ð/þ has more benefit than choosing þ to have both voiced & voiceless sounds.
Very interesting, thank you for the explanation!
If curious, you can try to read that linked post where the whole content uses ð & þ. It doesn’t take long for it to ‘click’ & personally I think it reads smoothly, but for a broad audience (which that post is not), I wouldn’t put such a burden on the copy. But around the periphery & in personal stuff, I don’t mind being the change I would like to see.
I now have a slightly ridiculous desire to build a “shadow page” into my in-progress site generator that rewrites English to use this so that every post has a version available in this mode. It is surprisingly delightful!
It could get tricky maintaining because you’d it’s not as simple as
s/th/þ/g. I’m actually a bit surprised someone enjoyed let alone preferred reading like that. I figured most would be annoyed.You could do it ðe opposite way, where you write content wiþ þorns/eðs and automatically replace ðem wiþ “th”.
Ðat… is very not-dumb way to go about it. :)
Yeah, the fun part would be building some actual understanding of the underlying language issues. The dumb-but-probably-actually-works version is just a regex over words, where you can add to it over time. The smarter version would actually use some kind of stronger language-aware approach that actually has the relevant linguistic tokens attached. Fun either way!
(I suspect the number of people who appreciate this is indeed nearly zero, but… I and three of my friends are the kind of people to love it. 😂)
ð is voiced (“that”) and þ is unvoiced (“thing”). Feel your throat as you pronounce both and you’ll understand the difference.
In modern English, th has two different sounds (think vs this) but before that we used proper letters to distinguish those two sounds. It would be þink and ðis if we still used them.
What’s the thinking behind having both a
kindattribute and a<cot>element? They seem redundant to me.Specifically, the attribute has a vibe like “this value should be one of the predefined values from the list,” and the element feels very free-form. I know you explicitly specified that the
kindcan be anything, but this is the feeling I get from the fact that it’s an attribute and hence contains only “plain” text. The web is all about flexibility and people pushing the boundaries, so I suspect that in practice people would use<cot>far more thankind.You might argue that setting an attribute value allows you to apply different CSS to tips, notes, warnings, etc., but I would point out that that usage seems redundant with the more general
classattribute, which is already also supported on<callout>. If your idea was that thekindcould be used by browsers to apply a certain default style to warnings, another style to tips, and so on, then that might make sense. In general I think this proposal would be strengthened if you included a concrete example of the user-agent CSS that browsers might use to render<callout>and<cot>and the variouskinds.The
<cot>&kindshould be seen as not redundant the moment we switch the document into a non-English language where the title text probably will no longer match. While classes would still work for styling, I can’t think of a scenario where the user agent changed its default rendering based on a class (might even go against a spec). Yes as you noted, I would prefer it if a user agent could change color or maybe::markerto match a certain list of kinds—as you might see the functionality of<input type="text">render and behave different to<input type="number">. I also mentioned that akindcould set an implied<cot>based on locale, but I feel it should be overridable (hence the element)—but that could get complicated.More examples would be nice, but that could get tedious, clash with the site styles, and importantly would require all the research into comparison of the visual output of callouts which is even more varied than the markup options.
I just use
<aside>. “As an aside…”Then the user agent is free to strip the element as it is “complementary” content. Most callouts aren’t complementary, but warnings or other notes directly related.
What user agents actually strip
<aside>s?They display fine, and from what I’ve been told, they screen-read fine. That’s “standard” to me and my readers.
Sorry that wasn’t worded right & I was out at lunch.
As noted in the post,
<aside>elements have an implicit complementary role which means that content needs to be standalone (not stripped out).With the exception of some ‘tips’, a callout is rarely standalone & not like “show times, current weather, related articles, or stocks to watch”. A callout is something directly related to the body copy of the article and thus isn’t suited for an
<aside>. I also mentioned this reasoning in Asciidoctor’s issue tracker which has caused moving forward with<aside>to halt while considering a possibly better option.You should define what a callout is or link to a definition.
How is it different from an , a , an or a . Is it a box? A speech bubble? Does it need an icon? Does it need a border? Can it be ignored and the text inlined or does that destroy the text for example because it now repeats something?
Was the opening three sentences of the abstract not sufficient?
How you design is up to a lot of room for interpretation & there isn’t a standard per se other than something box-like with a one-word label/title and body text. Icons could be done via
::markeras mentioned, but it doesn’t have to be a requirement. The text itself has a few I my personally-designed callouts without any icons.The lobste.rs Markdown ate your tag examples.
I’m interested in this custom blocks proposal, got a link? (It would be nice if you could include it it in your article, by the way.)
https://talk.commonmark.org/t/generic-directives-plugins-syntax/444
I was a bit lazy to find it while writing because the RFC is a little hard to find, but the topic is actually called generic directives.
I updated the post with a link tho now that I found the link!
The html5 parsers may be able to handle this, but please don’t do this. We have a mechanism for extending the data class of an html element, and it’s
class. So<div class="callout">I want the implicit role of
note& the ability for reader modes to be able to render it as well as conform to a callout title. Using a<div>will never safely be able to make such assumptions. New elements get proposed, and that’s what I would like to see.…but it wouldn’t be bad to include a warning.
Nothing can make those assumptions on an unspecified element either, which is why you have to set
roleexplicitly.Sure, if it became part of the spec that would be different of course.
It’s my understanding that by default, unknown elements get treated like divs by user agents (largely HTML5 parsers), in which case, you may as well name you elements something meaningful to yourself (with the explicit role as suggested in the post already) & hope it catches on. Right now I’m trying to dogfood it, because I seriously am interested in making this an RFC with some guidance/collaboration.
(I did add that cautionary note tho)
Would it make sense to prototype it as an actual custom element instead of a mystery tag? You could even inherit from an element that has some of the properties you want already.
I feel like this is something people miss in the discussion of WC: custom elements do not and cannot have semantics because anyone can define or redefine any tag. At best, it can be like microdata where there is a generally accepted use for a tag and search engines can just assume that’s what it’s being used for. But the whole point of custom elements are that they’re custom, so it makes no sense to try to impose a semantic on them after the fact.
I wholeheartedly agree. But we are talking about prototyping in preparation for proposing a new element. Custom Elements seem like they would be useful for the prototyping part.
What do you think it would be prototyping? Adding a semantic means that screen readers and search engines can understand what a tag means. How does having a customElement help with that? If screen readers and search engines are going to take the time to support something, it should be the actual tag you want. That was the lesson of the experimental CSS -webkit properties that all turned out to be permanent once they were in production.
Because he said in his article that he’s prototyping it.
If there’s no semantic to both a div & a custom element, what would be the lost if choosing the custom element name route?
I would love to see such element so that I can tell my browser to ‘callout { display:none; }’ and never have to see them again.
Until it’s for DANGER! And the command you ran deleted your root—they tried to warn ya.
I wouldn’t be surprised if they have other uses, but the main place I see callouts is in the middle of news articles, where they stick an excerpt of the very article I’m already reading. It’s very obnoxious.
I could be wrong about the meaning of “callout” being broader than I though, but I think what you are referring to is a pull-quote.