We need a better stylesheet for margin annotations

[domenic]

We are growing an increasing number of margin annotations on our specs. HTML is leading the way, but others are following.

Types of annotations

Caniuse boxes

Although perhaps soon to be obsoleted by MDN boxes (see below), we have this in HTML right now: see e.g. https://html.spec.whatwg.org/multipage/workers.html#navigator.hardwareconcurrency

Fingerprinting annotations

Again see https://html.spec.whatwg.org/multipage/workers.html#navigator.hardwareconcurrency . Currently only in HTML, although there were attempts to generalize in whatwg/infra#115.

MDN boxes

Coming to HTML in whatwg/html-build#184. See e.g. https://arcane-cove-57093.herokuapp.com/multipage/workers.html#the-workerglobalscope-common-interface . Currently only in HTML, but I believe @sideshowbarker is working with @tabatkins on bring it to Bikeshed in general

Web platform test annotations

Coming to HTML in whatwg/wattsi#90. I haven't seen the styles in action successfully, but judging by whatwg/whatwg.org#230 the intent is a purple-ish box in the margin. @zcorpan is already using the Bikeshed version in e.g. https://quirks.spec.whatwg.org/#the-hashless-hex-color-quirk, where it is full-width (not a margin annotation). I like the margin annotation version.

Goals

It would be nice to design our markup/stylesheets with the following in mind:

• Consistency. I think these should all look and behave roughly the same, with the same width (or just max-width?), background color, borders, collapsibility-or-not. Ideally this extends under the surface too, e.g. all of them using <aside>, but that's less important.

• Non-overlapping. Ideally these should not overlap the content of the spec, or overlap each other. At least in their default mode; perhaps when expanded overlapping is OK.

• Mobile-friendly. On mobile the caniuse boxes already look back, and it just gets worse the more we add. What is a good solution here?

Proposal

A rough sketch of a proposal:

• Pick a max-width for desktop-size screens. Probably somewhere between the caniuse boxes' 144px, and something that accomodates larger MDN titles. Constrain everything to this max width; unbounded content like MDN article titles or test filenames get cut off with an ellipsis via that CSS property.
• Add that max-width as a gutter to the desktop stylesheet. Until you hit the mobile breakpoint, that space should always be available.
• Use float: right, instead of absolute positioning, so that when there are many of these things together, they stack instead of overlap each other.
• On desktop, these things don't need to be collapsible.
• On mobile, have a much smaller gutter and max-width, e.g. 10px. This just shows e.g. "MDN" or "WPT" or "CIU". But clicking expands them to the left, to cover the content.

I'd welcome thoughts on the above.

To get from here to the above, I'd suggest:

• We figure out if we're keeping caniuse boxes or not. If not, we can remove them and simplify future steps.
• We land MDN boxes and WPT annotations in HTML, using good-enough-if-not-perfect markup/CSS. My comments on those PRs are only about unblocking their landing, not about this larger alignment project.
• We figure out if we want to coordinate alignment of all the markup structure, e.g. putting everything in an <aside>. This would probably require Bikeshed changes. Keep existing styles while doing so.
• Now implement the above proposal, which will be mostly CSS but may require some JS for mobile expand/collapse. (Or we could just use <details>, which is available on all mobile browsers... hmm.)

[tabatkins]

Another thing to think about - W3C uses that same margin gutter, but entirely for its sidebar ToC. Is this something WHATWG will ever want to do? I've come to appreciate and depend on having the ToC around at all times; I often get annoyed that I have to scroll back to the top of a WHATWG document just to navigate elsewhere.

It feels like you have to decide between a margin-ToC and other marginalia.