New docs site

[brian-smith-tcril]

Planning issue to discuss what we're looking for in a new docs site.

• Things we should keep
  • Live editable code examples
  • Runtime theme loading/switching
  • Usage guidelines
    • Opportunity to improve as we go
• Things we should add
  • Real-world examples
    • Like usage insights but better
      • With frontend-base converted frontend apps we might be able to do this by importing components from npm published apps.
  • Recommended ways to use something (in comparison to all the different ways it is used throughout frontend apps)
    • Clear distinction between human recommendations and machine gathered usage data
      • How to classify? Way to say "this is good, we should consider how to better support this in/with paragon" and "we haven't looked at this, we should see if this is a bad pattern we should try to replace" etc.
• Things we should change
  • Structure (follow atomic design hierarchy)
• Things we should remove
  • //todo

Other thoughts:

• What "wrapper" components in frontend apps are good vs bad
  • Wrapping a Paragon component to set props to keep an app more DRY is fine
  • classnames
    • using for "reasonable" things like adding margin/padding (basically any bootstrap helper classes) makes sense
    • things can get messy with custom css overriding (!important) Paragon component styles
    • Add "Customizing using className" sections to the component pages on the Paragon docs site #3785
  • Popover vs modal
    • feat: add prop to set noIsolation prop for modal popup #3777

[bradenmacdonald]

Just for fun, I made a prototype of a new docs site (and new Paragon!) here, using Storybook: #4384
It doesn't have most of the new content you're suggesting here, but it would make it much easier to add, and all of the documentation example code is type checked, which is a huge improvement over the existing docs site.