Integration with spec authoring tools (Bikeshed, ReSpec)

[tidoust]

Raised by @tabatkins during TPAC 2024's breakout on Web features: Bikeshed currently has a mechanism to include MDN panels and Can I Use panels. Down the road, this could be replaced, or completed, with a way to reference web-features, leveraging spec URLs and/or links to BCD keys.

Integration with spec authoring tools seems something worth thinking about from a web-features perspective. Creating this issue to discuss and track progress.

[tabatkins]

Here's how Bikeshed currently integrates with MDN and CanIUse:

MDN

• I automatically (and current unconfigurably) look for shortname.json or shortname-N.json among the MDN data files.
• Each feature has an associated deep link; I take the fragment from there and attach the MDN panel to the element with that ID.

CanIUse

• CanIUse doesn't consistently have deep links into specs, but it does contain spec URLs of some sort.
• You can explicitly tag an element with the CanIUse token corresponding to a feature, to attach the CanIUse panel to it.
• You can register a URL prefix to be informed about what CanIUse tokens exist with that URL prefix (but still have to explicitly attach those tokens).

---

It looks like I can get a nice best-of-both worlds hybrid with web-features. Each feature has both a deep spec link and a unique token.

So my plan, I think, would be:

• You can register a URL prefix, which'll automatically include all features matching that prefix.
• Those feature panels will be attached to the element with the matching fragment ID.
• You can also explicitly tag an element with a web-features token and get the corresponding feature panel attached to it.
• If you use a URL prefix and give the explicit token for one of those features, it'll override the fragment-based attachment.

Aka, something like:

<pre class=metadata>
...
Include Web Features Panels: https://drafts.csswg.org/css-backgrounds
</pre>

<h3 id=background-clip>
Painting Area: the 'background-clip' property</h3>
...
<dl dfn-type-value dfn-for=background-clip>
  <dt><dfn webfeature="css.properties.background-clip.text">text</dfn>

With this, you'd automatically get the css.properties.background-clip feature panels attached to the heading, since it has a matching URL. The background-clip:text features uses the same URL, tho, so this explicitly attaches that panel to the text definition. (If you didn't do this, then because they're both attached to the header, it'll just put both features into the same panel.)