Create a component library/style guide

[andrewn]

Nature of issue?

• New feature request

New feature details:

When developing features for the Editor, it can be challenging to figure out if the UI widget you need already exists in the project. If a component exists already, then copying it can cause subtle inconsistencies.

It'd be great to have a style guide in the projects that displays available components, and the different states they can be in. This should make the Editor more consistent, help reduce bugs and make contributing easier.

Possible choices

• Storybook
• Patternlab
• React Styleguidist
• Bit.dev
• Docz

Considerations

• Work with React
• Display "live" versions of the components so that changes to them are immediately visible
• Work with whatever CSS approach the project uses (see Component styles #1215)
• Easy to add new components
• Display the code required to use the component next to the rendered version
• Generate a static site so it can be viewed on the web (?)

[catarak]

Storybook

Pros

• Most widely used option
• addon support
• adds separate .story files - leaves components alone

Cons

• Learning curve - uses cutting-edge JavaScript that newer programmers may not be familiar with

React Styleguidist

Pros

• Uses JSDocs syntax - easy learning curve
• Uses Markdown files to document components - easy learning curve

Cons

• Adds comments inline to components
• JSDocs can be super finicky

PatternLab

It seems like this doesn't work with React?

Bit.dev

I think this project is for sharing components across projects by putting them into a library, which I don't think is necessary for the web editor.

Docz

Pros

• Uses MDX (Markdown + JSX, like React Styleguidist)
• Seems like React Styleguist but more simple?

---

found this comment relating Docz to Storybook, see whole thread

[catarak]

Also found this Front-end documentation post. Reading through this, I'm leaning towards React Styleguidist or Docx!

[andrewn]

Storybook
Learning curve - uses cutting-edge JavaScript that newer programmers may not be familiar with

What kind of "cutting edge" JavaScript do you mean? I've only used the same ES6/JSX when writing storybook stories.

[andrewn]

I think a good next step would be to pick a fairly simple component that changes with different props (e.g. button) and try out our top-3 tools to see how it they work. It sounds like: Storybook, docz and React Styleguidist?

[andrewn]

I've been setting up a component library on another project so had the opportunity to try out Docz and Storybook. Here are my thoughts.

Docz

I find that the Docz approach of writing MDX is less constrained, so better for a large style guide where there may be a lot of textual documentation for each component. For example:

• what is this component
• when should you use it
• when should you not use it

Docz will fetch the props and comments from prop-types to describe the components. It will also embeds a code editor so you can edit the component code to see how the props change. But it's just a free-form text editor, which is flexible but not as nice as Storybook add-ons.

Overall, it felt that Docz has less add-ons.

Storybook

I've mostly been using their Component Story Format (CDF) for writing stories. This is slightly more effort and structured, but I think that's maybe a good thing as it provides a template for everyone to follow.

Storybook has a lot of add-ons for adding things like accessibility checks, viewport resizing etc.

Storybook has a "knobs" add-on (click the "Knobs" tab at the bottom) that allow you to dynamically alter the props passed into the component. It's more work but gives you more control.

Storybook will also fetch the prop-types and comments and display them in a table.

The latest version also supports MDX, so you can do similar things to Docz if you want. It's not as mature yet, but it's interesting that this is also the direction they're going in.

Styleguidist

I didn't try to set this up. Looking into the docs a bit more, I was concerned it was too "automatic" to work with a complex project.

[andrewn]

@catarak I've opened two PRs #1244 (storybook) and #1294 (docz) for comparing the two component systems.

Both include a Button component using styled-components for comparison.

docz parses all the .md files in the project and turns them into nicely formatted HTML which is a nice touch.

However, I think Storybook is a better tool for developing components, especially being able to switch the theme via the UI but I'm keen to hear what you think!

[catarak]

Thanks for trying out both of these options! Spent a bunch of time looking at your two PRs and I agree, I think Storybook is the way to go forward. Being able to change the themes is a huge plus, and the knobs are a nice feature as well.

I definitely want to try my own hand at making a story, but also I think we should spend some time thinking about we want to configure/design storybook. I was looking through the Storybook Examples and surprised by how different they are. Luckily the source is linked to in a lot of the examples so we could pull from those.

[catarak]

It's also really helpful to look at the examples for reference on how to actually make a component library 🙃

[andrewn]

Storybook supports using "/" in titles to organise stories. The format is "Root/Group/Group/...". The groups can be nested arbitrarily, I think everything that doesn't contain actual stories turns into a folder.

The title "Components/Brand/RTL" would result in:

"without brand link", "with brand link", "with script link" are stories exported from the file with title Components/Brand.
And "RTL - with brand link" is a story exported from the file with title Components/Brand/RTL.

I'd suggest having a more consistent and shallower nesting for our component library:

<Root>/<Type>/ComponentName

Root:

• Common: shared components in client/components
• App: components in client/modules/App
• IDE: components in client/modules/IDE
• User: components in client/modules/User

Type:

• pages: in client/modules/*/pages/
• components: in client/modules/*/components

The aim is for Common to get bigger as we extract more reusable components from other parts of the app.

I'm not very convinced about Type but I think it's simplest for the component library structure represents the file structure of the app. We might not create stories for the pages in the app.

[catarak]

I like this organization! I agree about the component organization being too nested, and I think this is more straightforward. As certain components are being moved off the main IDE view (like the sketches/collections) I wonder if it would make sense to have another folder. Or like... would that stuff go in "App"? What should go in "App"?

Also agree that pages don't need to have stories. I think it's the most important to have stories for the stuff in client/components, as those are the things that new features would mainly be comprised of.