[Feature Request] Add Guides for how to style Lion components

[alangdm]

This is a bit of a follow up to a conversation with @daKmoR and @jorenbroekema at the Slack channel
https://polymer.slack.com/archives/CJGFWJN9J/p1583744891016200

The basic idea is that I feel that, while the current storybook is great to demo what the Lion components actually do and what their API is, there's no guide on how to easily achieve the main objective when using Lion components which is to extend them and add your own styling

So I propose to create a "Styling Guide" so that the information on how to style each Lion component is easily accessible

I would like to contribute on it, but before submitting PRs or anything, there are a few things I think need to be agreed upon:

---

1. Where to put the guide?

I think there's basically two options, use the current storybook or create a new guide from scratch, here are some of the pros/cons I can see:

• Storybook
  • Pros:
    1. Easy access to everything
    2. No need to configure another site
  • Cons:
    1. This would be mixing up a usage guide (current storybook) with an extension guide
    2. The current storybook could get too bloated
• New Guide
  • Pros:
    • All docs regarding customization are on one place
    • The format doesn't need to align to the current storybook
  • Cons:
    • Need to configure and maintain another site (or maybe blog articles somewhere? a wiki?)
    • Moving between the two guides might be cumbersome

2. How to handle "inheritance"

This partly connects with the previous point but since many components share similar base structures, documenting every part on every component's guide would be repeating a lot stuff

So no matter on which approach is taken on where to host the guide itself, it also needs to take in account how to avoid repeating information unnecessarily

---

Those are all the things I can think of right now, but I'm sure there are many others so please comment on what you think could be a good for creating this guide

[jorenbroekema]

Interesting! We definitely need a proper way of documenting subclasser stuff.

For me, the optimal end result would be to have storybook docs tab open with usage documentation, and then have another tab that open the subclasser documentation:

It could also be a secondary tab/toggle like this that toggles between usage and extend:

I think with this end result in mind, you have the best of both worlds as suggested by you @alangdm , because you still have it all in one place which is nice for maintenance and for readability/findability, but you don't bloat the demos because it is still its own tab. I think it definitely deserves its own tab for all our web components.

If we have a consensus that this end result is good to have, then we can think about how we can reach this result with storybook on a technical level.

[alangdm]

@jorenbroekema
I love the idea of the extra tab! I hadn't thought of doing it that way

Common CSS classes for groups of components could also be written once but included in every component's "extend" tab too

[jorenbroekema]

Hey just an update from me,

I think a general good first start would be to create some subclasser docs just to see what makes good subclasser documentation, what content is in there, etc.
Then I think it will be much easier to discuss concretely on a technical approach for how to integrate it in our Storybook on every story directly, as a tab Extend, in a somewhat automated way hopefully.

We would definitely need feedback from people using lion to build their components or even design systems in this, do you mind if I drop you a message to review it once we have some first examples?

Just to start the discussion off with what I think should be in a subclasser/extension doc:

• API table with all protected methods/props (because they are specifically meant for extensions to override)
• Table of CSS classes used in Shadow DOM of the component, to highlight suggested ways of overriding styles (e.g. for LionInput, how to create a horizontal layout of label + help-text + field)
• A concrete example where at least a few sensible method/prop overrides are done, as well as styling

Let me know if you think there are other things we should definitely have in there 🤗

[alangdm]

...do you mind if I drop you a message to review it once we have some first examples?

Sure!!

As for the extension docs contents, I hadn't thought about the API table but I think that would work great for more advanced cases

The examples would also be great but they might imply a high maintenance cost so that might be the hardest part of all this I guess

[jorenbroekema]

Closing as enhancements with votes needed, as per our workflow to only have bugs in issues. We are still actively pursuing the ambition to have subclasser docs side to side with the demos, we are looking a bit beyond Storybook for that by using MDJS inside a static site generator, but this is very much WIP still and happening behind the scenes of open-wc a bit :P