storybook-component-documentation

仓库: thebushidocollective/han
安装量: 85
排名: #9314

安装

npx skills add https://github.com/thebushidocollective/han --skill storybook-component-documentation

Storybook - Component Documentation

Create comprehensive, auto-generated component documentation using Storybook's autodocs feature, MDX pages, and JSDoc comments.

Key Concepts Autodocs

Automatically generate documentation pages from stories:

const meta = { title: 'Components/Button', component: Button, tags: ['autodocs'], // Enable auto-documentation parameters: { docs: { description: { component: 'A versatile button component with multiple variants and sizes.', }, }, }, } satisfies Meta;

MDX Documentation

Create custom documentation pages with full control:

import { Meta, Canvas, Story, Controls } from '@storybook/blocks'; import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

Button Component

A versatile button component for user interactions.

Usage

Props

JSDoc Comments

Document component props for auto-extraction:

interface ButtonProps { /* * The button label text / label: string;

/* * Is this the principal call to action? * @default false / primary?: boolean;

/* * Button size variant * @default 'medium' / size?: 'small' | 'medium' | 'large'; }

Best Practices 1. Enable Autodocs

Add the autodocs tag to generate documentation automatically:

const meta = { component: Button, tags: ['autodocs'], parameters: { docs: { description: { component: 'Button component with primary and secondary variants.', }, }, }, } satisfies Meta;

  1. Document Component Descriptions

Provide clear, concise component descriptions:

const meta = { component: Tooltip, tags: ['autodocs'], parameters: { docs: { description: { component: ` Tooltip displays helpful information when users hover over an element. Supports multiple placements and can be triggered by hover, click, or focus.

Features

  • Multiple placement options
  • Customizable delay
  • Accessible (ARIA compliant)

  • Keyboard navigation support `.trim(), }, }, }, } satisfies Meta;

  • Document Story Variations

Add descriptions to individual stories:

export const WithIcon: Story = { args: { label: 'Download', icon: 'download', }, parameters: { docs: { description: { story: 'Buttons can include icons to enhance visual communication.', }, }, }, };

export const Loading: Story = { args: { loading: true, label: 'Processing...', }, parameters: { docs: { description: { story: 'Loading state disables interaction and shows a spinner.', }, }, }, };

  1. Use JSDoc for Type Documentation

Document props with JSDoc for rich documentation:

interface CardProps { /* * Card title displayed at the top / title: string;

/* * Optional subtitle below the title / subtitle?: string;

/* * Card variant affecting visual style * @default 'default' / variant?: 'default' | 'outlined' | 'elevated';

/* * Card content / children: React.ReactNode;

/* * Called when card is clicked * @param event - The click event / onClick?: (event: React.MouseEvent) => void;

/* * Elevation level (shadow depth) * @minimum 0 * @maximum 5 * @default 1 / elevation?: number; }

  1. Create Usage Examples

Show realistic usage examples in MDX:

import { Meta, Canvas, Story } from '@storybook/blocks'; import * as FormStories from './Form.stories';

<Meta of={FormStories} />

Form Component

Basic Usage

With Validation

```tsx import { Form } from './Form';

function MyForm() { return (

console.log(data)} validationSchema={schema} >
); }

Common Patterns

Component Overview Page

```mdx import { Meta, Canvas, Controls } from '@storybook/blocks'; import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

Button

Buttons trigger actions and events throughout the application.

Variants

Primary

Use primary buttons for the main call-to-action.

Secondary

Use secondary buttons for less important actions.

Props

Accessibility

  • Keyboard accessible (Enter/Space to activate)
  • Screen reader friendly
  • Focus visible indicator
  • Proper ARIA labels

Best Practices

  • Use clear, action-oriented labels
  • Provide sufficient click target size (min 44×44px)
  • Don't use more than one primary button per section
  • Include loading states for async actions

API Documentation const meta = { component: DataGrid, tags: ['autodocs'], parameters: { docs: { description: { component: 'Advanced data grid with sorting, filtering, and pagination.', }, }, }, argTypes: { data: { description: 'Array of data objects to display', table: { type: { summary: 'Array>' }, }, }, columns: { description: 'Column configuration', table: { type: { summary: 'ColumnDef[]' }, }, }, onRowClick: { description: 'Callback fired when a row is clicked', table: { type: { summary: '(row: any, index: number) => void' }, }, }, }, } satisfies Meta;

Migration Guides import { Meta } from '@storybook/blocks';

<Meta title="Guides/Migration/v2 to v3" />

Migration Guide: v2 → v3

Breaking Changes

Button Component

Before (v2): ```tsx

After (v3):

The type prop has been renamed to variant for consistency.

Input Component

Before (v2):

After (v3):

Error handling now uses an object to support additional metadata.

New Features Icon Support

Buttons now support icons:

Design Tokens

Document design tokens and theming:

```mdx import { Meta, ColorPalette, ColorItem, Typeset } from '@storybook/blocks';

<Meta title="Design System/Colors" />

Color Palette

Primary Colors

Typography

Advanced Patterns Inline Stories in MDX import { Meta, Story } from '@storybook/blocks'; import { Button } from './Button';

<Meta title="Components/Button/Examples" component={Button} />

Button Examples

Inline Story

{() => { const [count, setCount] = React.useState(0); return ( ); }}

Code Snippets import { Source } from '@storybook/blocks';

<Meta title="Guides/Setup" />

Installation

Install the component library:

<Source language="bash" code={` npm install @company/ui-components

or

yarn add @company/ui-components `} />

Then import components:

<Source language="tsx" code={` import { Button, Input, Form } from '@company/ui-components';

function App() { return (

); } `} />

Anti-Patterns ❌ Don't Skip Component Descriptions // Bad const meta = { component: Button, tags: ['autodocs'], } satisfies Meta;

// Good const meta = { component: Button, tags: ['autodocs'], parameters: { docs: { description: { component: 'Primary UI component for user actions.', }, }, }, } satisfies Meta;

❌ Don't Use Generic JSDoc Comments // Bad interface ButtonProps { / The label */ label: string; / The size */ size?: string; }

// Good interface ButtonProps { / Text displayed on the button */ label: string; / * Visual size of the button * @default 'medium' */ size?: 'small' | 'medium' | 'large'; }

❌ Don't Forget Story Descriptions // Bad export const Disabled: Story = { args: { disabled: true }, };

// Good export const Disabled: Story = { args: { disabled: true }, parameters: { docs: { description: { story: 'Disabled state prevents user interaction and dims the button visually.', }, }, }, };

Related Skills storybook-story-writing: Creating well-structured stories storybook-args-controls: Configuring interactive controls for props storybook-configuration: Setting up Storybook with proper documentation addons

← 返回排行榜