Generate Component Documentation with AI

1. 01

   Components

   Real source files with props, states, and variants

2. 02

   AI reads

   Scans every file and extracts the API surface

3. 03

   Docs standard

   Applies your template: description, props, do/don't, a11y

4. 04

   Library pages

   Markdown docs ready to publish or commit

I documented 34 components by hand last year. Each one took about 45 minutes: list the props, describe the states, write usage guidelines, add do/don’t examples, screenshot the variants. That is 25 hours of work that was outdated within two sprints because engineers kept adding props without telling me.

Repo-aware AI tools read your actual component files and generate documentation from the source code. Not from memory. Not from a template you forgot to update. From the real, current code. When a prop gets added, you re-run the command and the docs update. The entire 34-component library? About 20 minutes.

---

---

Step 1: Point Your AI Tool at Your Components

Open your AI coding tool in the project. In Claude Code, that means:

cd ~/your-design-system
claude

Start with a single component to see what the tool produces:

Read the Button component in src/components/Button/ and generate a complete documentation page. Include:

1. Component description (what it does and when to use it)
2. Props table with name, type, default value, and description
3. All visual states (default, hover, active, disabled, loading)
4. Usage guidelines (when to use, when not to use)
5. Code example showing basic usage

The AI assistant will scan the component files, extract the props from TypeScript interfaces or PropTypes, identify state variations, and generate a structured markdown document.

Why this step matters

You are testing the output on one component before running it across your entire library. If the props table is missing something or the format does not match your team’s preferences, you adjust the prompt once and then scale it.

---

Step 2: Refine the Output Format

The first output is rarely perfect. Refine it:

Update the Button docs with these changes:

1. Add a "Do / Don't" section with 3 examples each
2. Format the props table as a markdown table with columns: Prop | Type | Default | Required | Description
3. Add an "Accessibility" section covering keyboard navigation and ARIA attributes
4. Group related props under subheadings (Appearance, Behavior, Content)
5. Add a "Related Components" section listing ButtonGroup, IconButton, and LinkButton

Once you are happy with the format, save the prompt. You will reuse it for every component.

Why this step matters

Documentation is only useful if it is consistent. Every component page should have the same sections in the same order. By refining the template on one component, you create a standard that scales.

---

Step 3: Create a Documentation Standard

Add documentation rules to your project’s persistent context file so the assistant follows the same format every time. Use CLAUDE.md for Claude Code, AGENTS.md for Codex, .cursor/rules for Cursor, or a linked docs/ai-context.md if your tool prefers plain markdown:

## Documentation Standards

When generating component documentation, follow this structure:

### Required Sections (in order)
1. **Description** - One paragraph. What the component does and when to use it.
2. **Props Table** - Markdown table. Columns: Prop, Type, Default, Required, Description.
3. **States** - List all visual states with descriptions.
4. **Usage Guidelines** - When to use and when not to use (3 examples each).
5. **Accessibility** - Keyboard navigation, ARIA attributes, screen reader behavior.
6. **Code Examples** - Basic usage, then common variations.
7. **Related Components** - Links to components often used together.

### Rules
- Extract props directly from TypeScript interfaces or PropTypes
- Include deprecated props with a deprecation notice
- If a prop has an enum type, list all valid values
- Note any props that are required vs. optional
- Use the component's actual default values, not assumptions

Why this step matters

A persistent rules file acts as memory for the AI tool. Without it, you would need to paste the formatting instructions into every prompt. With it, you simply say “generate docs for the Modal component” and the assistant already knows your format.

---

Step 4: Generate Docs for Your Entire Library

Now scale it. Ask the assistant to document everything:

Generate documentation for every component in src/components/. Follow the documentation standards in the project rules file.

For each component:
1. Create a markdown file at docs/components/[component-name].md
2. Follow the standard section order
3. Extract all props from the source code
4. Skip test files and story files

After generating all files, give me a summary table showing:
- Component name
- Number of props
- Number of states
- Any components that were missing TypeScript types

The assistant will work through each component directory, read the source files, extract the interface definitions, and generate a markdown file for each one.

Why this step matters

This is where the time savings become dramatic. Documenting 30 components manually takes 20+ hours. A repo-aware AI assistant does it in minutes. More importantly, the output is consistent. Every component has the same sections, the same table format, the same level of detail.

---

Step 5: Set Up a Documentation Update Workflow

Documentation rots the moment it is written. Set up a process to keep it current:

Compare the current component source code in src/components/Button/ with the existing documentation in docs/components/button.md. List any differences:

1. Props that exist in code but not in docs
2. Props that exist in docs but were removed from code
3. Default values that changed
4. New states or variants not documented

Run this check at the start of every sprint. You can even create a shell script:

#!/bin/bash
# docs-audit.sh
echo "Starting documentation audit..."
claude -p "Compare all component source files in src/components/ with their docs in docs/components/. List every discrepancy as a table with columns: Component, Issue Type, Details. Issue types are: Missing Prop, Removed Prop, Changed Default, Undocumented State."

Save this as docs-audit.sh in your project root and run it with bash docs-audit.sh.

Why this step matters

The hardest part of documentation is not writing it. It is keeping it accurate. An automated comparison between source code and docs catches drift before your team notices. Running it every sprint means your docs are never more than two weeks out of date.

---

What You Get

After completing this workflow, you have:

• Complete documentation for every component in your library
• A consistent format enforced through a project rules file
• Props tables extracted directly from source code (not written from memory)
• An automated audit script that catches documentation drift
• A repeatable process that takes minutes instead of hours

Common Pitfalls

• Undocumented components. If a component has no TypeScript types and no PropTypes, the assistant will infer props from usage. The output will be less precise. Add types first for best results.
• Generated docs committed without review. Always read what the assistant produces. It may misinterpret a prop’s purpose or miss context that only a designer would know. Treat the output as a first draft.
• Forgetting internal components. AI tools document everything they find. If you have internal-only components that should not be in public docs, add a filter to your prompt: “Skip any component in the internal/ directory.”

Exercise

Generate docs for one component, then the whole library

30 min

1. Prompt your AI tool to document one real component

   In your project directory, start Claude Code, Codex, Cursor, or another repo-aware assistant. Paste the Step 1 prompt, but replace Button with the name of a real component in your repo. Let the assistant read the source file and produce a markdown doc. Read the output carefully. If the props table misses a required flag, or the section order is wrong, note what you want to change.

   • The props table lists every prop from the actual TypeScript interface or PropTypes, not inferred ones
   • States are taken from real variants in the code, not invented
   • You can list the specific changes you want before running this on more components

2. Lock the format in project rules and run it across the library

   Add the Documentation Standards block from Step 3 to your project’s rules file (CLAUDE.md, AGENTS.md, .cursor/rules, or equivalent). Then run the Step 4 prompt to document every component in src/components/. Check three components at random. Confirm the section order, the props table format, and the default values all match what is in the source code.

   • Every component has a markdown file in docs/components/ following the same structure
   • Running the audit prompt from Step 5 flags no drift between source and docs
   • A new prop added to code shows up in the docs after one rerun, without you editing the file