Style guide for adding stacked slots to our components.

[heyMP]

This is a cary over from this thread: #254 (review)

Background

Stacked slots is a technique where the web component developer can utilize the "fallback" nature of slots to provide a layered regions that the user can override within the shadowroot. For instance, we could provide 3 ways to override the a region that displays button a button group:

┌───────────────────────────────────────────────────────┐
│ slot:button-container                                 │
│                                                       │
│ ┌──────────────────────┐     ┌─────────────────────┐  │
│ │                      │     │                     │  │
│ │ slot:submit-button   │     │ slot:dismiss-button │  │
│ │                      │     │                     │  │
│ └──────────────────────┘     └─────────────────────┘  │
│                                                       │
└───────────────────────────────────────────────────────┘

We could override the submit-button region, the dismiss-button region or both."

So why do this?

These layers of overrides with increasing layers of specificity make a design component more flexible. Even though no one has yet asked for the capability, we include it anyway to account for edge cases that either don't exist yet or haven't yet been considered. A practical reason for doing this is enabling A/B tests that need to make sometimes more radical changes to our components.

Why would we not do this?

We are giving users the ability to override more of the web components shadowroot than normal which can result in user taking advantage of it by overriding everything by default or by accident. One could make a sensible argument that this violates the purpose of design systems.

This also opens up the issue of managing a larger API surface. Typically, if a slot were to be moved or removed that would most likely constitute a breaking change to the component.

[bennypowers]

We could (and should) extend this reasoning to things like CSS Custom Property 'stacks' - How much room for customization should we provide? There are three positions we could take:

1. Maintain a minimal API surface, permitting fewer customization options
2. Provide undocumented escape hatches
3. Maintain a maximal API surface, permitting broad customization options

In my view, (3) is undesirable, as it would lock us in to those APIs: changing them (even slightly) would constitute a semver major breaking change. Similarly, (2) is not much better than (1), it merely 'shifts the blame' from changelogs to chat rooms, although it does perhaps give us some plausible deniability. The YAGNI principle is instructive here, or it's less-shrill cousin: the Robustness principle (be conservative in what you provide, be liberal in what you accept). Each user-accessible option we provide constitutes a promise on our part, a part of our "API contract", which for the sake of our users we should hold in high regard.

We shouldn't be against adding features, and stacking slots (and CSS custom properties) is a useful and very cool technique, which was well-applied by our own @heyMP in the case of rh-footer, but (especially at this early stage) we should be deliberate about each feature we add.

So, coming back down to earth, in the specific case of <rh-footer>, I recommend removing at minimum the base slot, and we should seriously consider removing the header, social-links, main, and footer slots, while retaining the rest (these being selected after considering a 'typical' user's needs with the element).

[heyMP]

cc @zhawkins, @wesruv This is something that we've talked about previously in terms of escape hatches. We're trying to find a balance between "escape hatches everywhere" and "maintainable API contracts".