How to document components for coding agents

1. Start with a component people keep rebuilding

Choose something used across several screens: a button, text field, modal, or status badge. Search the codebase first. The most useful first document often describes a component that already exists but is hard to discover.

Identify its actual import path, exported name, supported props, and existing examples. Check those facts against the implementation. A beautiful document that teaches an invented API creates more work for the next person or agent.

2. Put the brief next to the code

Use a nearby Markdown file or your team’s existing documentation convention. Include an owner or contact if there is one. Link from the repository’s agent instructions to the component directory so the brief is discoverable at the start of a task.

This example is a template. Replace the illustrative names and props with your component’s real API before using it in a project.

# Button
Location: components/Button.tsx
Import: import { Button } from "./components/Button"

Use for: actions that change application state.
Use a link for: navigation to another page.
Variants: primary, secondary, destructive.
States: default, hover, focus, disabled, loading.
Rules: one primary action per decision area; preserve visible focus.
Example: <Button variant="primary">Save changes</Button>
Verify: keyboard activation, loading behavior, long labels, narrow widths.
Do not add a new variant without reviewing existing options.

3. Make the examples runnable

When your project uses Storybook, add a story for each meaningful state and use realistic labels. A story captures a rendered component state; it gives reviewers a stable place to inspect a change. Include an example in context as well, such as a button inside a confirmation dialog.

Document what should happen during loading. Does the control preserve its width? Can a second activation send a duplicate request? How does a screen-reader user learn that work is in progress? These are behavior decisions that a visual screenshot cannot answer on its own.

• Demonstrate the default and most common alternate variant.
• Include disabled, loading, and error-adjacent examples where relevant.
• Show keyboard focus and confirm that the accessible name remains useful.
• Use a long label to reveal wrapping or truncation problems.

4. Test whether the brief helps a real task

Ask your coding agent to add one existing component to a small screen. Tell it to read the brief first and identify which example it follows. Review whether it imported the shared component, used supported props, and avoided new local styles.

If the agent rebuilds the component, check discovery before adding more documentation. The path may be missing from the project entry point, the example may not compile, or two competing components may have equally plausible names. Fix that ambiguity, then repeat the same small task.

During review, attach feedback to the exact rendered instance. Describe which shared behavior or token it should inherit. Accept the correction before sending it for implementation, then verify the reusable component and its consumers before merging.

Common questions