[RFC] Utilize Storybook for UI development

[david-chalk]

NOTE: this issue tracks the discussion around the decision to even do this. This is not the implementation issue.

Situation

The FusionAuth React SDK is a React npm package that offers both UI components with preconfigured functionality and non-UI components that offer non-visible functionality. There is currently no way to view the visible UI components.

Challenge

It is difficult to work on the visual styles of the UI components because there is no way to view them.

Question

How can we view the UI components in order to get visual feedback on style changes?

Answer

Let's use Storybook. It is the industry standard for viewing UI components in isolation and as such is well-supported with lots of documentation and resources.

Rendering components in isolation is particularly necessary for UI libraries like the FusionAuth React SDK because we don't have a host app to run them in. Components being isolated also forces developers to make sure they don't have any hidden dependencies to work correctly.

Aside from giving developers a place to develop UI components, Storybook also acts as interactive documentation for these components. Developers (and others) can interactively change props and components update to reflect their changes.

FusionAuth could choose to host the Storybook publicly so developers can view the components without even pulling down and running the project themselves. Services like Chromatic make hosting Storbook instances extremely easy and quick.

We can also "compose" Storybooks enabling us to have one place to view the components for every FusionAuth SDK. This would be a future enhancement past this one however.

Example Storybooks

• IBM's Carbon Design System
• Microsoft's Fluent UI Design System
• Adobe's Spectrum Design System

What's the lift? 💪

Integrating Storybook is fairly simple. And because we don't have a ton of components, it shouldn't take very long to make a "Story" for each component.

Estimate: 1 developer 1 day

[david-chalk]

Requesting comments and thoughts from @mooreds.

[michaelyons]

Requesting comments and thoughts from @lyleschemmerling

[lyleschemmerling]

Is the concern just that we do not have a spot to do development in the repo?

When we worked on this in the past we did so while simultaneously working in the https://github.com/FusionAuth/fusionauth-example-react-sdk and pulling in those updates. Using that both provides a place to validate the look and feel when used inside of a real application and to verify that the behavior of the sdk is working as intended.

Will doing that cover us for now?

[david-chalk]

@lyleschemmerling

Is the concern just that we do not have a spot to do development in the repo?

Yeah! There's no way to preview the components while developing them.

When we worked on this in the past we did so while simultaneously working in the https://github.com/FusionAuth/fusionauth-example-react-sdk and pulling in those updates. Using that both provides a place to validate the look and feel when used inside of a real application and to verify that the behavior of the sdk is working as intended.

Will doing that cover us for now?

That works but is definitely a slower process that limits speed of iterations. Developers and testers need to utilize two separate applications in order to verify even small changes to components.

Regarding "Using that... provides a place to validate the look and feel when used inside of a real application", it's a best practice to test components in isolation so we can confirm that there's no application styles or functionality leaking into the components.

Storybook also serves as a way to document the available components: it gives the components a place to live and be viewed. Right now, there's no place to "see" FusionAuth's components which is a little odd for a UI library. Developers may be less inclined to use the package if they can't see what's in it.

For example: as a web developer, it would be off-putting to to have to download, setup, and run an example application using MaterialUI in order to see what MaterialUI has to offer. Especially if you then have to go digging around the app to find all the components. That's not a smooth process just to check out a few buttons.

Storybook is a pretty quick win that solves a lot of those issues by itself, though we'd have to have a hosted instance to get the benefit of letting developers easily see what's in the library. As mentioned in the RFC, tools like Chromatic make that process extremely easy.

[lyleschemmerling]

Ultimately this sdk has 3 components at the moment, and they are mainly just wrappers around a button element that performs a redirect. I'm not convinced that we need to bring in Storybook to facilitate these. If we need to be able to render these in-repo then maybe we can do something simpler like just stand up a very minimal react shell app. We should aim for options that offer the lowest complexity and overhead.