Component Usage Documentation

Put the rules for using a component next to the component, where they get read.

moderate Developer Experience

What it adds

Usage documentation attached to each shared component covering intended use, variants, accessibility obligations, and the patterns to avoid.

What your agent is told to do

1
Inventory the shared components the app already has and write documentation for the ones that are used in more than one place. A component used once does not need a page; a component used forty times does.
2
For each component, state what it is for, which variants exist and when each applies, what the consumer is responsible for accessibility-wise, and which props or slots are load-bearing.
3
Include at least one realistic example per variant, using the app's own copy and data rather than lorem text. An example showing a three-character label hides the wrapping problem that every real usage hits.
4
Keep the documentation in the same directory as the component and update it in the same change that alters behaviour, so a reviewer sees a variant added and its documentation missing in one diff.
5
Do not write a separate documentation site maintained by hand. A second source of truth drifts within weeks and then actively misleads the people who trust it.

Edge cases it handles

Examples that are only prose go stale silently. Render the examples from the same code the documentation shows, or run them in the test suite, so a broken example fails a build rather than misleading a reader.
Every component needs an explicit section on when not to use it and what to reach for instead — a dialog documented without the note that a destructive confirmation belongs to the confirmation pattern will be used for both.
Documentation must be versioned alongside the implementation, so a consumer pinned to an older release reads the rules that actually applied then.
Realistic examples must include the awkward states: long labels, missing optional data, right-to-left text, and the loading and error variants, not just the happy path.
A component that has been deprecated must say so at the top with its replacement named, rather than quietly remaining as valid-looking guidance.
Accessibility notes must say who owns what — if the component renders the control but the consumer supplies the label, the documentation must state that the label is not optional.
Screenshots go out of date faster than anything else. Prefer live rendered examples, and if a screenshot is unavoidable, note what it is showing so a stale one is obvious.

Definition of done

Every component used in more than one place has usage documentation beside its implementation.
Each documented component names its variants, its intended use, and at least one case where it is the wrong choice.
Examples render from real code and fail the build when the component's interface changes.
Accessibility responsibilities are split explicitly between the component and its consumer.
Documentation ships in the same change as the behaviour it describes.
Deprecated components carry a visible notice naming their replacement.
The feature matches the existing design system.
No existing functionality is broken.

Related features

SEO Setup

Design Token Linter

Multi-Model Routing

How it works

1

Copy the link

Grab the Markdown instruction URL for this feature.
2

Give it to your AI

Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.
3

It inspects, then implements

Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.