Tooling: Add Storybook for client/*

[okmttdhr]

Overview

Currently, we have some Storybooks under the packages directory (e.g., tour-kit, components), but no Storybook for under the client directory.

I would suggest that we can have Storybook under the client directory. This way, we can add a "story" for every piece of UI (for components/pages/etc).

Context

Without Storybook, we need to run a local server when developing UI-related things, which is slow to debug and not easy to test all the conditions.

I would be happy to be able to develop based on Storybook at a larger granularity (e.g., per page) without limiting Storybook to so-called "components" only. https://storybook.js.org/docs/react/get-started/why-storybook#build-uis-in-isolation

There are several advantages to using Storybook for UI development.

• Rapid development: Since components are isolated, developers can quickly prototype and iterate on their designs without waiting for a full build and refresh cycle, which can be time-consuming with a local server.
• Organizing UI: Complex conditions can be organized and developed by component, which is helpful in finding, understanding, testing, and debugging UI patterns
• Storybook makes component testing easy with its play function, addon, etc. https://storybook.js.org/docs/react/writing-tests/introduction

Tasks

Some tasks may be better isolated as another task.

• CI
  • Run build on PR
  • Deploy to GitHub pages (or somewhere)
    • it'd be nice to have Storybook deployed for each PR with GitHub pages or something.
• Tips & Documentation
  • Update
    • https://github.com/Automattic/wp-calypso/blob/trunk/docs/components.md
    • https://github.com/Automattic/wp-calypso/blob/trunk/docs/component-libraries.md
  • General guidelines to use Storybook (how to run it? how to write a story?)
  • Direction on how best to use Storybook.
  • Retire Live Docs in devdocs https://wpcalypso.wordpress.com/devdocs/design
• Add some stories
  • There are several stories that I would like to add as examples. The settings in preview.js might change accordingly.
  • A component that uses redux store Add a sample component to the root Storybook (component with redux state) #75942
  • A component from another package Add a sample component to the root Storybook (component from another package) #75943
  • A component that has images
• Migrate to Storybook 7.0
• Addons
  • addon-essentials
  • Figma integration
  • Accessibility addon.

Related Resources

• Heads-up: The “Universal” Storybook Project for Calypso – codep2 p7H4VZ-4gp-p2
• Which Button should I use when working with the Calypso repo? pdKhl6-1hu-p2
  • Create a page listing all component libraries and why you might use them #71143
• Slack conversation p1680657358609729-slack-C03DY3RJ5
• Test Diversification: UI Component Tests – Software Testing p6fDka-Ol-p2
  • https://github.com/WordPress/gutenberg/blob/trunk/test/storybook-playwright/README.md

[simison]

Noting that this would replace https://wpcalypso.wordpress.com/devdocs/design

In addition to client, you should also include;

• Components from @wordpress/components (rendered in Calypso context)
• Components from @automattic/components (from packages directory in Calypso)

cc @Automattic/team-calypso who should probably own something like this.

[noahtallen]

I think we should add storybook to the top level of the repo, and then add everything under it (including the existing storybook examples in packages, and anything we want to add from the client). Step one would probably be to get the existing packages into it

Devdocs migration is definitely promising (for having one less thing to maintain), but I could see it being tough to prioritize in the near term for our team

[tyxla]

Thanks for opening the discussion up, this is a neat idea! 💯 We've already been using Storybook in many places in Calypso and Gutenberg, so I'd love to see unification in that area.

I agree that a single top-level storybook that encompasses the entire repo would be best.

As Noah said, we could start with the existing storybook instances and gradually migrate everything away from the existing devdocs. It doesn't have to be one big step, but rather many incremental ones.

This isn't something our team prioritizes (meaning, actively works on) right now, but we're happy to help with reviews, guidance, and discussion, and any other help needed.

[danielbachhuber]

cc @javierarce if you have any opinions about how Storybook for Calypso might work

[javierarce]

Besides what others have mentioned on this thread and from a designer perspective, it would be great to enable the Figma integration and the Accessibility addon.

And I wonder if it would make sense to use Storybook Composition to integrate other storybooks like Gutenberg or Jetpack.

[danielbachhuber]

@okmttdhr Might be worth blogging about this on calypsop2 too?

[tyxla]

I'd say migrating devdocs to use Storybook makes sense as part of the action plan listed above. Could be split into multiple steps to cover all areas.

[noahtallen]

Migrating to Storybook 7 would be awesome if anyone has time for it -- it more explicitly supports React 18, which would be nice to have for #77046. I temporarily bumped the packages in #77121, but I think the changes required to support it are a little more broad to do simultaneously. We have some workarounds in our storybook configs we can probably remove now too.

I'll probably get to it eventually, but it'll take some time! :)

[noahtallen]

Actually, it was a lot easier than I expected! I added a few options which make the initial boot faster, though it seems to load modules on demand. Storybook 7 is working pretty well in #77121, with only a couple tweaks needed.

[tyxla]

@noahtallen I don't think this was closed on purpose, so reopening.

[noahtallen]

Indeed, I think GitHub must have auto-closed it.