component-documenter（组件记录器）

Component Documenter

Expert skill for creating comprehensive, user-friendly documentation for component libraries. Specializes in Storybook 9, README files, API documentation, usage guides, and migration documentation.

Technology Stack (2025)

Documentation Tools

• Storybook 9 - Component development platform
• MDX 3 - Markdown + JSX documentation
• TypeDoc - API documentation from TypeScript
• Docusaurus 3 / VitePress 2 - Documentation sites

Addons

• @storybook/addon-a11y - Accessibility testing
• @storybook/addon-essentials - Core addons
• @storybook/test - Testing integration
• storybook-dark-mode - Theme switching

Storybook 9 Configuration

Main Config

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite'

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@storybook/addon-interactions',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
  docs: {
    autodocs: 'tag',
  },
  typescript: {
    reactDocgen: 'react-docgen-typescript',
  },
}

export default config

Preview Config

// .storybook/preview.ts
import type { Preview } from '@storybook/react'
import '../src/styles/globals.css'

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
    docs: {
      toc: true,
    },
    a11y: {
      element: '#storybook-root',
      config: {},
      options: {},
    },
  },
  decorators: [
    (Story) => (
      <div className="p-4">
        <Story />
      </div>
    ),
  ],
}

export default preview

Story Examples

Component Story (CSF 3)

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { fn } from '@storybook/test'
import { Button } from './Button'

const meta = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['default', 'destructive', 'outline', 'secondary', 'ghost', 'link'],
      description: 'Visual style variant',
    },
    size: {
      control: 'select',
      options: ['default', 'sm', 'lg', 'icon'],
    },
    disabled: {
      control: 'boolean',
    },
  },
  args: {
    onClick: fn(),
  },
} satisfies Meta<typeof Button>

export default meta
type Story = StoryObj<typeof meta>

export const Default: Story = {
  args: {
    children: 'Button',
  },
}

export const Primary: Story = {
  args: {
    variant: 'default',
    children: 'Primary Button',
  },
}

export const Secondary: Story = {
  args: {
    variant: 'secondary',
    children: 'Secondary Button',
  },
}

export const Destructive: Story = {
  args: {
    variant: 'destructive',
    children: 'Delete',
  },
}

export const AllSizes: Story = {
  render: () => (
    <div className="flex items-center gap-4">
      <Button size="sm">Small</Button>
      <Button size="default">Default</Button>
      <Button size="lg">Large</Button>
    </div>
  ),
}

export const AllVariants: Story = {
  render: () => (
    <div className="flex flex-wrap gap-4">
      <Button variant="default">Default</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="link">Link</Button>
      <Button variant="destructive">Destructive</Button>
    </div>
  ),
}

export const WithIcon: Story = {
  args: {
    children: (
      <>
        <PlusIcon className="mr-2 h-4 w-4" />
        Add Item
      </>
    ),
  },
}

export const Loading: Story = {
  args: {
    disabled: true,
    children: (
      <>
        <LoaderIcon className="mr-2 h-4 w-4 animate-spin" />
        Loading...
      </>
    ),
  },
}

export const Disabled: Story = {
  args: {
    disabled: true,
    children: 'Disabled',
  },
}

MDX Documentation

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

<Meta of={ButtonStories} />

# Button

A versatile button component for user interactions.

## Overview

The Button component provides a consistent way to trigger actions throughout your application.

<Canvas of={ButtonStories.Default} />

## Props

<Controls />

## Variants

### Primary (Default)
Use for the main call-to-action on a page.

<Canvas of={ButtonStories.Primary} />

### Secondary
Use for secondary actions that complement the primary action.

<Canvas of={ButtonStories.Secondary} />

### Destructive
Use for dangerous or irreversible actions.

<Canvas of={ButtonStories.Destructive} />

## Sizes

<Canvas of={ButtonStories.AllSizes} />

## States

### Loading
Shows a loading indicator when an async action is in progress.

<Canvas of={ButtonStories.Loading} />

### Disabled
Prevents interaction when an action is not available.

<Canvas of={ButtonStories.Disabled} />

## Accessibility

- Uses semantic `<button>` element
- Keyboard accessible (Enter, Space)
- Focus visible indicator
- Disabled state properly communicated

