The previous lesson left you with a hard truth: an agent that can read your Button exists can still use it wrong, because knowing a component exists is not knowing when to use it. An agent reads that Button has a variant="destructive" prop and cheerfully applies it to a "Save" action, because the prop is real and the prop name alone does not tell it that destructive is for irreversible actions only. The fix is documentation written for a reader who takes everything literally and infers nothing: MDX doc blocks in Storybook that state the intended use, the props, and the edge cases in prose an MCP-enabled agent consumes. This lesson has you write Meta, Description, and ArgsTable doc blocks for a five-component subset of your system, and demonstrate the diff that proves it matters - the same prompt producing a hallucinated prop on an undocumented component and the real prop on a documented one. The artifact is five MDX-documented components plus a before/after AI-prompt comparison that shows documentation turning a guessing agent into a reading one.

Reading a Prop Versus Understanding It

The connection from the last lesson gives an agent the shape of your components: that Button exists, that it has a variant prop, that the values are primary, secondary, ghost, destructive. That shape is necessary and it is not sufficient, because shape is syntax and use is semantics. An agent reading only the shape knows the destructive variant exists but not that it must be reserved for irreversible actions; knows the size prop has a sm value but not that sm buttons fail the target-size minimum on touch and should not be used for primary mobile actions; knows there is a loading prop but not that you must set it during async operations or the user double-submits. The prop list is a vocabulary; it is not a usage guide, and an agent handed a vocabulary with no usage guide will use the words in grammatically valid but semantically wrong ways.

This is the exact analog of the program's founding distinction. The agent can generate syntactically correct component usage - real component, real prop, real value - while getting the use wrong, the same way a generated mock can look right and behave wrong. The component's MDX documentation is where you supply the understanding the prop list lacks. It is the place you write down, in words the agent reads, the things a human team member would learn from a code review or a Slack thread or simply absorbing the team's taste over months: this variant is for this situation, this prop is required in this case, this is the edge case people get wrong. Without the documentation, the agent has your vocabulary and your team's tacit knowledge is invisible to it; with the documentation, that tacit knowledge becomes machine-readable context.

The Three Doc Blocks That Carry the Weight

Storybook's MDX format supports a set of doc blocks, but for making a component AI-readable three do most of the work. Knowing what each one is for keeps your documentation focused on what the agent needs rather than padded with what reads nicely to a human and tells the agent nothing.

Meta: The Component's Identity and Intended Use

The Meta block establishes what the component is and, crucially, what it is for. This is where you state the component's purpose in a sentence an agent can use to decide whether this is the right component for a need: "Button triggers an action or navigation. Use it for the primary and secondary actions on a screen. For navigation that looks like a link, use Link instead." That last sentence is gold for an agent, because it draws the boundary between this component and its neighbor, which is exactly the decision an agent gets wrong when it reaches for a button where a link belongs. Meta is where you prevent the agent from using the right component in the wrong role.

Description: Usage Rules and Edge Cases in Prose

The Description block is the prose body where the tacit knowledge lives, and it is where you spend most of your documentation effort. This is where you write the usage rules ("there should be exactly one primary Button per screen section"), the constraints ("do not use variant=destructive for non-destructive actions; it signals irreversibility to the user"), and the edge cases ("set loading=true during async submission to prevent double-submits; the button disables itself while loading"). Every sentence here is a rule the agent would otherwise have to guess at and frequently guess wrong. Write it the way you would brief a sharp new hire who will take you completely literally and has no access to the team's accumulated taste: state the rule, state the reason, name the edge case.

ArgsTable: The Precise, Annotated Prop Contract

