CLI: consistent welcome-component in all generators

[yannbf]

Work summary

Make all 0-Welcome.stories.* components look the same and have the same content accross all storybook templates.

These are suggestions from @ndelangen but we can discuss further in this issue:

Storybook logo
Link to storybook docs
Link to discord invite
Link to storybook repo on github
Some message about the ability to add & write addons

This work is part of #10723 and depends on:

• preferrably CLI: colocate example components together with generated stories #10793 to be done first.
• A proposal that @domyen is making.

Where to start

Check all framework templates under generators folder and change the 0-Welcome.stories.* components accordingly.

Acceptance criteria

• CLI tests are passing
• E2E tests are passing
• The implementation is approved by @domyen
• Changes are properly reviewed by some of the members mentioned below

Who to contact

@shilman @ndelangen @domyen

[domyen]

I spoke to @tmeasday and @shilman about how this coincides with the new documentation.

Requirements:

• Introduce the concept of stories
• Share the most common ways to configure it for your project. Nearly all users must configure SB to start using it in their workflow.
• Share links to learn and get support

Details
We can build the welcome screen in MDX to make maintenance easy across the frameworks that support SB Docs (all of the official integrations do).

Here's an early preview of how that might look:

wdyt?

[yannbf]

That looks amazing! And all those links would then point to sections of the documentation website?

I like that there are a bunch of info which (at least how I read) reiterates about storybook being a tool to develop entire screens 👌

About MDX it seems to be nice and it would be also a great way to show people how to have documentation pages in their setup right from the start. However that also means that they need to have addon docs out of the box, which shouldn't be a problem once we ship the examples with addon-essentials.

I think, however, that it would be important for the users to distinguish the difference and purpose of mdx and js stories, so they don't get confused.

[domyen]

Nice! The links will go to different parts of the documentation.

I think, however, that it would be important for the users to distinguish the difference and purpose of mdx and js stories, so they don't get confused.

Good idea! Folks are currently unclear about what goes in a story (evidenced by how many Storybooks include prose in the story). We should articulate the difference by adding code comments in the MDX files.

SB Docs
We should ship this with essentials. UI documentation is the second most popular use case for Storybook after isolated component dev.

[tooppaaa]

It's awesome @domyen, really like it. Just a few practical questions / comments:

• where would icons go ? online / copied to client / inlined ?
• I see "src/storybook-examples", like it !
• Can't wait to see it shipped and remove -mdx format !!

[domyen]

@tooppaaa
re:icons It'd make sense to ship them in the storybook-examples directory somehow or perhaps referenced in Storybook's static dir. I don't think we should host them online because network connections can be pretty flaky.

Any recommendations on a lightweight way of including these images? I can output them however is easiest (svg, png, etc).

[tooppaaa]

The most realistic way is the best. In my company's storybook instance, we have an assets folder where we pick svg icons to use in MDX.
So I would go for copying SVG's under storybook-examples/assets

[domyen]

Nice, that makes sense. I'm not very familiar with the build step, but would we run into any issues with webpack?

[tooppaaa]

I checked before saying we could embed svg :D I don't have any special configuration in mine so I assume it's fine.

[tmeasday]

According to the docs we can import png files in stories: https://storybook.js.org/docs/configurations/serving-static-files/#1-via-imports

I wonder if that'll work in MDX files? I guess we'll find out.

Hmm.. although thinking about this a bit I don't know if we can substitute a variable into raw HTML in a MDX file (assuming that is how we want to do this markup in a framework-independent way).

[yannbf]

Storybook adds a few webpack rules by default, and png is supported using file-loader.
But wouldn't it be best if we just import it from @storybook/framework/demo ? The other components would be colocated with the example stories, but for the mdx I think it's just simpler. The Welcome component would be too much boilerplate I think.

[tooppaaa]

PNG, SVG, either will work. What's easiest for you @domyen.
Ideally, in my opinion, we would not import anything from demo as it can create a lot of inconsistency between frameworks.
If we want it to be as close to what users will do, icons should be copied and used like "in real life"
As everything will be in a single place in the codebase, it's just easiest to copy everything.

[tmeasday]

@yannbf I think it makes sense to show people how to make a welcome page in MD(x). I think it's a pretty common thing that folks want to do (for design systems anyway).

[yannbf]

Oh, in that sense I totally agree with you!

[domyen]

Thanks for the feedback everyone. 🙇‍♂️

I coordinated with @tmeasday and @shilman to reexamine the other stories generated by sb init. The goal is to improve the onboarding experience by showing how to configure SB and showcasing how to build entire UIs in SB.

I created a product design strawman that includes:

• [New] Welcome component
• [Updated] Button component
• [New] Header component
• [New] Page component

Check the doc out here
Design prototype here

@yannbf Should we track the work in this issue or break it out into separate issues?

[tooppaaa]

