Docs should explain why you're not extending built-in elements.

[markcaron]

As Eric Bidelman noted, "There's no better way to write a progressive web app than to progressively enhance existing HTML elements." [1]

Where possible, buttons and other custom elements should extend native HTML elements "to gain all of its features (DOM properties, methods, accessibility)". [1]

[1] https://developers.google.com/web/fundamentals/web-components/customelements#extendhtml

[surma]

Agreed, where possible, native elements should be used. See 7ca3652

[robdodson]

Unfortunately there's a lot of contention around extending built-in elements with some browsers stating that they will "never" support it. Even libraries like Polymer are dropping support (in the near term) to see if we can find consensus on a different solution. For these reasons we've chosen to not do customized built-ins on this project and we're going to be updating the docs wherever possible to indicate when using a native element would be preferable. This is a good issue because it reminds me we should add a similar warning to the toggle button.

[markcaron]

Awesome! Thanks, Rob and Surma. I figured you had a good reason for not extending HTMLButtonElement. :-)

A warning would be helpful. Thanks for the explanation.

[robdodson]

I changed the title of this issue and I'm reopening so we can go back and add this explanation to the docs.