Style Guide: provide reasoning for all Priority A: Essential items

[jedahan]

Awesome work with the style guide!
I especially love the explanation on the first item:

This prevents conflicts with existing and future HTML elements, since all HTML elements are a single word.

On a meta-level, it seems if you are recommending a style as being Priority A/Essential, an explanation of reasoning/why will go a long way to help people understand the value in doing a thing, and not just blindly doing it.

[chrisvfritz]

I agree! 🙂 Which Priority A rule(s) are you not seeing sufficient explanation for?

[jedahan]

When using the data property on a component (i.e. anywhere except on new Vue), the value must be a function that returns an object.

There is a 'Detailed explanation' button that I totally missed, but having a single line summary of that detailed explanation above it, like

Making the value of data a function that returns an object, allows components to maintain separate states instead of sharing the same state.

---

I think, revisiting this issue, I didn't realize that some have 'Detailed Explanation' blocks, and some don't. There is a lot of information here, maybe a side-by-side design with the detailed explanations in a separate column to the right would help make both more visible.

[chrisvfritz]

maybe a side-by-side design with the detailed explanations in a separate column to the right would help make both more visible

I like the idea of making these more visible, but a lot of users are viewing on screens too small for a side-by-side design like that. Maybe changing the background of the collapsed Detailed Explanation blocks on hover would help. What do you think?

[jedahan]

That would help.

Maybe having the text of the button for detailed explanation being the first line of the contents, with an ellipses if its too long?

[chrisvfritz]

I don't think displaying partial content with an ellipsis would be possible if we stay with native <details> elements, but I'll play around with it. 🙂