@domyen Loving it, awesome !
I think the should be tracked per framework (even if it's already huge) to deliver

• component
• stories
• e2e

I'm hoping to finish #10913 asap in order to start these tasks on a solid layer

[tooppaaa]

@domyen @shilman @tmeasday has the Welcome story landed ?
addon-essentials is about to be shipped part of the sb init in #11282

I can definetely start to work on some parts.

[yannbf]

Presenting myself available as well to help! Last month was crazy but now I have some time to contribute too 💃

[tooppaaa]

Here's a proposal that we can start to work on https://gist.github.com/tooppaaa/08accf47c0823d2cfbc016debf47276e
Which displays as

My main questions are:

• Is this how you imagine we can build it ?
• What do you think of using MDX variables to create "per story" components ?
• React.children might look weird for non-react users, any other options ?
• @domyen can we have assets ?

Even if the final wording / UI / content is not finalize on your side, I think we can have a good-enough first version we can ship before RC, what do you think ?

[domyen]

This is amazing @tooppaaa!

Before you get too far, I'm going to take a stab at the styling and markup today.

Ideally, we should use raw HTML and CSS in the MDX as much as possible. That will make it easy to port to all frameworks. And users will be familiar with what's going on no matter what framework they use.

Hang tight, hopefully will have something for you in a few hours

[domyen]

I styled the welcome mdx in this repo, see this file.

My plan is to style the rest of the example components tomorrow because they're used in the updated docs. I think the idea is to make the welcome component and the example components consistent in all frameworks.

Strawman next steps

1. I will finish styling the example components tomorrow in a generic way that should work across frameworks. This is effectively a proof of concept for React.
2. I will handoff to someone (@tooppaaa, @yannbf others?) to implement in the rest of the frameworks Storybook CLI
3. We QA together
4. Ship 🚀

WDYT?

[tooppaaa]

Hello !

I can take this task over the weekend ;)

The only comment so far is that it's a lot html of hard-to-read html and don't really show up the capabilities of MDX.
One small step to this direction could be to extract icons to constants

<a>
---    <svg>
---      ...
---    </svg>
+++ <Icon />
</a>


+++ export const Icon = () => <svg> ... </svg>

This would ease the reading of the links

We can of course see that later and so far, deliver this cross framework welcome page !

[ndelangen]

That's beautiful @domyen !

[domyen]

@tooppaaa @tom I styled the rest of the components in the sample repo here. This brings their appearance in line with the design spec. Hooray!

Question
We have a mix of JSX styles and vanilla CSS using the <style> tag. I prefer to use CSS because it's cleaner for styling nested elements. Plus raw CSS is framework agnostic meaning you can paste it in various frameworks as you please.

The Button component is very "React-y". It relies on JSX for styling.

• Do you think we should change it to use raw CSS for consistency with the other components? That would mean we have to use class names which might not be ideal for React, but might easier to port to other frameworks.
• Is there a better solution that I'm missing?

@tooppaaa Re: Welcome MDX, I agree with you on it being hard to read. I updated the code to import the image assets instead of putting them inline. I think this is a big improvement in readability and shows folks that they can import assets/components as if MDX were any other JS file.

[tmeasday]

Here’s my 2c, fwiw:

1. Maybe class names is the best solution. I don’t think our component files need to serve as teaching resources about how to build components in react (et al). There is plenty of stuff on the net for that. I think the priority should be maintainability, across all frameworks.

With that in mind maybe we should have a single css file that we can add to all templates somehow?

2. Similarly if we can just have the image files also in one place in the cli and copied to all templates it probably makes sense to do imports there too!

[domyen]

A single CSS file that we import in each file makes sense to me for maintenance reasons.

Should we drop the CSS and images in the /assets dir?

[tmeasday]

wfm. Would like to hear from @tooppaaa and @shilman who have more context on this front

[tooppaaa]

After looking at the code, I'm in favor of @tmeasday idea. Classnames would ease the reading of components.
We can have css files in assets or next to components (button.css, header.css,...) either case will be easy to implement and maintain :)

[yannbf]

These are subjective questions, maybe for @domyen or @shilman :
for storybook documentation, do we want to point users to:
1 - https://storybook.js.org/docs
2 - https://storybook.js.org/docs/basics/introduction/

Somehow I think that 2 is more straight forward and people can quickly go to their framework of choice in the side navigation.

Also, the welcome component has a link to this component driven approach article https://blog.hichroma.com/component-driven-development-ce1109d56c8e and although it's a great article, it's from 2017. Everything related to storybook there is outdated (like install step, code example etc), and there are links even to kadira. I assume we want to either update that article or revamp it in a new one?

[domyen]

@yannbf we'll need to update the article! Thanks for pointing that out. The point of the 2017 article is to show that the component-driven process is not a new concept.

Re: link to docs, we're launching new docs and docs site in the next couple of weeks. storybook.js.org/docs will go to the same path as storybook.js.org/docs/basics/introduction. It doesn't go there right now because we haven't had a chance to update the legacy Gatsby 1 site.

[shilman]

Jiminy cricket!! I just released https://github.com/storybookjs/storybook/releases/tag/v6.0.0-rc.2 containing PR #11422 that references this issue. Upgrade today to try it out!

You can find this prerelease on the @next NPM tag.

Closing this issue. Please re-open if you think there's still more to do.