Primer Storybook

[broccolini]

Setting up Storybook for testing changes to Primer styles within the Primer repo. We have a couple of projects coming up and no easy way to view how changes to Primer look while we're working in the Primer repo. This was pretty quick to setup and since it's got a fair amount of support I figure it's worth testing. If it ends up not being the right thing for us that's fine, but hoping it can be a quick-fix solution to tide us over for the up-coming projects.

To test locally I think you just need to do an npm install, and npm start will run storybook.

Issue with Sass imports

• It can't currently resolve the paths for the sass imports, I can fix this by prefixing @import with a ~ but obviously that would conflict with primer-module-build.
  • @shawnbot suggested building a small "primer-path-resolver" node module, and mentioned he'd noticed some potential problems with the module build, the website starter, and npm 5.
  • I had the (probably bad) idea of making a separate sass file that lists the imports for all the modules prefixed with ~. That's not a great long-term fix but might tide us over for the short term.

Here's the docs on the custom webpack config I used to setup the sass loaders https://storybook.js.org/configurations/custom-webpack-config/

Future thoughts

• If we continued this we might want to consider where we keep and whether we want to automate generation of stories. It looks like when people use Storybook for react components they often keep the stories with the component code. Not sure what would be best for us but there is some overlap between the stories markup and the code examples in the docs.
• It's super easy to setup and run this locally, but long term we'd probably want a shareable url, we can do that via github pages but we might want staging urls when we're testing pre-releases

Story setup

If we can resolve the Sass import issue without too much trouble I'll add stories for the rest of the components. Happy to discuss story setup, but my general thoughts were we have 1 story per component, if that component has states then show them in the same view. I feel unsure about modifiers and elements so want to take a look at other storybook's. Here's a couple of examples:

• https://lonelyplanet.github.io/backpack-ui/
• http://jxnblk.com/rebass/stories/
• https://webedx-spark.github.io/coursera-ui/

cc @primer/ds-core

[shawnbot]

@broccolini I think I figured out the magical sass and postcss incantations:

• For sass-loader, we just needed put ../modules in the includePaths.
• For postcss, I created a "shim" config that imports primer-module-build/lib/.postcss.json, deletes the use key, and passes it through as plugins. (@jonrohan, I think that the postcss configuration format changed since we last worked on it!)

As of 75fb852, it works for me without any build errors!

[broccolini]

@shawnbot Yissss! Pulled it down and tested a sass changed and it worked! It's not super fast but does apply the changes without re-fresh. Not sure how fast it should be though. Still, it's fast enough and gives us a way to see style changes while we're making updates which is rad.

I'll work on adding stories for the rest of the components and will check in with you and @jonrohan about next steps.

[shawnbot]

It might be worth looking at whether Storybook has hooks for rebuilding assets outside of webpack, because I have a feeling that's what's so slow. But for now, onward and upward!

[broccolini]

It might be worth looking at whether Storybook has hooks for rebuilding assets outside of webpack, because I have a feeling that's what's so slow. But for now, onward and upward!

It was definitely faster before adding the sass loader etc. so yeah perhaps there's a better way to configure this. But happy to work with this for now :)

[broccolini]

@shawnbot and I had a chat and decided it's worth merging this in so we can all use it while adding new components, I'll make a tracking issue and continue to add the remaining stories.

In this pr I've added the following:

• Avatars
• Box
• Breadcrumb
• Buttons
• Flash alerts
• Typography utilities
• Blankslate
• Forms

It looks like this:

I also added an addon so we can have it say "Primer" in the top left and link back to primer.io.

Story structure

Some guidelines for the story structure:

• Call stories by their class name or modifier where possible
• Keep scales (such as type) on the same page
• Keep states of a component (such as buttons) on the same page,
• Have modifiers on separate pages
• Keep example copy simple (using the class name if possible).

You can, for the most part, copy+paste examples from the README docs, depending on their quality. Some tips in case you're not familiar with jsx:

• change class= => className, and "= > '
• every tag needs to be closed, so things like <input> => <input />
• if you have multiple elements in a story you need to wrap them in a <div>

I did not copy every example to a story if it was not part of the component or overkill on examples.

While I was doing this is highlighted some of the inconsistencies in our style guide, and how some examples are kind of muddled together or don't use great example copy, or are missing altogether. I started making a list to follow up but didn't want to make changes to readme's in this bigg-ish pr.

To do

(which @shawnbot has offered to help with)

• pull in the styleguide js bundle so examples that us js work too
• pull in octicons and figure out how to include them in examples

cc @primer/ds-core

[shawnbot]

💥

[shawnbot]

I added a real quick and dirty octicons story (cc @jonrohan) and the styleguide.js to the previews. FRIDAY MERGE PARTY!

👏 @broccolini 👏