Types of informational boxes (such as "Note" and "Warning")

MDN
#1

Currently we really only have two types of informational box: “Note” and “Warning”. I don’t think this is really adequate or useful.

I would like to see us expand this to provide more options. Not everything of importance that needs to be made to stand out visually is a warning, per se, and not everything you want to make easy to spot is a note.

To that end, I would like to discuss the possibility of making available some additional box types:

  • a11y-warning: A warning box specifically about accessibility issues. Things like “Using this attribute can confuse users of screen reading devices,” for instance, would be in this category.
  • a11y-tip: A recommendation for an accessibility best practice or a way to make something easier for specific groups of users.
  • tip: A best practice or recommendation, or a suggested approach to solving a problem.
  • xref: Advice to refer to other content, such as “See foo for a list of accepted values.”

There are almost certainly a few others we should consider as well.

These should all be able to be pulled to the side using the pull-aside class.

#2

I like the idea of making our callout boxes more informative, but I think we need to think carefully about what we want to add. Some comments:

  • I like the idea of having new types of “tip” to cover tips or best practices, and “xref” to call out links to important supplementary information.
  • I like the idea of pulling them to the side; I think it would make them stand out better, and make the page more interesting.
  • I don’t think we need “a11y-warning” and “ally-tip” as separate classes. I think instead we need to think about this in a more modular way:
    • class names for types of box, i.e. note|warning|tip
    • class names for topic it is related to, i.e. a11y|security|privacy|perf
    • We can then combine classes to produce the desired visual, e.g. class=“tip a11y”
  • We need to think about how this would tie in with the idea we discussed about having Accessibility|Privacy|Security|Performance concerns sections on MDN pages in a more formal way, extending what Eric Bailey started with the Accessibility concerns. Estelle is currently working up a plan about this.
#3

Oh absolutely. I was really describing it more from the user experience perspective than the under-the-hood classes, although that wasn’t clear from how I wrote it and used labels that admittedly looked like class names.

I think if we had an urgency level (tip, note, warning, and maybe even a “fun fact” level) and a category like you suggest (a11y, security, privacy, performance, errors, and possibly others like code-readability), that would be the way to go.

We could probably find a way to put together a tool or script that finds all pages that include at least one block styled in a way that matches a given set of these and either lists out links to the pages or provides a page name and the contents of the block, to let us create "Security concerns in " section or whatever. Could make for an interesting experiment at some point.

#4

Yup, all sounds interesting. I’m not sure as to whether this is hugely high priority, but I am interested from the outset.

1 Like
#5

I’ve just joined MDN and interested in developing the security related aspects. I realise this thread hasn’t been active for some time but wonder if there is chat still ongoing elsewhere?