Component Documenter

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

Core Capabilities

1. README Documentation

• Professional project overview
• Installation instructions
• Quick start guides
• Feature highlights
• Usage examples
• Configuration options
• Contributing guidelines
• Troubleshooting sections

2. Storybook Integration

• Story creation for all components
• Controls/Args documentation
• Multiple story variants
• Interactive examples
• MDX documentation pages
• Accessibility addon integration
• Visual regression testing setup

3. API Documentation

• Props interface documentation
• Type definitions
• Method signatures
• Event handlers
• Return types
• Default values
• Required vs optional props

4. Usage Guides

• Getting started tutorials
• Common use cases
• Best practices
• Code examples
• Do's and Don'ts
• Accessibility guidelines
• Performance tips

5. Migration Guides

• Version upgrade guides
• Breaking changes documentation
• Migration steps
• Codemod scripts
• Before/after examples
• Deprecation notices

6. Component Examples

• Basic usage examples
• Advanced patterns
• Edge case handling
• Integration examples
• Real-world scenarios
• Interactive demos

Workflow

Phase 1: Documentation Planning

1. Understand Audience

   • Developers using the library
   • Contributors to the project
   • Designers implementing specs
   • Stakeholders reviewing features

2. Identify Content Needs

   • What needs documentation?
   • What's missing in current docs?
   • Common questions/issues
   • User pain points

3. Choose Documentation Types

   • README for project overview
   • Storybook for component demos
   • JSDoc for inline code docs
   • Markdown files for guides
   • TypeScript for type docs

Phase 2: Writing Documentation

1. Create README

   • Clear project description
   • Installation steps
   • Quick start example
   • Links to detailed docs

2. Write Storybook Stories

   • Default story for each component
   • Variant stories (sizes, colors, states)
   • Interactive controls
   • Accessibility checks

3. Document API

   • Props with types
   • Usage examples
   • Edge cases
   • Return values

4. Create Usage Guides

   • Step-by-step tutorials
   • Common patterns
   • Integration examples
   • Best practices

Phase 3: Maintenance

1. Keep Updated

   • Update with code changes
   • Add new examples
   • Document breaking changes
   • Fix outdated content

2. Gather Feedback

   • User questions
   • GitHub issues
   • Support requests
   • Usage analytics

3. Continuous Improvement

   • Add missing examples
   • Clarify confusing sections
   • Improve searchability
   • Update screenshots

README Templates

Library README

# @myorg/ui-library

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

[![npm version](https://badge.fury.io/js/%40myorg%2Fui-library.svg)](https://www.npmjs.com/package/@myorg/ui-library)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🎨 **50+ Components** - Buttons, inputs, modals, and more
- 🎯 **TypeScript First** - Full type safety out of the box
- ♿ **Accessible** - WCAG AA compliant, keyboard navigation
- 🌗 **Dark Mode** - Built-in theming system
- 📦 **Tree-shakeable** - Import only what you need
- 🎭 **Customizable** - Tailwind CSS and CSS variables
- 📱 **Responsive** - Mobile-first design

## Installation

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

Quick Start

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

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

Documentation

• 📚 Full Documentation
• 🎨 Storybook
• 📝 API Reference
• 🚀 Examples

Components

Form Components

• Button - Buttons in various styles
• Input - Text inputs with validation
• Select - Dropdown selection
• Checkbox - Checkbox input

Layout Components

• Card - Content container
• Stack - Flexbox layout
• Grid - Grid layout

Feedback Components

• Alert - Alert messages
• Toast - Toast notifications
• Modal - Modal dialogs

Usage

Basic Example

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

function MyComponent() {
  return (
    <Button
      variant="primary"
      size="lg"
      onClick={() => console.log('Clicked!')}
    >
      Click me
    </Button>
  )
}

With TypeScript

import { Button, type ButtonProps } from '@myorg/ui-library'

interface MyButtonProps extends ButtonProps {
  customProp?: string
}

function MyButton({ customProp, ...props }: MyButtonProps) {
  return <Button {...props} />
}

Theming

import { ThemeProvider } from '@myorg/ui-library'

function App() {
  return (
    <ThemeProvider theme="dark">
      <YourApp />
    </ThemeProvider>
  )
}

Configuration

Tailwind CSS

Add to your tailwind.config.js:

module.exports = {
  content: [
    './node_modules/@myorg/ui-library/dist/**/*.{js,ts,jsx,tsx}',
  ],
  presets: [
    require('@myorg/ui-library/tailwind-preset')
  ],
}

CSS Variables

Customize colors in your CSS:

:root {
  --color-primary: 59 130 246;
  --color-secondary: 139 92 246;
  --radius: 0.5rem;
}

Browser Support

• Chrome (last 2 versions)
• Firefox (last 2 versions)
• Safari (last 2 versions)
• Edge (last 2 versions)

Contributing

We welcome contributions! Please see CONTRIBUTING.md.

License

MIT © Your Organization

Credits

Built with:

• React
• TypeScript
• Tailwind CSS
• Radix UI

### Component README
```markdown
# Button

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

## Import

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

Usage

<Button variant="primary" size="md">
  Click me
</Button>

Props

Prop	Type	Default	Description
variant	'primary' | 'secondary' | 'outline' | 'ghost'	'primary'	Visual style variant
size	'sm' | 'md' | 'lg'	'md'	Button size
disabled	boolean	false	Disables button
loading	boolean	false	Shows loading state
onClick	(e: MouseEvent) => void	-	Click handler
children	ReactNode	-	Button content

Examples

Variants

<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>

Sizes

<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

States

<Button disabled>Disabled</Button>
<Button loading>Loading</Button>

With Icons

<Button>
  <Icon name="plus" />
  Add Item
</Button>

Accessibility

• Uses semantic <button> element
• Keyboard accessible (Enter, Space)
• Focus visible indicator
• Disabled state prevents interaction
• ARIA attributes when needed

Best Practices

✅ Do:

• Use semantic variants (primary for main action)
• Provide clear button text
• Use loading state for async actions
• Add icons for clarity when helpful

❌ Don't:

• Use too many primary buttons on one page
• Make buttons too small (min 44x44px)
• Use only icons without labels for important actions
• Nest interactive elements inside buttons

## Storybook Stories

### Basic Component Story
```typescript
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { Button } from './Button'

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'outline', 'ghost'],
      description: 'Visual style variant',
    },
    size: {
      control: 'select',
      options: ['sm', 'md', 'lg'],
    },
    disabled: {
      control: 'boolean',
    },
    onClick: { action: 'clicked' },
  },
}

