design-system bugfixing.instructions.md

Bug Fixing Best Practices

1. Initial Analysis (Don't Jump to Solutions)

Parse the Support Request

• Extract key symptoms: What exactly is broken? What's the expected vs actual behavior?
• Identify affected components: Which UI elements, APIs, or features are involved?
• Classify the issue: Bug, feature request, configuration issue, or user error?
• Note reproduction context: Browser, environment, specific data, user actions

Understand the Technical Flow

• Trace the data path: From input → processing → output where does it break?
• Identify the domain: Styling, event handling, data transformation, rendering, etc.
• Consider scope: Is this a single component issue or systemic problem?

Communicate Initial Analysis

Always summarize your initial understanding and ask for confirmation:

• "Based on the bug report, I understand that [X problem] is happening when [Y scenario]. Is this correct?"
• "I think this affects [components/areas]. Should I investigate these areas first?"
• "This seems like a [bug type] issue. Does this match your expectations?"

Wait for confirmation before proceeding to investigation.

Create Story for Visual Inspection

After confirming the analysis, create a Storybook story to reproduce the bug:

• Create the story in the main/root component's stories file (e.g., RichSelect.stories.tsx, not SelectMenu.stories.tsx)
• This makes the bug reproduction more accessible and realistic for users
• Include problem summary in the story description
• Document expected vs actual behavior
• Provide clear test steps
• Make the bug visually apparent in the story
• Use the actual component API that users would interact with
• Create mock data that triggers the bug if needed

Template for bug reproduction story:

export const BugReproduction: Story = {
  name: 'Bug: [Brief Description]',
  args: {
    // Props that trigger the bug
  },
  parameters: {
    docs: {
      description: {
        story: `
**Problem Summary:** [What goes wrong]

**Expected Behavior:** [What should happen]

**Actual Behavior:** [What actually happens]

**How to Test:**
1. [Step by step instructions]
2. [To reproduce the issue]

        `,
      },
    },
  },
};