Skip to main content

How to properly write a Story for The Wall

Introduction​

A story captures the rendered state of a UI component. It's an object with annotations that describe the component's behavior and appearance given a set of arguments.

This object describes how to render a component. You can have multiple stories per component, and those stories can build upon one another.

These guidelines ensure consistency and quality when writing stories for components in Storybook. They follow the official Storybook documentation and include additional best practices for Figma validation and edge case coverage.

⚠️ 1. Cover Edge Cases​

Stories should represent not only the happy paths, but also edge cases. Aim to have meaningful coverage.

  • Include stories for:

    • Long text (overflow scenarios)
    • Empty states
    • Error states
    • Loading states
    • Boolean prop combinations (e.g., disabled + selected)
    • Non trivial state: when the code has a specific combination of prop resulting in a different rendering effects. Nonetheless, aim for stories that cover the basic features. Stories need to be cost effective, as they need to be maintained, reviewed, updated, it includes visual tests, etc.

  • If any of these states are not in Figma, notify the design team in order to clarify the component usage, so they can, if necessary, create figma specs for said case.

✅ 2. One Figma Scenario = One Story​

Each visual scenario defined in Figma must be represented as an individual Story in Storybook.

  • Validate your component against the Figma's component page.
  • Create a Story for each scenario shown in Figma.
  • If a scenario exists in Figma, it must have a corresponding Story.

🧱 3. Story Structure​

Follow this standard structure for writing stories:

export default {
  title: "components/ComponentName",
  component: ComponentName,
  args: {
    // list of default props for the component
  },
  argTypes: {
    // list of argument and control types for each prop
  },
} satisfies Meta<typeof ComponentName>;

For each story scenario, use the following structure:

type Story = StoryObj<typeof ComponentName>;

export const Default: Story = {
  parameters: {
    design: {
      type: "figma",
      url: "https://www.figma.com/design/figma-default-scenario-link",
    },
  },
};

export const ScenarioOneName: Story = {
  args: {
    propName: "some value for the prop",
  },
  parameters: {
    design: {
      type: "figma",
      url: "https://www.figma.com/design/figma-scenario-one-name-link",
    },
  },
};

Notes:​

  • Use satisfies Meta<typeof ComponentName> for type safety.
  • Ensure design.url is accurate and points to the corresponding Figma scenario.
  • Make sure all additional scenarios are declared similarly to Default.
  • Use the args object to set default values for props that are common across multiple stories.
  • Aim to achieve the highest coverage possible for the component.
  • Keep in mind the accessibility of the component. When adding a component story, ensure that it follows the accessibility guidelines.

📌 Final Checks​

Before pushing your stories please make sure of the following:

  • All scenarios from Figma are covered.
  • All major and edge states are represented.
  • Component behaves as expected with the given props.
  • Code follows the structural template provided.
  • Figma links are correct.

Keeping stories aligned with design and user expectations leads to more reliable and useful component documentation. Thanks for contributing to our design system! 🚀