superset2/docs/.claude/instructions.md

Developer Portal Documentation Instructions

Core Principle: Stories Are the Single Source of Truth

When working on the Storybook-to-MDX documentation system:

ALWAYS fix the story first. NEVER add workarounds to the generator.

Why This Matters

The generator (scripts/generate-superset-components.mjs) should be lightweight - it extracts data from stories and passes it through. When you add special cases to the generator:

• It becomes harder to maintain
• Stories diverge from their docs representation
• Future stories need to know about generator quirks

When you fix stories to match the expected patterns:

• Stories work identically in Storybook and Docs
• The generator stays simple and predictable
• Patterns are consistent and learnable

Story Patterns for Docs Generation

Required Structure

// Use inline export default (NOT const meta = ...; export default meta)
export default {
  title: 'Components/MyComponent',
  component: MyComponent,
};

// Name interactive stories with Interactive prefix
export const InteractiveMyComponent: Story = {
  args: {
    // Default prop values
  },
  argTypes: {
    // Control definitions - MUST be at story level, not meta level
    propName: {
      control: { type: 'select' },
      options: ['a', 'b', 'c'],
      description: 'What this prop does',
    },
  },
};

For Components with Variants (size × style grids)

const sizes = ['small', 'medium', 'large'];
const variants = ['primary', 'secondary', 'danger'];

InteractiveButton.parameters = {
  docs: {
    gallery: {
      component: 'Button',
      sizes,
      styles: variants,
      sizeProp: 'size',
      styleProp: 'variant',
    },
  },
};

For Components Requiring Children

InteractiveIconTooltip.parameters = {
  docs: {
    // Component descriptors with dot notation for nested components
    sampleChildren: [{ component: 'Icons.InfoCircleOutlined', props: { iconSize: 'l' } }],
  },
};

For Custom Live Code Examples

InteractiveMyComponent.parameters = {
  docs: {
    liveExample: `function Demo() {
  return <MyComponent prop="value">Content</MyComponent>;
}`,
  },
};

For Complex Props (objects, arrays)

InteractiveMenu.parameters = {
  docs: {
    staticProps: {
      items: [
        { key: '1', label: 'Item 1' },
        { key: '2', label: 'Item 2' },
      ],
    },
  },
};

Common Issues and How to Fix Them (in the Story)

Issue	Wrong Approach	Right Approach
Component not generated	Add pattern to generator	Change story to use inline export default
Control shows as text instead of select	Add special case in generator	Add argTypes with control: { type: 'select' }
Missing children/content	Modify StorybookWrapper	Add parameters.docs.sampleChildren
Gallery not showing	Add to generator output	Add parameters.docs.gallery config
Wrong live example	Hardcode in generator	Add parameters.docs.liveExample

Files

• Generator: docs/scripts/generate-superset-components.mjs
• Wrapper: docs/src/components/StorybookWrapper.jsx
• Output: docs/developer_docs/components/
• Stories: superset-frontend/packages/superset-ui-core/src/components/*/