Research porting docs to Docusaurus and remove them from Storybook

[simoneb]

GitHub's Primer website is a good source of inspiration, if not a good idea for an implementation even

[nstolpe]

I've started some research into this. As far as I can tell, we should be able to copy MDX directly from storybook into Docusaurus and use that. Docusaurus allows you to define and use React components inside an MDX file, which might simplify our setup of demo files (StoryBook may allow this too, I haven't looked into it yet, but I haven't seen it happening in code so far).

I found this Docusaurus addon for integrating Docusaurus and Storybook. The documentation is sparse, but from what there is it looks more aimed at using Docusaurus components in Storybook stories. Still, it might be wroth investigating further, or using as a reference if.

This comment on a Docusaurus Github issue discusses and has an example of embedding a Storybook story in Docusaurus. It seems to work pretty well, though it's in an iframe and still has Storybook styles (you also can't scroll inside the iframe, but I'm guessing that's a bug in their code).

Given Docusaurus's MDX support, I think that route might be the simplest and most straightforward in terms of initial dev and later maintenance. I think we would lose out on Storybook's component configuration preview, but we may be able to include enough interaction with wrapper components around the demo's. It might be worth doing a quick prototype with one or two components to see how it goes.

[nickzafiropulos]

Lots of inspiration for design system websites here - https://designsystemsrepo.com/design-systems/
Most have a lot of detail in the documentation, but follow a similar basic structure.

At the most basic level:

Homepage / intro
Foundations (detail on colour, type, spacing etc)
Components (with varying tabs on each to include overview, react implementation, accessibility etc)

Having each component page tab based allows us to scale easily.

Deciding on what exactly these tabs, and indeed the level and format of the detail is a fairly big discussion/job in itself, which we should work alongside the DS community on. Formidable designers have been working on https://designsystem.puma.com/ , so we could also learn a lot from them.

But first, I would suggest:

1. Some basic conceptual designs to align on a scaleable structure - no real content or detail at this stage
2. As @nstolpe suggested, setting up a Docusaurus site as a prototype to test out the intergrations etc

[nickzafiropulos]

@nstolpe - this might be useful https://www.youtube.com/watch?v=2R53Y7eP45k