export default meta
type Story = StoryObj<typeof Button>

export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Click me',
  },
}

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

export const Sizes: Story = {
  render: () => (
    <div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
    </div>
  ),
}

export const WithIcon: Story = {
  args: {
    children: (
      <>
        <PlusIcon />
        Add Item
      </>
    ),
  },
}

export const Loading: Story = {
  args: {
    loading: true,
    children: 'Loading...',
  },
}

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

MDX Documentation Story

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

<Meta of={ButtonStories} />

# Button

Versatile button component for user interactions.

## Overview

The Button component provides a consistent way to trigger actions throughout your application. It supports multiple variants, sizes, and states.

<Canvas of={ButtonStories.Primary} />

## Props

<Controls />

## Variants

Buttons come in four visual styles to indicate different levels of emphasis.

### Primary

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} />

### Outline

Use for tertiary actions or to reduce visual weight.

<Canvas of={ButtonStories.Outline} />

### Ghost

Use for the least visual weight, often in toolbars or menus.

<Canvas of={ButtonStories.Ghost} />

## Sizes

Three sizes are available to fit different contexts.

<Canvas of={ButtonStories.Sizes} />

## States

### Loading

Shows a spinner when an async action is in progress.

<Canvas of={ButtonStories.Loading} />

### Disabled

Prevents interaction when an action is not available.

<Canvas of={ButtonStories.Disabled} />

## With Icons

Icons can be added to provide visual clarity.

<Canvas of={ButtonStories.WithIcon} />

## Accessibility

- Keyboard accessible with Enter and Space keys
- Focus indicator visible
- Disabled state properly communicated to screen readers
- Loading state announced to screen readers

## Best Practices

### ✅ Do

- Use primary buttons for main actions
- Keep button text concise (2-4 words)
- Use loading state for async actions
- Ensure minimum touch target size (44x44px)

### ❌ Don't

- Use too many primary buttons
- Use ambiguous labels like "Click here"
- Nest interactive elements
- Make buttons too small

## Examples

### Form Submission

```tsx
function Form() {
  const [loading, setLoading] = useState(false)

  const handleSubmit = async () => {
    setLoading(true)
    await submitForm()
    setLoading(false)
  }

  return (
    <Button
      variant="primary"
      loading={loading}
      onClick={handleSubmit}
    >
      Submit
    </Button>
  )
}

Button Group

<div className="flex gap-2">
  <Button variant="primary">Save</Button>
  <Button variant="outline">Cancel</Button>
</div>

### Storybook Configuration
```typescript
// .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-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-a11y', // Accessibility addon
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
  docs: {
    autodocs: 'tag',
  },
}

export default config

API Documentation

JSDoc Comments

/**
 * Button component for user interactions.
 *
 * @example
 * ```tsx
 * <Button variant="primary" onClick={() => alert('Clicked!')}>
 *   Click me
 * </Button>
 * ```
 */
export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  /**
   * Visual style variant
   * @default 'primary'
   */
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost'

  /**
   * Button size
   * @default 'md'
   */
  size?: 'sm' | 'md' | 'lg'

  /**
   * Disables the button and prevents interaction
   * @default false
   */
  disabled?: boolean

  /**
   * Shows loading spinner and disables interaction
   * @default false
   */
  loading?: boolean

  /**
   * Button content
   */
  children: ReactNode

  /**
   * Click event handler
   */
  onClick?: (event: MouseEvent<HTMLButtonElement>) => void
}

TypeDoc Generation

