wonder-blocks: Skill for Claude Code

Storybook Best Practices

This guide covers conventions and best practices for creating Storybook stories (.stories.tsx or .stories.ts) in the Wonder Blocks design system.

TypeScript Types

✅ Define story types consistently (avoid any):

type StoryComponentType = StoryObj<typeof Component>;

export const Default: StoryComponentType = {
    args: {
        // props here
    },
};

Default Export Configuration

Meta Configuration

✅ Include all relevant meta properties:

export default {
    title: "Packages / ComponentName / SubComponent",
    component: ComponentName,
    subcomponents: {SubComponent1, SubComponent2}, // If applicable
    parameters: {
        componentSubtitle: (
            <ComponentInfo
                name={packageConfig.name}
                version={packageConfig.version}
            />
        ),
        chromatic: {
            disableSnapshot: false, // or true with reason
        },
    },
    argTypes: ComponentArgTypes,
    args: {
        // Default args for all stories
    },
    decorators: [
        // Optional decorators
    ],
} as Meta<typeof ComponentName>;

Key properties:

• title: Hierarchical path in Storybook sidebar
• component: The main component being documented
• subcomponents: Related components shown in docs
• parameters: Meta-level configuration (Chromatic, a11y, etc.)
• argTypes: Control definitions (usually imported from separate file)
• args: Default values applied to all stories
• decorators: Layout wrappers applied to all stories

Title Naming Convention

✅ Follow the hierarchy (avoid flat titles like "Button Stories"):

title: "Packages / Button / Button"
title: "Packages / Dropdown / SingleSelect"
title: "Packages / Button / Testing / Snapshots / ActivityButton"

Story Patterns

General Tips for Stories

✅ Follow these best practices when writing stories:

• The Default story should be interactive and work with the Storybook controls. Users should be able to modify props using the controls panel.
• Write stories for all possible prop combinations/states. This is very helpful for identifying that all states are styled correctly and any changes can be confirmed in visual regression tests.
• Disable Chromatic for stories that don't need visual regression tests (we have a limited number of Chromatic snapshots monthly). For example:
  • Stories already covered by another story
  • Stories for testing purposes only
  • Stories that don't have any visual differences from other stories
• Avoid including specific background colors in Stories so that we can dynamically change the background in Storybook using the Storybook background control in the toolbar. Let users control the background through Storybook's built-in controls.