name: documentation description: Generate comprehensive feature documentation including Storybook stories, JSDoc comments, and feature guides. Use after completing a feature (may span multiple commits). Creates documentation for humans and AI to understand features, usage patterns, and design decisions.

Documentation (TypeScript + React)

Generate comprehensive documentation for features, components, and hooks.

When to Use

After completing a feature (may span multiple commits)
When a component/hook needs usage documentation
When design decisions need recording
For public/shared components and hooks

Documentation Types

1. Storybook Stories (Component Documentation)

Purpose: Visual documentation of component usage and variants

Creates: .stories.tsx files alongside components

2. JSDoc Comments (Code Documentation)

Purpose: Inline documentation for types, props, complex functions

Location: In source files (.ts, .tsx)

3. Feature Documentation (Architectural Documentation)

Purpose: WHY decisions were made, HOW feature works, WHAT to extend

Creates: docs/features/[feature-name].md

Workflow

1. Identify Documentation Needs

Ask:

Is this a reusable component? → Storybook story
Is this a custom hook? → JSDoc + usage example
Is this a complete feature? → Feature documentation
Are types/props complex? → JSDoc comments

2. Create Storybook Stories

For each component, create stories showing:

Default state
All variants/props
Interactive states
Edge cases (loading, error, empty)

Example:

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

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  parameters: {
    layout: 'centered'
  },
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'danger']
    }
  }
}

export default meta
type Story = StoryObj<typeof Button>

// Default story
export const Primary: Story = {
  args: {
    label: 'Button',
    variant: 'primary',
    onClick: () => alert('clicked')
  }
}

// Variants
export const Secondary: Story = {
  args: {
    ...Primary.args,
    variant: 'secondary'
  }
}

export const Danger: Story = {
  args: {
    ...Primary.args,
    variant: 'danger'
  }
}

// States
export const Disabled: Story = {
  args: {
    ...Primary.args,
    isDisabled: true
  }
}

export const Loading: Story = {
  args: {
    ...Primary.args,
    isLoading: true
  }
}

// Interactive example
export const WithIcon: Story = {
  args: {
    ...Primary.args,
    icon: <IconCheck />
  }
}

3. Add JSDoc Comments

For public types and interfaces:

/**
 * Props for the Button component.
 *
 * @example
 * ```tsx
 * <Button
 *   label="Click me"
 *   variant="primary"
 *   onClick={() => console.log('clicked')}
 * />
 * ```
 */
export interface ButtonProps {
  /** The text to display on the button */
  label: string

  /** The visual style variant of the button */
  variant?: 'primary' | 'secondary' | 'danger'

  /** Callback fired when the button is clicked */
  onClick: () => void

  /** If true, the button will be disabled */
  isDisabled?: boolean

  /** If true, the button will show a loading spinner */
  isLoading?: boolean
}

For custom hooks:

/**
 * Custom hook for managing user authentication state.
 *
 * Handles login, logout, and persisting auth state to localStorage.
 * Automatically refreshes token when it expires.
 *
 * @param options - Configuration options for authentication
 * @returns Authentication state and methods
 *
 * @example
 * ```tsx
 * function LoginForm() {
 *   const { login, isLoading, error } = useAuth()
 *
 *   const handleSubmit = async (email: string, password: string) => {
 *     await login(email, password)
 *   }
 *
 *   return <Form onSubmit={handleSubmit} isLoading={isLoading} error={error} />
 * }
 * ```
 */
export function useAuth(options?: AuthOptions): UseAuthReturn {
  // Implementation
}

For complex types:

/**
 * Represents the state of an asynchronous operation.
 *
 * Uses discriminated union to ensure invalid states are impossible
 * (e.g., cannot have both data and error simultaneously).
 *
 * @template T - The type of data returned on success
 *
 * @example
 * ```typescript
 * const [state, setState] = useState<AsyncState<User>>({ status: 'idle' })
 *
 * // Type narrowing works automatically
 * if (state.status === 'success') {
 *   console.log(state.data.name) // state.data is available and typed
 * }
 * ```
 */
export type AsyncState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error }

4. Create Feature Documentation

For completed features, create docs/features/[feature-name].md:

Template:

# Feature: [Feature Name]

## Overview
Brief description of what the feature does and why it exists.

## Problem
What problem does this feature solve? What was the pain point?

## Solution
How does this feature solve the problem? What approach was taken?

## Architecture

### Components
- **ComponentName**: Purpose and responsibility
- **AnotherComponent**: Purpose and responsibility

### Hooks
- **useFeatureHook**: What it does and why it's separate

### Context
- **FeatureContext**: What state it manages and why context was needed

### Types
- **KeyType**: What it represents and why it's a custom type

## Key Design Decisions

### 1. [Decision Title]
**Decision**: What was decided
**Rationale**: Why this approach was chosen
**Alternatives**: What other approaches were considered
**Trade-offs**: What we gained and what we gave up

### 2. [Another Decision]
...

## Usage