## Best Practices

### Do
- Use primary buttons for main actions
- Keep button text concise (2-4 words)
- Use loading state for async actions

### Don't
- Use too many primary buttons on one page
- Use ambiguous labels like "Click here"
- Nest interactive elements inside buttons

README Templates

Library README

# @myorg/ui-library

Modern React 19 component library with TypeScript, Tailwind CSS 4, and full accessibility.

[![npm](https://img.shields.io/npm/v/@myorg/ui-library)](https://www.npmjs.com/package/@myorg/ui-library)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## Features

- **50+ Components** - Buttons, inputs, modals, and more
- **TypeScript First** - Full type safety
- **Accessible** - WCAG 2.1 AA compliant
- **Dark Mode** - Built-in theming
- **Tree-shakeable** - Import only what you need

## Installation

\`\`\`bash
npm install @myorg/ui-library
\`\`\`

## Quick Start

\`\`\`tsx
import { Button, Input } from '@myorg/ui-library'
import '@myorg/ui-library/styles.css'

function App() {
  return (
    <div>
      <Button variant="default">Click me</Button>
      <Input placeholder="Enter text..." />
    </div>
  )
}
\`\`\`

## Documentation

- [Storybook](https://storybook.myorg.com)
- [API Reference](https://docs.myorg.com/api)
- [Examples](https://github.com/myorg/ui-library/tree/main/examples)

## Requirements

- React 19+
- Tailwind CSS 4+

## License

MIT

Component README

# Button

Versatile button component with multiple variants, sizes, and states.

## Import

\`\`\`tsx
import { Button } from '@myorg/ui-library'
\`\`\`

## Usage

\`\`\`tsx
<Button variant="default" size="default">
  Click me
</Button>
\`\`\`

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | 'default' \| 'secondary' \| 'outline' \| 'ghost' \| 'link' \| 'destructive' | 'default' | Visual style |
| size | 'default' \| 'sm' \| 'lg' \| 'icon' | 'default' | Size |
| disabled | boolean | false | Disabled state |
| asChild | boolean | false | Render as child element |

## Accessibility

- Keyboard: Enter, Space to activate
- Screen reader: Announces as button
- Focus: Visible focus ring

API Documentation

JSDoc Comments

/**
 * Button component for user interactions.
 *
 * @example
 * ```tsx
 * <Button variant="default" onClick={() => alert('Clicked!')}>
 *   Click me
 * </Button>
 * ```
 */
export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>,
  VariantProps<typeof buttonVariants> {
  /**
   * Render button as child element using Radix Slot
   * @default false
   */
  asChild?: boolean
}

Migration Guide Template

# Migration Guide: v1 to v2

## Breaking Changes

### Button Component

#### Variant names changed

**Before (v1):**
\`\`\`tsx
<Button color="primary">Click</Button>
\`\`\`

**After (v2):**
\`\`\`tsx
<Button variant="default">Click</Button>
\`\`\`

## New Features

### Server Components Support

Components now support React 19 Server Components by default.

\`\`\`tsx
// Server Component (default)
import { Card } from '@myorg/ui-library'

// Client Component (when needed)
'use client'
import { Button } from '@myorg/ui-library'
\`\`\`

## Migration Steps

1. Update package: \`npm install @myorg/ui-library@2\`
2. Run codemod: \`npx @myorg/codemod v1-to-v2\`
3. Test application
4. Fix any remaining issues

Best Practices

Writing Style

1. Clear and Concise: Simple language
2. Examples First: Show code before explaining
3. Progressive Disclosure: Basic → Advanced
4. Consistent Formatting: Same patterns
5. Scannable: Headings, lists, tables

Accessibility Documentation

1. Document keyboard shortcuts
2. List ARIA attributes used
3. Describe screen reader behavior
4. Note focus management

When to Use This Skill

Activate when you need to:

• Write or update README files
• Create Storybook 9 stories
• Generate API documentation
• Write usage guides
• Create migration guides
• Document component props
• Write tutorials

Output Format

Provide:

1. Complete Documentation: README, stories, guides
2. Code Examples: Working, tested examples
3. Props Tables: Complete prop documentation
4. Accessibility Notes: Keyboard, ARIA, screen reader
5. Migration Guide: When updating versions