search

generoi / genero-design-system

https://gds.generogrowth.com/
MIT License
4 stars 0 forks source link

Add storybook #5

Closed oxyc closed 4 years ago

oxyc commented 4 years ago

Let's store these in each component src/components/button/stories?

Shall we use mdx? I guess this should work (seems there's some issue with importing markdown though):

import { Meta, Story, Preview, Markdown } from '@storybook/addon-docs/blocks'
import Readme from './readme.md'

<Meta title="Button"  />

# Button

<Markdown>
  {Readme}
</Markdown>

<Preview>
  <Story>
    <gds-button>Button</gds-button>
  </Story>
</Preview>

Also https://github.com/storybookjs/storybook/issues/4600

oxyc commented 4 years ago

@silentnoodlemaster maybe you can have a look at this tomorrow? Maybe @taromorimoto @Hyperinen @henritukiainen can give some thoughts on what we should do since they've used it before.

toffebjorkskog commented 4 years ago

Interesting.

toffebjorkskog commented 4 years ago

Will be nice to see how it displays the components

henritukiainen commented 4 years ago

Directory structure

Agree with storing the stories per component, i.e. src/components/button.

Not sure if you need a stories directory under that. I think there would typically be only one story file per component (with multiple stories in the same file, of course), with occasional additions for some sub-components. Seems to me that with good naming convention it might be cleaner to keep the stories next to the components? Thoughts?

button/Button.js button/SomePartOfButton.js button/stories/Button.stories.js button/stories/SomePartOfButton.stories.js

vs

button/Button.js button/Button.stories.js button/SomePartOfButton.js button/SomePartOfButton.stories.js

I guess we'll also have a storybook directory at the root of the gds repository for configs, mocks and helpers, etc.?

MDX

Would be happy to give mdx a try. We're about to switch to it in our other component library as well. We don't have any practical experiences of it yet, but using the storiesOf syntax we did eventually start importing md files just because they're so convenient for writing longer documentation, and mdx should hopefully be more convenient than importing md into jsx.

It's still listed as experimental in Storybook docs, but we could write a few component stories using it and we can still switch afterwards if it's buggy. If it doesn't work out, Storybook's recommended way is Component Story Format (CSF), which seems pretty great (kind of better than mdx actually :).

Story structure

It's important to get the naming conventions of the story groups, stories and substories right, but it's hard to figure the structure out before we have a few stories up. Luckily the stories are really easy to move around, so let's just improve it once we have a few components.

Design System/Buttons/BaseButton Design System/Buttons/SomeSpecialButton vs. Design System/Atoms/Button Design System/Buttons/SomeSpecialButton vs. Design System/Button/someSubStory Design System/SomeSpecialButton/someSubStory

silentnoodlemaster commented 4 years ago

@silentnoodlemaster maybe you can have a look at this tomorrow

I did not notice this until now

oxyc commented 4 years ago

Seems to me that with good naming convention it might be cleaner to keep the stories next to the components? Thoughts?

Sounds great since you say there's not really a use case for having multiple story files per component (I've never used it).

I guess we'll also have a storybook directory at the root of the gds repository for configs, mocks and helpers, etc.?

Yes

Storybook's recommended way is Component Story Format (CSF), which seems pretty great (kind of better than mdx actually :).

I tested it and it seemed pretty nice yeah. Also since stencil already autogenerates some docs (available properties, css variables etc) maybe this is a better way to go as we might want to keep our docs in the readme.md?

henritukiainen commented 4 years ago

Storybook's recommended way is Component Story Format (CSF), which seems pretty great (kind of better than mdx actually :).

I tested it and it seemed pretty nice yeah. Also since stencil already autogenerates some docs (available properties, css variables etc) maybe this is a better way to go as we might want to keep our docs in the readme.md?

Fine by me, but I'm not that familiar with the expected benefits of mdx. @taromorimoto any thoughts? I think CSF was added after our decision to go with mdx, so we probably haven't done a comparison...?

silentnoodlemaster commented 4 years ago

41e059ca3ac0960c9e768fd73c8d833d989cdce9 looks like image

oxyc commented 4 years ago

Story structure

It's important to get the naming conventions of the story groups, stories and substories right, but it's hard to figure the structure out before we have a few stories up. Luckily the stories are really easy to move around, so let's just improve it once we have a few components.

Design System/Buttons/BaseButton Design System/Buttons/SomeSpecialButton vs. Design System/Atoms/Button Design System/Buttons/SomeSpecialButton vs. Design System/Button/someSubStory Design System/SomeSpecialButton/someSubStory

Yeah maybe we need to come back to this once we start having some components.

Personally I like the straightforward

Design System/Buttons/BaseButton Design System/Buttons/SomeSpecialButton