search

processing / p5.js-web-editor

The p5.js Editor is a website for creating p5.js sketches, with a focus on making coding accessible and inclusive for artists, designers, educators, beginners, and anyone else! You can create, share, or remix p5.js sketches without needing to download or configure anything.
https://editor.p5js.org
GNU Lesser General Public License v2.1
1.34k stars 1.29k forks source link

Create a component library/style guide #1216

Open andrewn opened 4 years ago

andrewn commented 4 years ago

Nature of issue?

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

Considerations

catarak commented 4 years ago

Storybook

Pros

Cons

React Styleguidist

Pros

Cons

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

found this comment relating Docz to Storybook, see whole thread

catarak commented 4 years ago

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

andrewn commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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:

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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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

andrewn commented 4 years ago

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:

Screenshot 2020-04-19 11 08 34

"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:

Type:

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 commented 4 years ago

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.