Overlay

[simurai]

This is a proof of concept for the following idea: Because we have a few patterns/components that are quite similar and they all need to become responsive, why not combine them all with some sort of container object. Make it reusable for any kind of content.

We do this by:

• Introducing a new responsive .Overlay object
• Introducing a new .SelectMenu component

Which lets us potentially deprecate:

• .select-menu
• .dropdown-menu
• .Box-overlay
• .Popover
• Maybe also "hover cards"?

Example

Below a simple example, more in the documentation.

<details class="details-reset details-overlay" open>
  <summary class="btn">Choose an item</summary>

  <!-- Overlay object starts here -->
  <div class="Overlay">
    <div class="Overlay-box">
      <header class="Overlay-header"><!-- Optional -->
        <h3 class="Overlay-title">Title</h3>
      </header>
      <main class="Overlay-content">
        
        <!-- Content goes here. For example a .SelectMenu -->
        <menu class="SelectMenu">
          <a class="SelectMenu-item"> ... </a>
          <a class="SelectMenu-item"> ... </a>
          <a class="SelectMenu-item"> ... </a>
        </menu>
        <!-- Content ends here. -->
        
      </main>
      <footer class="Overlay-footer">Footer</footer><!-- Optional -->
    </div>
  </div>
</details>

📝	📷
default
.Overlay--dropdown
.Overlay--selectMenu
default as dialog
.Overlay--popover

☝️ < sm breakpoint.

Benefits

• By re-using the .Overlay object for multiple patterns, we can greatly reduce CSS.
• By re-using the .Overlay object, we can keep the look consistent.

Concerns

• It might be harder to maintain because changes to .Overlay need to be tested with many use-cases in mind.

• The "API" is not as intuitive. Currently it uses multiple modifier classes of the components it tries to replace. E.g. .Overlay--selectMenu. But it shouldn't describe the content, it should only describe the different "versions" of the .Overlay object. Some alternatives:

  • .Overlay--dropdown -> .Overlay--min, .Overlay--small
  • .Overlay--selectMenu -> .Overlay--max, .Overlay--large, .Overlay-xs-fullHeight
  • .Overlay--popover -> .Overlay--transparent

  Not matter how often I renamed them, it just doesn't feel right.

• Having a lot of flexibility is great, but it might come at a cost of not being consistent throughout many use cases.

Alternatives

An alternative to this PR: Keep the components separated, maybe refactor/rename them and make them responsive. See https://github.com/github/design-systems/issues/601#issuecomment-488263465. Overall more CSS would be needed and the same/similar styling is repeated in multiple components. But at the same time they should be easier to maintain since they don't try to be too many things at once.

---

Ref. https://github.com/github/design-systems/issues/601#issuecomment-489551559

[simurai]

Let's close this again now that #808 shipped.