### Basic Usage
```typescript
// Simple example showing most common use case

Advanced Usage

// Example showing advanced features or edge cases

Integration

How this feature integrates with other parts of the application.

API Reference

Components

ComponentName

Props:

propName (Type): Description

Events:

onEvent: When it fires and what it provides

AnotherComponent

...

Hooks

useFeatureHook

Parameters:

param (Type): Description

Returns:

returnValue (Type): Description

Types

TypeName

type TypeName = ...

Description of when and how to use this type.

Testing Strategy

Unit Tests

What is tested at the unit level (pure components, hooks)
Coverage expectations (100% for leaf components)

Integration Tests

What user flows are tested
How mocking is handled (MSW for APIs)

Accessibility

Compliance

WCAG level compliance (A, AA, AAA)
What accessibility features are implemented

What keyboard shortcuts are supported
How tab order works

What ARIA attributes are used
What announcements are made

Performance Considerations

Optimizations

What performance optimizations are implemented
Use of memo, useMemo, useCallback

Bundle Impact

Approximate bundle size contribution
Any lazy loading or code splitting

Known Limitations

Current Limitations

What doesn't work yet
What edge cases aren't handled

Future Enhancements

What could be improved
What features could be added

Troubleshooting

Common Issues

Issue: [Problem Description]

Symptom: What users will see Cause: Why this happens Solution: How to fix it

Links to related documentation
Dependencies on other features
Features that depend on this

Migration Guide

(If replacing existing functionality)

Before

// Old way

After

// New way

Breaking Changes

What changed
How to update code

Changelog

v1.1.0 (2024-01-15): Added support for...
v1.0.0 (2024-01-01): Initial implementation


## Output Format

After generating documentation:

📚 DOCUMENTATION GENERATED

Feature: User Authentication

Generated Files: ✅ Storybook Stories (3 components)

src/features/auth/components/LoginForm.stories.tsx
src/features/auth/components/RegisterForm.stories.tsx
src/features/auth/components/PasswordInput.stories.tsx

✅ JSDoc Comments Added

src/features/auth/hooks/useAuth.ts (hook documentation)
src/features/auth/types.ts (type definitions)
src/features/auth/context/AuthContext.tsx (context API)

✅ Feature Documentation

docs/features/authentication.md (complete guide)

📖 Documentation includes:

Problem/solution overview
Architecture and design decisions
Usage examples (basic + advanced)
API reference (components, hooks, types)
Testing strategy
Accessibility features
Performance considerations
Troubleshooting guide

🎯 Next Steps:

Review generated Storybook stories locally: npm run storybook
Review feature documentation: docs/features/authentication.md
Update any project-specific references or links
Commit documentation with feature code

📝 Maintenance:

Update Storybook stories when component props change
Update JSDoc when APIs change
Update feature docs when design decisions change
Keep examples working (they're testable!)


## Documentation Principles

### For Humans AND AI

Documentation serves two audiences:
1. **Human developers**: Need to understand and extend code
2. **AI assistants**: Need context to help debug and extend features

Write documentation that helps both audiences understand:
- **WHY** decisions were made (context for future changes)
- **HOW** the feature works (architecture and flow)
- **WHAT** can be extended (integration points)

### Show, Don't Tell

Prefer code examples over prose descriptions:

**❌ Bad**:

The Button component accepts a variant prop that can be primary, secondary, or danger, and will style the button accordingly.


**✅ Good**:
```typescript
<Button variant="primary" label="Save" />
<Button variant="secondary" label="Cancel" />
<Button variant="danger" label="Delete" />

Keep Examples Executable

Storybook stories and JSDoc examples should be real, working code that compiles and runs.

Document Design Decisions

Most important: WHY decisions were made.

❌ Bad:

// Uses context for state management

✅ Good:

/**
 * Uses AuthContext for state management instead of prop drilling.
 *
 * Decision: Context chosen because auth state is needed in 10+
 * components across different nesting levels (nav, profile, settings,
 * protected routes). Prop drilling would be unmaintainable.
 *
 * Alternative considered: Redux - overkill for single feature state
 */

When to Document

Always Document

Public/shared components
Custom hooks (except trivial ones)
Complex types (discriminated unions, branded types)
Completed features (spanning multiple commits)

Consider Documenting

Complex utility functions
Non-obvious algorithms
Performance-critical code
Edge cases and workarounds

Don't Over-Document

Trivial functions (self-explanatory)
Implementation details (private functions)
Obvious code (const user = getUser())

Best Practices

Storybook

One story file per component
Show all variants
Include interactive controls
Document props with argTypes
Add accessibility checks (a11y addon)

JSDoc

Use @param, @returns, @example tags
Include examples showing typical usage
Document complex types inline
Link related types with @see

Feature Docs

Start with problem/solution
Include architecture diagrams (mermaid)
Provide working code examples
Document WHY, not just WHAT
Keep updated as feature evolves

Tools

Storybook Commands

# Run Storybook locally
npm run storybook

# Build static Storybook
npm run build-storybook

# Test stories (interaction testing)
npm run test-storybook

TypeDoc (Alternative to JSDoc)

# Generate API documentation from TypeScript
npx typedoc --entryPoints src/index.ts

Key Principles

See reference.md for detailed principles:

Document WHY, not just WHAT
Show working code examples
Keep docs close to code
Update docs with code changes
Test examples (Storybook)
Document for humans AND AI
Focus on usage, not implementation

See reference.md for complete documentation templates and examples.

documentation

SKILL.md