Skip to main content

Storybook Best Practices

Some best practices to create a positive DX.

Gesso Storybook - Production

Gesso Storybook - Staging

Storybook Organization​

  • Organization of Storybook is inline the atomic methodology, and is also mirrored by the Figma Gesso/Design System file.

  • When adding new items, it’s important to know what type of component/story is being added and where it should live within the SB structure.

Naming Stories​

  • The first — and usually only — story is called Default

What should/shouldn’t be in a Story​

  • Default - shows the component will all the props available as controls. Set some argument defaults that make the display useful, such as default text.

  • Don’t create extra stories for various use cases.

  • Don’t put other components in the story unless they are directly required.

    • Ex. Tab and TabContainer make sense together.

    • Ex. Ribbon using typography does not.

    • Don’t use extra grids, containers or typography wrappers, this indicates the component has functionality that it does not have. If those are required for the component to function, they should probably be built into the component.

    • Storybook is for technical examples, impressive showcases should be in the demo.

  • If a prop requires a full component be passed to it, provide a couple examples that can be selected via drop-down or radio button. See for how to do this.

Documenting Stories​

  • Description of component (top, under component name)

    • Under description include a “Material Reference” link if the component is based off of a material component.

  • Control Order

    • Visual/design controls at the top

    • Technical controls such as callbacks in the middle.

    • Deprecated controls at the bottom.

    • Control order is determined by the order of the stories Args, NOT argTypes

    • If you want to control the order but not set a default, just use ‘undefined’

  • Source code should not be handled by dedent or otherwise be created manually. It should always be left to automatic generation.

  • Controls for deprecated options should be marked as such, there is a deprecateStorybook helper function for this.

The Card story is a good example to follow for best practices if you are unsure.