GAIA UI comes with Storybook, an open-source tool for developing UI (User Interface) components in isolation. It serves as a sandbox environment where developers can create, view, and interact with UI components independently from the larger application. With this tool, we are documenting the web components available for use, providing a structured and interactive way to showcase components, their variations, and behaviors. Using Storybook for documentation has several advantages:
Visual Showcase: Storybook generates a visual catalog of UI components, displaying various states, props, and interactions. This makes it easier for developers, designers, and stakeholders to understand how each component works and how it appears in different scenarios.
Isolated Environment: Components can be developed and documented in isolation, allowing for focused attention and detailed documentation without the distraction of the larger application or dependencies.
Accessibility Testing: Storybook can be used to test and document component accessibility by providing features and tools for analyzing and improving accessibility within each component.
Interactive Exploration: Users can interact with the documented components directly within Storybook, trying out different configurations, inputs, and states to understand their behavior and functionality better.
Documentation Generation: Storybook can be configured to automatically generate documentation based on code comments, prop definitions, and other metadata, simplifying the process of keeping component documentation up-to-date.
You can document and test your components by adding more stories to the the src/stories folder
For more information on how to use Storybook, go to https://storybook.js.org/docs/get-started/whats-a-story
Storybook comes with a built-in development server featuring everything you need for project development. Running the storybook
command will start the local development server, output the address for you, and automatically open the address in a new browser tab where a welcome screen greets you.
pnpm run storybook
A story captures the rendered state of a UI component. Developers write multiple stories per component that describe all the “interesting” states a component can support.
The CLI created example components that demonstrate the types of components you can build with Storybook: Button, Header, and Page.
Each example component has a set of stories that show the states it supports. You can browse the stories in the UI and see the code behind them in files that end with .stories.js
or .stories.ts
. The stories are written in Component Story Format (CSF)--an ES6 modules-based standard--for writing component examples.
Let’s start with the Button
component. A story is a function that describes how to render the component in question. Here’s how to render Button
in the “primary” state and export a story called Primary
.
import type { Meta, StoryObj } from '@storybook/react'; import { Button } from './Button'; const meta: Meta<typeof Button> = { component: Button, }; export default meta; type Story = StoryObj<typeof Button>; /* *👇 Render functions are a framework specific feature to allow you control on how the component renders. * See https://storybook.js.org/docs/api/csf * to learn how to use render functions. */ export const Primary: Story = { render: () => <Button primary label="Button" />, };
View the rendered Button
by clicking on it in the Storybook sidebar.
The above story definition can be further improved to take advantage of Storybook’s “args” concept. Args describes the arguments to Button in a machine-readable way. It unlocks Storybook’s superpower of altering and composing arguments dynamically.
import type { Meta, StoryObj } from '@storybook/react'; import { Button, ButtonProps } from './Button'; const meta: Meta<typeof Button> = { component: Button, }; export default meta; type Story = StoryObj<typeof Button>; export const Primary: Story = { args: { primary: true, label: 'Button', }, };
Both story examples render the same thing because Storybook feeds the given args
property into the story during render. But you get timesaving conveniences with args:
Button
s callbacks are logged into the Actions tab. Click to try it.Button
s arguments are dynamically editable in the Controls tab. Adjust the controlsStorybook makes it easy to work on one component in one state (aka a story) at a time. When you edit the Button code or stories, Storybook will instantly re-render in the browser. No need to refresh manually.
Update the label
of the Primary
story, then see your change in Storybook.
Stories are also helpful for checking that UI continues to look correct as you make changes. The Button
component has four stories that show it in different use cases. View those stories now to confirm that your change to Primary
didn’t introduce unintentional bugs in the other stories.
Checking component’s stories as you develop helps prevent accidental regressions. Tools that integrate with Storybook can automate this for you.