LLM Readable Documentation: How to Write Components So AI Doesn't Invent the Wheel
Main chat
A chat for vibe coders: news, guides, live cases, marketplace, and finding executors.
In May 2026, a real job posting Senior Product Designer featured a requirement that a year ago did not exist: “Create and maintain system documentation readable by designers, engineers, and LLMs like Claude.”.
LLM as the third audience of documentation is not the future, it is the present.
Three audiences, three different needs
** Designer understands context. "Use Primary Button for the main action" is understandable without explanation. Experience tells you what the “main action” is and what it looks like in practice.
**Developers need precise syntax. You need the right props, the right value, the right import. The context also captures and can come up with details.
**AI agent * does not understand the context and does not think. If it says “use the button for actions,” the AI fills in the “action” from the training data. This is usually any click, including navigation. You need clear rules: “Button/Primary – only for CTA (save, send, create).” Not for navigation, but for this link.
Five principles of LLM-readable documentation
1. Clearness instead of implied
All people understand by default is to write explicitly.
“Use Button for interactive user actions.”.
Use Button/Primary for the single main CTA on the screen: save changes, submit a form, create an object, move to the next step. Do not use for navigation between pages - for this Link or NavItem.
Difference: The “action” for AI is vague. The list of specific examples is not.
2. Prohibitions work better than permits
AI broadly interprets permissions. No prohibitions.
“Use for action” → AI uses for everything interactive. “Not for navigation” → AI does not use for navigation. Period.
The “Forbidden” section with alternatives is one of the most valuable documentation elements for AI.
3. Tables instead of prose for parameters
The props table reads in seconds. Prose requires interpretation.
| Prop | Type | Default | Description
|------------------------------------------------------------------------- |------------------------------------------- |
| variant | "primary" | "secondary" | "ghost" | "danger" | "primary" | Visual version |
| size | "sm" \| "md" \| "lg" | "md" | Size |
| disabled | boolean | false | Inactive state |
| loading | boolean | false | Download status |
| icon | ReactNode | - | Icon to the left of the text |4. Examples with explicit markers и and и
This is the only Primary on the screen.
<Button variant="primary" size="md">Save changes</Button >>
Next Next post: Secondary next to Primary
<Button variant="secondary">Cancel</Button >>
<Button variant="primary">Save</Button >>
Incorrect: Two Primary on the same screen
<Button variant="primary">Save</Button >>
<Button variant="primary">Publish</Button >>
Incorrect – Primary for navigation
<Button variant="primary" onClick={() => navigate('/dashboard')} >>
Head to head.
</Button/ >>
Correct for navigation: <Link href="/dashboard" >> Main </Link >>Markers are literal instructions. AI reproduces examples with ., avoids examples with ..
5. Related components explaining when to use
AI creates a new component because it doesn't know what it already has.
## Instead of Button use
`Link` – for navigation between pages (not actions)
`IconButton` – button with icon only (aria-label required)
`ButtonGroup` - a group of switchable mutually exclusive variants
`FAB` – the main action on top of the content on mobileComplete component documentation template
#Button
A button to trigger actions. Not for navigation between pages.
## Options
| Option | When to use | Restriction |
|------------|-------------------------------------------------------------------------------------------------------- |
| `primary` | Main action on the screen | Maximum one in the visible area |
| `secondary` | Secondary acts | - |
| `ghost` | Tertiary actions in a dense interface | Not for destructive actions |
| `danger` | Irreversible destructive actions | Always with confirm-dialogue |
## Forbidden
Two `variant="primary"` in one visible region
- `Button` to go to the page → use `Link`
Button with icon only without `aria-label`
A button with text longer than 5 words (exception: forms)
Hardcut colors via `style` instead of variant
## Props
[table from example above]
## Examples
[code with ] and ]]
## Instead of Button use
`Link` - navigation
`IconButton` - Icon Only
- `ButtonGroup` - Related Action GroupThree storage locations: different audiences, different depth
**AGENTS.md – for AI, briefly (≤200 lines) **
Every session is read. Longer - important rules are lost.
Button – the rules for AI
primary: single CTA (save/send/create)
Secondary: Next to primary or self-directed
ghost: tertiary acts
Danger: Irreversible + confirm required
Two primary beside
Button for navigation → Link
Only an icon without aria-label
жен hard-cut colorsStorybook MDX - for developers, in detail, with live examples and Controls. AI reads through Storybook MCP.
Notion/Confluence - for the team, with a history of decisions and context why.
How to Maintain Relevance
Documentation is becoming obsolete faster than it seems. Three rules:
Same PR as component. Not later. The API has changed without updating AGENTS.md – AI generates non-working code.
Changelog:
#changelog
v1.3.0 (June 2026): added prop loading:boolean
v1.2.0 (March 2026): deprecated is Disabled → disabled
v1.1.0 (January 2026): size options added: sm/md/lgA test through AI once a month. Give only AGENTS.md, ask to create a form. If AI is wrong, the documentation is incomplete. Real metric: edit after generation with good documentation – 1-2. Without her, 5-10.
Prompt for creating LLM-readable documentation
Create an LLM-readable documentation for the component.
Mandatory structure:
1. One line: what it is and what not to use for
2. Table of options: option | when | restriction
3. Section "Prohibited" with alternatives for each item
4. Props table: prop | TypeScript-type | default | description
5. Examples with markers ы (right) and ы (wrong)
6. "Instead of [component] use" - a list with explanations
Requirements:
- No implication - it's all clearly written.
Rules: specific actions or prohibitions (not "recommended")
Props Names from Real Code – Copypast Should Work
- After creation: test - just give this Claude documentation and ask
Create a screen with this component. The result will show the gaps.Practice: How to test the quality of documentation
A test that shows real quality better than any review: open a new chat, give only AGENTS.md without any other instructions, and ask "Create a typical login form for our product.".
Look at the result: What components did AI use? Right names from the system or invented? Colors through CSS variables or hex? The correct typeface?
Every breach is a gap in documentation, not in AI. If you add an explicit prohibition or example, you test again. After 3-4 iterations, AGENTS.md begins to give the correct result the first time.
The real metric worth tracking is the number of edits after the first screen generation. With good documentation - 1-2 edits. With bad - 5-10 iterations of explanations. The difference is in edits or documentation.
When documentation does the opposite
Occasionally, abundant documentation interferes. AI is overloaded with rules and begins to apply them incorrectly - at the same time several conflicting.
Signs of overload: AI starts adding aria-label to every element, including those that don’t need it. Or add a loading state to a static text. Or trying to apply Typography tokens to icons.
Solution: The documentation should be accurate, not exhaustive. Better 10 clear rules than 50 flaccid recommendations. AGENTS.md to 200 lines is not a volume limit, it is a noise limit.
Difference Between Human Documentation and AI
Designers and developers have been learning to write documentation for people for years. It was documentation with context, with meaning, sometimes with humor. “Use the main button for important actions” – any designer knows what it means.
AI doesn't understand "important." For AI, “important” is what is clearly labeled as important. If not written, AI fills the gap with its assumption from training data.
Switching thinking from “writing for a colleague” to “writing for a system that doesn’t know the context” is what makes LLM-readable documentation. It's not "write worse" or "primitiver." This is to write more precisely: remove the implication and replace the explicit rules.
The good news is that AI documentation works better for humans. It's clearer, more specific, with examples. A new designer or developer reads it and immediately understands what and how. Without “well, that’s in context.”.
Documentation as a living product
The mistake that many people make is to write the documentation once and think it’s ready. Component documentation is a living product that requires support as a component.
For every PR component that changes, ask the question, “Do I need to update the documentation?” The answer to yes usually takes 5 minutes. It’s cheaper than looking at why AI generates from an old API.
Once a quarter: go through all the components and check that the documentation matches reality. Components that have not been touched for a long time - to start with them, there is the most outdated.
** Three documentation quality metrics:**
The number of edits after the first AI generation. Good documentation > 1-2 edits. Bad → 5-10 iterations.
The number of questions “how to use this component” per week. There are no questions, the answer is in the documentation. Constant questions in the chat room.
Percentage of AI generation using the right components from the system You can check once a month through the test from the previous section.
Why Prohibitions Work Better Than Permits
In the documentation for people, we write what is possible and sometimes what is impossible. For AI, the ratio should be the opposite: more explicit prohibitions, less open permissions.
The reason is how AI interprets uncertainty. “Use the action button” – AI considers this to be permission to use the button for any interactive element, including navigation. “Do not use Button to navigate between pages” is an explicit prohibition that AI enforces.
The practical consequence is that when writing the documentation, go through each rule and ask, “How can AI interpret this broadly?” The answer shows what needs to be formulated as an explicit prohibition.
Example: “Button/Primary – for the main action” → AI can put three Primary Button because three actions are “main”. Button/Primary is for a single CTA in the visible domain. Prohibited: More than one Button/Primary on screen.
That sounds superfluous to humans. It's necessary for AI.
Test: Check your documentation right now
Take Agents.md. Open a new chat with Claude Code or Cursor. Insert only the contents of AGENTS.md as a system prompt. Ask: “Create a user profile page.”.
Look at the result: What components did AI choose? The right names? Right options? The Right CSS Variables for Colors?
Every deviation from what is expected is the missing rule in the documentation. Add it explicitly. Repeat the test. After 3-4 iterations, the documentation will begin to give a consistent result.
This is the quickest way to improve documentation – not to think what’s missing, but to see where AI is wrong.
When documentation interferes: signs of overload
Sometimes too detailed documentation works worse than short. AI begins to apply the rules incorrectly: adds aria-label to each element, including those that do not need it, or applies typography tokens to icons.
Signs of overload in AGENTS.md:
- AI adds
loadingprop to static text - AI puts
disabledon buttons that should not be inactive - AI applies one rule everywhere, ignoring context
Solution: AGENTS.md to 200 lines is not a volume limit, it is a noise limit. Ten clear rules work better than fifty vague recommendations.
Selection principle: Include only rules that AI violates without them. If AI never uses Inter, you don’t have to ban Inter. If AI sometimes puts two Primary Buttons, bans are explicit. Documentation from real problems, not from perceived ones.
Changelog: Three lines that change the quality of support
The simplest improvement units make is to add a Changelog section to each component.
#Button
#changelog
v1.3.0 (June 2026): added prop loading:boolean, icon on the right
v1.2.0 (March 2026): deprecated is Disabled → use disabled
v1.1.0 (January 2026): size: sm | md | lg addedAI sees the changelog and understands the relevant API without further explanation. A developer who wasn't at the last rally knows what's changed. The new person on the team sees the history of decisions.
Three lines to update. Save hours on "why my code doesn't work" questions.
● One line: what and for what not to use
Table of options with obvious limitations
Section "Prohibited" with alternatives
Props table with TypeScript types and defaults
Examples with ы and ы
"Instead of X use" - a list with explanations
AGENTS.md ≤ 200 lines (only the most critical)
Storybook MDX – full version for developers
● Updated in the same PR as the component
Changelog when changing the API
