Custom Element Semantics - Advice and Requirements


I have spent the last week or 2 adding content to the Custom Elements spec about the semantics of custom elements and how devs can implement robust semantics. Would appreciate any feedback on the Custom Element Semantics section


Looks good certainly.

Perhaps separating out the examples into different self contained use case examples rather than evolving the taco and tequila elements as you go along to show an evolving set of changes.

I often find it more approachable to jump into the solution I’m trying to solve.


@SteveF this might be bikeshedding, I’m not sure. It seems to me that it would be better to re-arrange this. 1.11.1 introduces the problem pretty well except that the end of the paragraph and the arrangement of the two subsequent explanations seems misleading to me. Would it be better to rephrase as (added stuff in bold below):

The addition of visual styling and scripted events to the taco-button could provide hints as to the semantics and expected interaction behaviours of the custom element for some users, but for the semantics to be formally expressed, developers must convey the semantics either by way of extension of an element with built-in semantics or by using ARIA roles, states and properties.

See, extension is easier to get right if that actually is possible to do (as is the case with your example, which is why I find it confusing maybe). So, then just reverse the two so you present extension first and then explicitly call the other out as ‘Adding Semantics via ARIA’ or something and explain that sometimes this is just the route you’ll have to take because you’re just extending ‘HTMLElement’ which has no built in semantics really.


Hi @jonathank, thanks for the feedback. The stuff in the spec is really only meant as an intro to the more exhaustive docs listed in the developer advice section


by you, no way :wink: Will review and get back to you, thanks!