tl;dr
Turn a component's code and docs into a contract that says what it's for, what it isn't for and what it promises.
For documenting components that agents will use. Each one gets a short contract in markdown.
Why
Every component page in my design system opens with a short description, and agents are the ones reading it.
Props tell an agent what a component accepts. They don’t tell it when to use one, so the description has to. The line that does the most work is what the component isn’t for. For a button, that’s “Don’t use it to go to another page. Use a link.”
How to use it
- Paste the component's code, props and any docs.
- Fix the "don't use for" section; it's the most valuable line and the tool's weakest guess.
- Save it next to the component.
Prompt
The drop: Component Usage Guidelines
A prompt to paste, with blanks to fill
Write a contract for this component, under 200 words:
- Purpose: one sentence
- Use when: two or three situations
- Don't use for: two or three common misuses, each with the component to use instead
- Props that matter: only the ones that change behaviour
- States: every state it supports
- Easily confused with: the components an agent might pick instead, and how to tell them apart
- Limits: content limits (max items, max characters) and accessibility promises
Mark anything you inferred rather than read as [CHECK].
Component:
[paste code and docs]What you get
Run on a Button component from a typical React design system, with its props and docs pasted in.
Button
Purpose: Starts an action on the current page, like saving, sending or opening a dialog.
Use when:
- The person is about to do something, not go somewhere
- It's the main or second action in a form, card or dialog
Don't use for:
- Going to another page. Use Link.
- Switching a setting on and off. Use Switch.
- A row of filters. Use ToggleGroup.
Props that matter:
- variant: primary (one per view), secondary, ghost
- loading: shows a spinner and blocks repeat clicks
- icon: leading icon, never on its own without a label
States: default, hover, focus, pressed, loading, disabled
Easily confused with: Link. If the URL changes, it's a Link, even when it looks like a button.
Limits: label up to 3 words [CHECK]. Keyboard reachable, visible focus, 44px touch target.