[Feature Request] Add Styling Guidelines

[daKmoR]

Styling Guidelines had the following text inside...

restructure/rewrite/reconsider if still needed

https://github.com/ing-bank/lion/blob/master/docs/20-guidelines-styling.md
(Link will only become valid once the branch feat/markdown has been merged)

<!-- TODO: check if needed for story above, else delete
It would mainly be benificial when:

- styles need to be reused in a context where extending is not a solution/forking is needed (which
happened quite some times in our previous components lib, making our core styles less scalable).

- style components (and their corresponding html structure) are considered the core building
blocks of a Design System. Webcomponents provide a developer friendly abstraction that mainly
sees fit

### Naming Conventions

For css class naming, we use BEM naming conventions. This helps you identify semantics of
your markup at a quick glance, resulting in more readable and maintainable code.
BEM is an abbreviation for:
- Block
- Element
- Modifier

## webcomponents

### HTML Structure

Despite not having applied any styling by default, our components do have an html structure that
allows [subclassers](./definitions.md) to easily extend them.
Webcomponents can be

### BEM and shadow DOM

Although BEM naming conventions partly encapsulate

All CSS our components is written from a generic mindset, following BEM conventions:
https://en.bem.info/methodology/

Although the CSS and HTML are implemented by the component, they should be regarded as
totally decoupled.

Not only does this force us to write better structured css, it also allows for future
reusability in many different ways like:
 - disabling shadow DOM for a component (for water proof encapsulation can be combined with
  a build step)
 - easier translation to more flexible, WebComponents agnostic solutions like JSS
  (allowing extends, mixins, reasoning, IDE integration, tree shaking etc.)
 - export to a CSS module for reuse in an outer context

Please note that the HTML structure is purposely 'loose', allowing multiple design systems
to be compatible with the style component.
Note that every occurence of '::slotted(*)' can be rewritten to '> *' for use in an other
context
-->

<!-- TODO:
 - follow https://cssguidelin.es/ and/or inuitcss: by prefixing our components with 'c-', we mark
    our components as core components, ensuring they never conflict with css created by  -->

[daKmoR]

more text that was unclear in relationship to lion

## Style components

A style component consists of a set of css classes mapping to a certain html structure. Although css
components are often implemented by web components, they should be considered modules on their own,
reusable in different contexts: they should be considered the lowest abstraction layer of a
web component.

A web component usually implements a css module (mapped at host level), but the opposite is not
necessarily true: a css module doesn't have to be used inside a web component or at the root level
of a web component.

Advantages of developing style components isolated from web components are:

- They can be reused in non shadow dom contexts.
- Not everything has to be a web component: anchor or card styling inside a web component would be a
  matter of importing a style component into a shadowroot.

### Requirements

Style components are written with the following assumptions in mind:

- **Environment agnostic**: Lion web components are unopinionated about their environment: they
  should be usable in every context/framework/technology thinkable, regardless of whether shadow dom
  is used.
