Add comprehensive JSDoc documentation to a React component file following Storybook MCP best practices
Add comprehensive JSDoc documentation to the component file at $ARGUMENTS so that Storybook's AI manifest and MCP server produce high-quality, actionable component metadata.
Read the component file at $ARGUMENTS and understand its structure: exported components, props types/interfaces, sub-components, variants, and defaults.
Read related files (index.ts barrel, stories, any MDX docs in the same directory) to understand the full component API surface and existing documentation.
Add JSDoc to the main exported component with:
[ComponentName](?path=/docs/componentname--docs).@summary@example tag showing the most common usage pattern with realistic props./**
* Avatar displays a user's profile image, initials, or a fallback icon.
* Use Avatar for user identification in lists, headers, cards, and comments.
* For navigation that displays a user, consider pairing with [UserCard](?path=/docs/usercard--docs).
*
* @summary Displays a user's profile image, initials, or fallback icon
*
* @example
* <Avatar src="/photo.jpg" alt="Jane Doe" size="md" variant="circle" />
*/
Add JSDoc to every prop in the component's type/interface:
Defaults to 'md').interface AvatarProps {
/** Image URL to display. When unavailable or loading fails, `fallback` content is shown instead. */
src?: string;
/** Accessible alt text describing the avatar image. Required when `src` is provided. */
alt?: string;
/** Content rendered when `src` is missing or fails to load. Typically initials (e.g., "JD") or an icon. */
fallback?: ReactNode;
/** Controls the avatar dimensions. Defaults to `'md'` (40px).
* - `xs` (24px) — inline indicators, dense lists
* - `sm` (32px) — compact layouts, table rows
* - `md` (40px) — standard usage, cards, headers
* - `lg` (48px) — profile sections, detail views
* - `xl` (64px) — hero sections, prominent display
* - `2xl`–`4xl` — large feature areas, profile pages
*/
size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';
}
Add JSDoc to sub-components (compound component parts like Root, Image, Fallback, Trigger, Content, etc.) if they are exported:
@summary tags.Add JSDoc to exported hooks (e.g., useAvatar):
Add JSDoc to exported recipe/style objects (e.g., tv() variants):
After applying all documentation, re-read the modified file and verify against this checklist. Fix any failures before finishing.
| # | Check | How to verify |
|---|---|---|
| 1 | Every exported component has a JSDoc with @summary | Search for each export — confirm a /** ... @summary block directly above it |
| 2 | Every prop in every public type/interface has a JSDoc comment | Read the type block — every member must have a /** ... */ line |
| 3 | @summary tags are under 80 characters | Count characters in each @summary value |
| 4 | Component JSDoc includes "when NOT to use" guidance | Look for negative guidance (e.g., "Do not use…", "For X, use Y instead") in the main component description |
| 5 | At least one @example tag on the main component | Confirm @example exists with realistic JSX |
| 6 | Defaults mentioned in prop docs for props that have them | Check that props with default values include "Defaults to …" |
| 7 | Union/enum options explained where not self-evident | Confirm size/variant/status-like props list their options with context |
| 8 | Exported hooks have JSDoc with @summary | Search for exported hooks — confirm documentation |
| 9 | No @param or @type tags added | Search for @param and @type — must find none that were added |
| 10 | No runtime code was modified | Diff only shows JSDoc comment additions/changes |
| 11 | TypeScript compiles without errors | Run npx tsc --noEmit and confirm clean output |
If any check fails, fix the issue and re-verify before reporting completion.
@summary tags concise — under 80 characters. Agents see this in list views and truncated contexts.@example tags, not placeholder text like "foo" or "test".@param tags for props — react-docgen-typescript extracts these from the interface. Use JSDoc on the interface members instead.@type {string}) — TypeScript types are already extracted.