New principle: Guidance on when to use a child element vs an attribute

[LeaVerou]

Related to: #269

We should add some guidance for people designing HTML elements (both spec writers and web component authors) about when to choose an attribute for metadata vs a specific element type.

Some examples of child elements being used for metadata instead of attributes are:

• <caption> for <table>
• <figcaption> for <figure>
• <legend> for <fieldset>
• <source> for <video>, <audio>, <picture>
• <summary> for <details>
• <title> and <desc> in SVG

I think we should encourage use of child elements over attributes for any text that will be presented to end users. Child elements can include HTML for inline markup, as well as i18n attributes (dir, lang etc).

There are examples in the web platform that violate this guideline:

• <img alt>
• The title attribute
• <input placeholder>
• <input value>
• <optgroup label>

Should these be presented as past design mistakes or should the principle become more granular somehow to accommodate them? E.g. perhaps this doesn't apply to replaced elements? On a related note, this guidance cannot be followed for empty elements, which means it cannot be followed for new global attributes. Should new empty elements be discouraged?

Child elements of a specific type are also a way to annotate elements with metadata of a more complex data structure than text, numbers, or booleans (or short lists thereof, like in the class attribute). Examples of such complex data structures that are already specified via child elements are <source> and <option> which essentially specify lists of objects (in JSON terms).

(I'm fine to send a PR for this once there's consensus about adding the principle and what it should be)

[torgo]

We discussed today and agreed we should pick this up and do something.

[bkardell]

Is this potentially also related to #213 and #218 #298? (note: typo, edited)

[LeaVerou]

Is this potentially also related to #213 and #218?

I don't see how, could you elaborate please?

[bkardell]

Yeah, I debated whether I should have in the first place, sorry.

I ask whether it is potentially related to #213 because very often microsyntaxes are trying to stuff complex structured information into an attribute. Elements allow structure, but are often unappealing or of debatable fit. Seems potentially worth considering them together as you craft advice.

Regarding #298 - there has been a lot of discussion among implementers and feelings about mistakes in the past created. An example of this, potentially, is the type attribute of input. The basis for this is that these types extend regular text input, but the result is that we have a lot of issues created by this approach. Apple engineers, for example, have cited LSP a number of times WRT how they prefer to approach issues like this going forward, with composition over inheritance. An alternative take (not suggesting anyone proposed this) could have been to wrap individual typed input elements around a standard <input> as a decorator, effectively acheving the same but without the same complexities. As we have prior examples in the platform, it again seemed potentially relevant to consider in the same discussion?

[LeaVerou]

From today's breakout:

• We agree that when an attribute value syntax is a novel microsyntax, it should probably be a child element with attributes instead. External microsyntaxes are fine (e.g. @style, input@pattern, time@datetime).
• Also, when an attribute contains user-facing text, that should be an element, for i18n. Yes, this means @title and @alt should have been elements (and that empty elements were likely a mistake).

[annevk]

I'm not sure I agree that title and alt should have been elements. That would have added quite a bit of complexity and they were never a big i18n problem as far as I can tell. We never did see reason enough to add titlelang and titledir and such, for instance. Making them a lot more convoluted to use might well have made them much less likely to be used.

Same deal with placeholder, a quite recent addition to this group.

[hober]

The action is on me to draft text for this one.