- **Customisable**: They should provide an api for [subclassers](?path=/docs/guidelines-definitions--page#subclasser):
  - **white label**: components (just like web components) are white label components. They provide
    a flexible html structure which should be mappable to any Design System.
    This approach is inspired by [Inuitcss](https://github.com/inuitcss/inuitcss) (an architectural
    foundation for white label style components) and [Bootstrap Material](https://fezvrasta.github.io/bootstrap-material-design/)
    (a Material Design system based on existing Bootstrap html/class names).
    This is also [a great example of a Design System](https://www.carbondesignsystem.com/components/checkbox/code)
    taking this(style components as lowest abstraction layer) approach.
  - **well structured**: for clear, readable and maintainable code we use [BEM](http://getbem.com/):
    it forces the
    developer to think about component structure in terms of 'block', 'element' and 'modifier'
    parts/roles. The classes defined in a BEM component form the api for a
    [subclasser](?path=/docs/guidelines-definitions--page#subclasser): he can 'fill in' the BEM selectors by overriding them in the
    `static get styles()` configuration property on the constructor of a web component.
  - **flexible markup**: By making the HTML structure purposely 'loose', multiple Design Systems can
    be made compatible with the style component. When the default html/css structure is not flexible
    enough, it can be extended by creating new BEM element selectors.

## Why BEM?

For css class naming, we use [BEM](http://getbem.com/) naming conventions. This helps you identify
semantics of your markup at a quick glance, resulting in more readable and maintainable code.
BEM provides us the following advantages:

- **Clear namings** that convey meaning about semantics and structure at a quick glance
- **Prevent collisions** within shadow roots. Larger shadow roots using multiple style components
  would easily collide when css selectors would be scoped to the shadow dom in which they were
  created. For instance, calling the header of a card '.header' instead of '.c-card\_\_header'
  would make the card component not reusable in different contexts.
- **Maximum flexibility** we can write css regardless of context. When we create a style component
  for a card, we can offer it as a style component only and later decide to offer it as a web component.
  Or offer the style component
  as a more lower level api for advanced use cases and the web component (that has limiting markup and
  styling options) for the majority of cases.
  Also, when we already have a web component for the card and people want to create a custom card
  component, it might make more sense to write a new web component instead of extending the existing
  card web component.
  Having style components as described above, allows for maximum flexibility in these scenarios.
  Future CSS updates can then be done from a central place, without having to rewrite forked web components.
- **Performance** we aim for applications having a limited number of shadow roots and we consider
  shadow root creation a performance concern. Style components reduce the need for shadow roots.

[//]: # 'TODO: we definitely suffered here in the Polymer era. We might want to create some new perf tests for our lit-element based apps to verify this claim again.'

### Challenges with BEM in shadow dom

Mapping BEM components to shadow root is not really straightforward:

1. host styles should be rewritten to `:host {}` instead of `.my-block {}`
2. slot styles be rewritten to `::slotted(.my-block__element)` instead of `.my-block__element`
3. we should not [self-apply classes](https://developers.google.com/web/fundamentals/web-components/best-practices)
   on host level. Apart from this being a bad practice, it will trigger linting errors in our setup.

### Mapping host and slot styles

The [CSS Module](https://github.com/w3c/web components/issues/759) and [CSS Selector](https://github.com/w3c/csswg-drafts/issues/3714) proposals would allow us to reuse BEM components more easily within web components.
We might also think about other ways of creating build steps that would allow us to map BEM
components to a shadow root, making it possible to map hosts and slots in an eay way.

[//]: # 'TODO: quite important that we find a solution to this problem'

### No self-application of classes

In order to adhere to this rule, notation of our BEM modifiers that live on the host (which are
ususally written like `.my-block--my-modifier`) will be rewritten to `.my-block[my-modifier]`
Although this would only be needed for the third challenge as described above, for consistency,
we apply it to all our modifiers within our style component.
So for instance `.my-block__element--my-other-modifier` becomes
`.my-block__element[my-other-modifier]`.

### Why mapping style components to the host matters

- **flexible host overrides**:
  Imagine we have a style component `.c-alert` and we want to map this to a web component `<my-alert>`.
  In our Design system it might be a good practice to give all our block components a default bottom
  margin of 16px. An [Application Developer](?path=/docs/guidelines-definitions--page#subclasser) might need an instance of `<my-alert>` where he wants to
  set this bottom margin to 0.
  If the margin-bottom of 16px would not be defined on the host level but one level deeper (the first
  div element within the shadow root of `<my-alert>`), the Application Developer needs to apply a
  negative margin of -16px. The latter would be a bad practice.

- **easily map modifiers**:
  If we continue with our alert example and we have a flag 'is-closeable', we might need to adjust
  styling based on that. In this case we assume the attribute 'is-closeable' serves as a styling
  hook for the `.c-alert` component.

[tlouisse]

Hey,

Good to bring this up 👍 It's very much related to best practices/apis for Subclassers like discussed here: #591
I hope in one of the coming weekends I will have time to finalize the Material Design extension of the datepicker, which could illustrate those ideas more concretely.
Also, we could properly answer #632 then.

About BEM and its relation to Lion

I think in essence this document pledges for a structured, predictable api for Subclassers.
Just like the platform does this with pseudo elements (example for input[type=date]):

::-webkit-datetime-edit-fields-wrapper { background: silver; }

We can't provide this api, so we need another structured approach for this (can be BEM, can be anything).

Subclassing in practice

There are two ways for a Subclasser to extend out Lion components and make them compatible with a Design System:

1. Only override the styles (let's call this the CSS Zen garden approach
2. Provide both your own html and css. If approach 1 cannot solve your use case, take full ownership of the html (we aim to do this in such a way that all functionality/a11y are still handled by lion, see [Feature Request] Make templates more extendable #591)

The docs were written with approach 1 in mind. The lowest barrier component extension (think of a lion-input) would be:

class BlueBorderInput extends LionInput {
   static get styles() {
      return css`
         .input-group {
           border-color: blue;
         }
     `
   }
   // no template overrides
}

When writing such a component, it might be benificial to have access to a 'raw' html/css structure like: https://github.com/ing-bank/lion/blob/master/packages/field/src/FormControlMixin.js#L260

So this default css structure can be provided in many ways. BEM is a good candidate, because:

• it is well known (we don't have to reinvent the wheel)
• you can see at the blink of an eye what a class is meant for (.block, .block__element or .block--modifier)

And then there is the fact that we use BEM in our extension layer for 'pure css components (cards, links etc.')
Having one (instead of two) convention for all css would also be an added benefit. Only a bit coupled to our own extension layer ;)

So... we could argue that something less opiniated than BEM would be a better fit. Then we would probably end up with something like our own BEM flavour, but call it differently 😄

Few other remarks

These docs can use an update/makeover (some of those things were written with a 'Polymer era mindset' and don't apply anymore (about performance etc.)).

As for the big TODO: this was never supposed to end up in master as it was not written for '3rd party consumption' 😉
So feel free to delete. Both in the code and in this topic, because it's mainly noise in the discussion.