Design systems / Practical guide # How to document components for coding agents A reusable component brief for your existing library. [By CRRT](/)·November 2, 2026·3 min read [← All resources](/resources) ## The short answer A component brief for a coding agent should explain where the component lives, when to use it, its supported variants, and how to verify its behavior. Pair a working example with state and accessibility requirements so the agent can reuse an existing component with less guesswork. ## 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. Copy & adapt ``` # 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: 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 ### Should I document every component at once? Start with the components that are frequently duplicated or incorrectly used. A verified brief for one common control is more useful than an unverified inventory. ### Does component documentation replace visual review? No. Documentation describes intended usage. Review confirms that the rendered result, surrounding layout, and interaction meet that intent. ## Sources & further reading * [Storybook: writing component stories](https://storybook.js.org/docs/writing-stories) * [Storybook: best practices for AI](https://storybook.js.org/docs/ai/best-practices) Written with AI assistance. Tool references checked against the linked documentation on November 2, 2026. Examples are starter templates to adapt and review in your own project. Keep going ## Put the next piece in place. [ Practical guide · 3 min read ### Design tokens for AI prototypes: start with one screen A small token file and a prompt your builder can reuse. ](/resources/design-tokens-for-ai-prototypes)[ Practical guide · 3 min read ### How to write visual feedback a coding agent can act on A copyable feedback template and a complete worked example. ](/resources/visual-feedback-for-coding-agents) ## See something off? Ship the fix. Pin the feedback. Give your coding agent the context. Review what comes back. [Try CRRT](/docs/install)