The ArgsTable (rendered from the component's prop types and arg annotations) is the precise contract: every prop, its type, its allowed values, its default, and a per-prop description. This is what stops the agent inventing a prop, because it can read the exact, exhaustive list of props that exist and their exact allowed values. The leverage move is to annotate each prop with a one-line description of when to use it, not just what type it is: variant is not merely "primary" | "secondary" | "ghost" | "destructive" but each value carries a note - destructive "for irreversible actions only." The ArgsTable is where you make it impossible for the agent to use a prop that does not exist and hard for it to use a real prop in the wrong situation, because the allowed values and their intended uses are both right there in the contract it reads.

The prop list is a vocabulary; the MDX is the usage guide. An agent handed a vocabulary with no usage guide uses the words in grammatically valid, semantically wrong ways - the real component, the real prop, applied to exactly the situation it is wrong for. Documentation is where you write down the tacit knowledge a human absorbs over months so a literal reader can have it instantly.

Choosing and Documenting the Five-Component Subset

You do not document the whole system at once; you prove the pattern on a representative five-component subset, because five well-documented components teach the pattern and demonstrate the payoff better than fifty half-documented ones. Choose the five deliberately. Pick the components most prone to misuse, because those are where documentation buys the most: a Button (variant misuse), a Modal (when to use versus a drawer or inline, and focus-trapping edge cases), an Input (validation states and the required-label rule), a Select (versus radio versus combobox, and the long-list edge case), and a destructive-action pattern (the confirmation requirement). These five carry the kinds of usage rules an agent most reliably gets wrong, so documenting them is the highest-leverage starting point.

For each, you write the three blocks: a Meta stating identity and the boundary with neighbors, a Description carrying the usage rules and edge cases, and an annotated ArgsTable contract. The work is genuinely writing, not generating - and here is a place to be careful with AI. You can use a model to draft the documentation, and it will produce competent, generic prose about what a button is. But the value is in the team-specific rules the model cannot know: that your system reserves the destructive variant for a specific confirmation pattern, that your modals must never be used for more than one decision, that your select degrades to a search input past twenty options. Those rules live in your team's practice, not in the model's training data, so a model-drafted doc is a starting skeleton you fill with the actual rules, the same division of labor that ran through the whole token chapter: the model does the generic scaffolding, you supply the specific knowledge that makes it yours.

The Before/After Demonstration That Proves It

The diff is the deliverable, because it converts "documentation helps" from an assertion into something you can show. Run the same prompt against the agent twice: once with the component undocumented (shape only, from the MCP connection) and once with the three MDX blocks written.

Before, with shape only, you prompt for a "delete confirmation with a clear destructive action," and the agent does something plausibly wrong. It might invent a confirmColor="red" prop that does not exist, because it knows the action should look dangerous and guesses a prop to make it so. Or it uses variant="primary" for the delete button because it does not know your destructive variant exists for exactly this purpose, coloring a primary button red by hand. Either way the output is system-adjacent but wrong: a hallucinated prop or a real prop used for the wrong job, precisely the failures documentation prevents.

After, with the Meta naming the destructive pattern, the Description stating that destructive actions require confirmation and the destructive variant, and the ArgsTable annotating variant="destructive" as "for irreversible actions only," the agent reads all of it and uses Button variant="destructive" inside the confirmation, with no invented prop, because the documentation told it the real prop exists and is exactly the one for this situation. The diff between the two outputs is the proof: same prompt, same connection, same agent, and the only changed variable is whether the component was documented. You can point at the before-output's hallucinated confirmColor and the after-output's correct variant="destructive" and say, precisely, this is what the documentation did. That is a far stronger artifact than a doc nobody can demonstrate the value of.

Why This Is Design Work, Not Just Tech Writing

It is tempting to file MDX documentation under "engineering chore" or "tech writing" and hand it off, and that instinct is exactly backwards for the rules that matter. The prop types and defaults can come from the code; an engineer or the framework generates those. But the usage rules and the boundaries between components are design decisions, and they live in the designer's head. Only the designer knows that the destructive variant is reserved for the team's confirmation pattern, that modals are for single decisions, that the select degrades past twenty options - because the designer made those rules, often implicitly, through hundreds of design reviews and crit comments and "no, use the other component" corrections. The MDX documentation is where you make those implicit rules explicit, and that is design authorship, not transcription.

This reframes the work as high-leverage rather than low-status. Every rule you write into a component's Description is a rule you no longer have to enforce by hand in a review, because the agent now applies it from the start, and the human contributors reading the same docs apply it too. You are encoding your taste into the system so it scales past the moments you are personally in the room. That is the same move as building the token system: turning a thing that lived in your judgment and had to be applied manually every time into infrastructure that applies itself. The designer who writes the component docs is doing the same leverage-positive work as the designer who built the tokens.json, on the layer above it - and an agent reading a system documented this way is reading not just your components but your accumulated design judgment about how they should be used, which is the closest thing to having you in the room that a machine can get.

Writing a Doc Block the Agent Actually Reads

Abstractions are easy to nod along to and hard to apply, so make one concrete. Take the Button and write its three blocks the way you would actually ship them, then notice what separates a doc that moves the agent from one that does not. The Meta is one or two sentences: "Button triggers an action such as submit, save, or delete. For navigation that changes the URL, use Link; for a low-emphasis action inside dense UI, use IconButton." Two sentences, and you have already drawn the two boundaries an agent most often crosses - button-as-link and button-where-an-icon-button-belongs. Notice the form: not "Button is a clickable element" (true, useless) but "use it for X, and for the adjacent case Y use this other thing instead." The boundary is the content. A Meta that only describes the component without bordering it against its neighbors has documented the easy, inert half.

The Description is where you spend the words, and the discipline is to write rules, not adjectives. A weak description says the button is "flexible and accessible." A strong one says: "There is exactly one primary Button per screen section; additional actions use secondary or ghost. Use variant=destructive only for irreversible actions, and always pair a destructive action with a confirmation step - never let a single click destroy data. Set loading=true during async submission; the button disables itself to prevent double-submits. Do not place a Button with size=sm as a primary action on touch surfaces, because it falls below the 24-pixel target-size minimum." Read those four sentences as an agent would: each is an unambiguous instruction with a condition and a reason. The condition tells the agent when the rule fires; the reason is not for the agent, who will obey regardless, but for the human contributor reading the same block, who needs to know whether the rule still applies as the system evolves. Write the condition for the machine and the reason for the person, in the same sentence.

The annotated ArgsTable is the contract, and the move that earns its keep is the per-value note. An unannotated table lists variant: "primary" | "secondary" | "ghost" | "destructive" and stops, which tells the agent the values are legal and nothing about which to pick. The annotated version carries, against each value, the single phrase that routes the choice: primary "the one most important action in this section," secondary "supporting actions," ghost "low-emphasis actions in toolbars and dense rows," destructive "irreversible actions only, always with confirmation." Now the agent reading the contract has, at the exact place it chooses a value, the rule for choosing it. That co-location matters more than it looks: a rule about variant values is far more reliably applied when it sits in the variant row of the contract than when it is buried three paragraphs into the prose, because the agent encounters it precisely when it is making the decision the rule governs. Put each rule where the decision it governs is made.

Keeping the Documentation From Going Stale

A documentation layer an agent reads literally has a failure mode worse than being absent: being confidently wrong. An undocumented component at least announces its gap - the agent has only the shape, and you know to review its output. A component documented with a rule that used to be true and no longer is hands the agent an authoritative instruction that is now false, and the agent applies it with the same confidence it applies the correct ones. If your team decided last quarter that the destructive variant now also covers a specific bulk-archive pattern, and the Description still says "irreversible actions only," the agent will refuse the now-legitimate use or route around it, and no one will notice because the doc looks maintained. Stale documentation is not neutral; it actively misleads a reader that cannot tell old truth from current truth.

The discipline that prevents this is to treat the MDX as part of the component's definition of done, not as a separate artifact maintained on goodwill. A change to a component's API or to a usage rule is not complete until the documentation that describes it is updated in the same pull request and reviewed alongside the code. This is the single highest-leverage governance move for documentation, because it removes the gap between when a rule changes and when its description changes - the gap where staleness lives. The same review that catches a missing prop type should catch a Description that contradicts the new behavior. When you wire documentation into the change process this way, the doc cannot silently fall behind the component, because the component cannot ship without it.

Two lighter practices catch the drift that slips past the change process. First, periodically rerun the before/after-style prompt against a documented component and watch whether the agent still behaves as the doc intends; a divergence means the doc and the practice have separated even without a flagged API change, which happens when the team's taste shifts informally. Second, watch for the signal of contributors routinely overriding a documented rule in review - if three people in a month ignore the "exactly one primary per section" rule because the new dense-table pattern genuinely needs two, the rule is wrong, not the contributors, and the documentation should be revised to match the practice rather than the practice bent to match a stale rule. Documentation consumed by a literal reader is a living contract; it earns its authority only by staying current, and it stays current only when keeping it current is built into the work rather than left to whoever remembers.

Key Takeaways

• Knowing a component exists is not knowing when to use it. The MCP connection gives an agent the component's shape (real props, real values); the prop list is a vocabulary, not a usage guide, so an agent uses the right component and real props in semantically wrong ways - the destructive variant on a Save action - unless documentation supplies the understanding the shape lacks.
• Three MDX doc blocks carry the weight. Meta states identity and intended use, including the boundary with neighboring components (use Link, not Button, for navigation). Description is the prose body where tacit usage rules and edge cases live. ArgsTable is the precise prop contract, annotated per-prop with when to use each value, not just its type.
• Document a deliberate five-component subset chosen for misuse-proneness - Button, Modal, Input, Select, and a destructive-action pattern - because five well-documented components teach the pattern and prove the payoff better than fifty half-documented ones.
• AI drafts the generic scaffolding; you supply the team-specific rules it cannot know - that your destructive variant is reserved for your confirmation pattern, that your modals are for single decisions, that your select degrades past twenty options. Those rules live in your practice, not the model's training data.
• Prove it with the before/after diff: the undocumented component yields a hallucinated confirmColor prop or a misused variant="primary"; the documented one yields the correct variant="destructive". Same prompt, same connection, same agent - the only changed variable is the documentation, which is the strongest possible proof of its value.
• This is design work, not tech writing. Prop types come from code, but the usage rules and component boundaries are design decisions that live in the designer's head, accumulated through hundreds of reviews. Writing them into MDX makes implicit taste explicit and self-applying - the same leverage-positive move as building the token system, one layer up.