// typedoc.json
{
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "plugin": ["typedoc-plugin-markdown"],
  "excludePrivate": true,
  "excludeProtected": true,
  "excludeExternals": true,
  "readme": "README.md",
  "categorizeByGroup": true,
  "categoryOrder": [
    "Components",
    "Hooks",
    "Utilities",
    "Types"
  ]
}

Migration Guides

Version Upgrade Guide

# Migration Guide: v1.x to v2.0

## Breaking Changes

### 1. Button Component

#### Removed `color` prop

The `color` prop has been replaced with `variant` for clearer semantics.

**Before (v1.x):**
```tsx
<Button color="blue">Click me</Button>

After (v2.0):

<Button variant="primary">Click me</Button>

Renamed isLoading to loading

For consistency across components.

Before:

<Button isLoading>Submit</Button>

After:

<Button loading>Submit</Button>

2. Input Component

Changed validation prop structure

Validation props are now grouped in a single validation object.

Before:

<Input required error="Required field" />

After:

<Input validation={{ required: true, error: "Required field" }} />

New Features

ThemeProvider

v2.0 introduces a new theming system with light/dark mode support.

import { ThemeProvider } from '@myorg/ui-library'

function App() {
  return (
    <ThemeProvider>
      <YourApp />
    </ThemeProvider>
  )
}

Compound Components

Many components now support compound component patterns.

<Select>
  <Select.Trigger>Choose option</Select.Trigger>
  <Select.Content>
    <Select.Item value="1">Option 1</Select.Item>
    <Select.Item value="2">Option 2</Select.Item>
  </Select.Content>
</Select>

Deprecations

Alert Component

The type prop is deprecated in favor of variant.

// Deprecated (still works but will warn)
<Alert type="error">Error message</Alert>

// Recommended
<Alert variant="error">Error message</Alert>

Automated Migration

We provide a codemod to automate most changes:

npx @myorg/ui-library-codemod v1-to-v2 src/

Step-by-Step Migration

1. Update package version

   npm install @myorg/ui-library@2.0.0
   

2. Run codemod

   npx @myorg/ui-library-codemod v1-to-v2 src/
   

3. Review changes

   • Check git diff
   • Test your application
   • Fix any remaining issues

4. Update imports (if needed)

   // Some components moved
   import { Toast } from '@myorg/ui-library/feedback'
   

5. Test thoroughly

   • Run your test suite
   • Manual QA testing
   • Check for console warnings

Need Help?

• 📖 Full documentation
• 💬 GitHub Discussions
• 🐛 Report issues

## Documentation Best Practices

### Writing Style
1. **Clear and Concise**: Use simple language
2. **Examples First**: Show code before explaining
3. **Progressive Disclosure**: Basic → Advanced
4. **Consistent Formatting**: Use same patterns
5. **Scannable**: Use headings, lists, tables

### Content Structure
1. **Start with Why**: Explain purpose
2. **Quick Start**: Get users running fast
3. **Common Use Cases**: Cover 80% of usage
4. **API Reference**: Complete prop documentation
5. **Troubleshooting**: Address common issues

### Code Examples
1. **Complete**: Copy-paste ready
2. **Realistic**: Real-world scenarios
3. **Commented**: Explain non-obvious parts
4. **TypeScript**: Show type usage
5. **Tested**: Ensure examples work

### Accessibility
1. **Document a11y Features**: Keyboard, screen readers
2. **Provide Guidelines**: How to use accessibly
3. **Include ARIA**: Document ARIA usage
4. **Test Instructions**: How to verify a11y

### Maintenance
1. **Keep Updated**: Update with code changes
2. **Version Docs**: Document per version
3. **Deprecation Warnings**: Clear migration paths
4. **Changelog**: Track all changes
5. **Feedback Loop**: Improve based on questions

## Tools & Resources

### Documentation Tools
- **Storybook**: Component development and docs
- **TypeDoc**: Generate API docs from TypeScript
- **Docusaurus**: Documentation website builder
- **VitePress**: Fast static site generator
- **Markdoc**: Markdown-based documentation

### Storybook Addons
- **@storybook/addon-a11y**: Accessibility testing
- **@storybook/addon-essentials**: Core addons
- **@storybook/addon-interactions**: Test interactions
- **@storybook/addon-links**: Link stories
- **storybook-dark-mode**: Dark mode toggle

### Writing Tools
- **Grammarly**: Grammar checking
- **Hemingway**: Readability improvement
- **Vale**: Prose linting
- **markdownlint**: Markdown linting

## When to Use This Skill

Activate this skill when you need to:
- Write or update README files
- Create Storybook stories
- Generate API documentation
- Write usage guides
- Create migration guides
- Document component props
- Write tutorials
- Create examples
- Set up documentation site
- Improve existing docs
- Write contributing guidelines

## Output Format

When creating documentation, provide:
1. **Complete Documentation**: README, stories, guides
2. **Code Examples**: Working, tested examples
3. **Screenshots**: Visual aids where helpful
4. **Links**: Cross-references to related docs
5. **Metadata**: Version, last updated, authors
6. **Next Steps**: What to read next

Always prioritize clarity, completeness, and accessibility in documentation.