grafana/contribute/style-guides/storybook.md

Storybook

Storybook is a tool which we use to manage our design system and the components which are a part of it. Storybook consists of stories: each story represents a component and a case in which it is used. To show a wide variety of use cases is good both documentation wise and for troubleshooting -- it might be possible to reproduce a bug for an edge case in a story.

Storybook is:

• A good way to publish our design system with its implementations
• Used as a tool for documentation
• Used for debugging and displaying edge cases

How to create stories

Stories for a component should be placed next to the component file. The Storybook file requires the same name as the component file. For example, a story for SomeComponent.tsx will have the file name SomeComponent.story.tsx. If a story should be internal, not visible in production, name the file SomeComponent.story.internal.tsx.

Writing stories

When writing stories, we use the CSF format. For more in-depth information on writing stories, see Storybook’s documentation on writing stories.

With the CSF format, the default export defines some general information about the stories in the file:

• title: Where the component is going to live in the hierarchy
• decorators: A list which can contain wrappers or provide context, such as theming

// In MyComponent.story.tsx

import MyComponent from './MyComponent';

export default {
  title: 'General/MyComponent',
  component: MyComponent,
  decorators: [ ... ],
}

When it comes to writing the actual stories, you continue in the same file with named exports. The exports are turned into the story name.

// Will produce a story name “some story”
export const someStory = () => <MyComponent />;

If you want to write cover cases with different values for props, then using knobs is usually enough. You don’t need to create a new story. This will be covered further down.

Categorization

We currently have these categories:

• Docs Overview - Guidelines and information regarding the design system
• Forms - Components commonly used in forms such as different kind of inputs
• General - Components which can be used in a lot of different places
• Visualizations - Data visualizations
• Panel - Components belonging to panels and panel editors

Writing MDX documentation

An MDX file is basically a markdown file with the possibility to add jsx. These files are used by Storybook to create a “docs” tab.

Link the MDX file to a component’s stories

To link a component’s stories with an MDX file you have to do this:

// In TabsBar.story.tsx

import { TabsBar } from "./TabsBar";

// Import the MDX file
import mdx from "./TabsBar.mdx";

export default {
  title: "General/Tabs/TabsBar",
  component: TabsBar,
  parameters: {
    docs: {
      // This is the reference required for the MDX file
      page: mdx,
    },
  },
};

MDX file structure

There are some things that the MDX file should contain:

• When and why the component should be used
• Best practices - dos and don’ts for the component
• Usage examples with code. It is possible to use the Preview element to show live examples in MDX
• Props table. This can be generated by doing the following:

// In MyComponent.mdx

import { Props } from "@storybook/addon-docs/blocks";
import { MyComponent } from "./MyComponent";

<Props of={MyComponent} />;

MDX file without a relationship to a component

An MDX file can exist by itself without any connection to a story. This can be good for writing things such as a general guidelines page. Two things are required for this to work:

• The file needs to be named *.story.mdx
• A Meta tag must exist that says where in the hierarchy the component lives. It can look like this:

<Meta title="Docs Overview/Color Palettes"/>

# Guidelines for using colors

...

You can add parameters to the Meta tag. This example shows how to hide the tools:

<Meta title="Docs Overview/Color Palettes" parameters={{ options: { isToolshown: false }}}/>

# Guidelines for using colors

...

Documenting component properties

A quick way to get an overview of what a component does is by looking at its properties. That's why it is important that we document these in a good way.

Comments

When writing the props interface for a component, it is possible to add a comment to that specific property, which will end up in the Props table in the MDX file. The comments are generated by react-docgen and are formatted by writing /** */.

interface MyProps {
  /** Sets the initial values, which are overridden when the query returns a value*/
  defaultValues: Array<T>;
}

Knobs

Knobs is an addon to Storybook which can be used to easily switch values in the UI. A good use case for it is to try different props for the component. Using knobs is easy. Grafana is set up so knobs can be used straight out of the box. Here is an example of how you might use it.

// In MyComponent.story.tsx

import { number, text } from "@storybook/addon-knobs";

export const basicStory = () => (
  <MyComponent
    max={number("Max value", 10)}
    min={number("Min value", -10)}
    title={text("Title", "Look at the value!")}
  />
);

The general convention is that the first parameter of the knob is its name and the second is the default value. There are some more types:

Knob	Description
text	Any text field
number	Any number input. Also available as range
boolean	A switch between true/false
color	Color picker
object	JSON input or array. Good to use if the property requires more complex data structures.
array	Array of strings separated by a comma
select	Select a value from an options object. Good for trying different test cases.
options	Configurable UI for selecting a range of options
files	File selector
date	Select date as stringified Unix timestamp
button	Has a handler which is called when clicked

Best practices

• When creating a new component or writing documentation for an existing one, always cover the basic use case it was intended for with a code example.
• Use stories and knobs to create edge cases. If you are trying to solve a bug, try to reproduce it with a story.
• Do not create stories in the MDX, always create them in the *.story.tsx file.