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