Notes and Warnings: Style Guidelines

(Eric Shepherd) #1

Back when our .note and .warning styles were just boxes around the enclosed text, we established the standard of starting the contents with “<strong>Note:</strong>” or “<strong>Warning:</strong>”.

Now our styles include an appropriate icon.

Do we still write that text into the content of these boxes, or do we rely on the icon and possibly other style cues? At one point, I thought we had discussed this, but given the various discrepancies that show up, I thought it wise to double-check; it’s not written down anywhere that I can find.

I have been removing the “Note:” and “Warning:” prefixes from the contents of these boxes, since I thought we had decided to do away with these (and they definitely seem to be no longer necessary).

Thoughts? Pointers to decisions contrary to these recollections?


(Chris Mills) #2

I don’t remember a conversation about removing those. In fact, I’ve been adding them in where I see them :wink:

So I think we ought to make a call here. I think I’d be happy either way, but with a slight preference on putting them in, as I think they look neater.

(Sphinx Knight) #3

I’d concur with Chris. I don’t know how accessibility is handled with those classes but I tend to think they’re better written down with the icon :slight_smile:
I don’t have specific explicit pointers to meta doc or existing linting rule though.

(Eric Shepherd) #4

Hm, I could have sworn I posted a follow-up last night but I don’t see it.

The thing is, we could have CSS magic insert “Note:” if we want it to be there, or have it injected for the use of screen readers only, By including it directly in the text, we lose the option to do that, or to have the boxes styled in such a way as to have them formatted with the “Note” label in special positions, like:




Interesting styles like this aren’t as easy if the word “Note” is included in the text. Besides, why write "Note: " in every note if it’s always got to be there? Might as well be automated, no?


(Chris Mills) #5

Fair point.

It wouldn’t be that hard to just change the macro so that it adds it in if it is not already there, and doesn’t if it is. :wink: