

Until recently, the standard advice was "don't use AI to write design system documentation." That advice fit the moment. Early LLM output was generic, hallucinated rationale, and produced documentation that read fluently but had no specificity to the system it was meant to describe.
The advice has aged. AI tools have improved, and the honest question now isn't "should we use it" but "where does it actually help, and where does it create more work than it saves?" The line between useful and counterproductive has moved, and it'll move again.
This article is about where that line currently sits. It covers what AI is genuinely good at in design system documentation work, what it still gets wrong, the patterns of use that earn their place, and the trap that catches teams who let AI write the whole thing.
The framing throughout is practical. AI is a tool, the same way Figma is a tool or Storybook is a tool. The question isn't whether to allow it. It's how to use it in ways that produce documentation people actually use.
The places where AI consistently produces useful documentation output share a few qualities: the task has a clear structure, the output can be checked against a known reference, and the part that requires team-specific context is small.
Drafting from a clear template is one of those tasks. If you have a documented component page structure (name, purpose, usage, anatomy, variants, states, props, accessibility, do/don't), an AI can produce a competent first draft when given the template, the underlying code, and the visual reference. The first draft is rarely shippable, but it's a workable starting point.
Generating prop tables and API documentation from code is another strength. TypeScript types, JSDoc comments, and similar code artifacts contain most of the information a prop table needs. AI translates that into readable prop documentation faster than a human can. The catch is that the AI needs to be reading the actual code, not guessing at it.
Consistency checks across pages are exactly the kind of repetitive task where AI outperforms humans. Noticing that one component uses sentence case in its examples while another uses title case, or that 80% of your error messages start with "Sorry" but a handful start with "Oops," is mechanical work. Letting AI do the scan and the team review the findings is a faster pattern than reading 200 pages by hand.
Drafting do/don't variations works similarly. Given one good do/don't pair, AI can produce three or four plausible variations to consider. Most won't make the cut. A few will surface mistakes the team hadn't thought to address.
Translation across contexts is one of the clearest LLM strengths. Turning a design rationale into developer documentation, or a code example into a usage guideline. The team has already decided what to say. The AI is restating it in a different register.
Gap identification rounds out the list. Pointing an AI at an existing documentation site and asking "what's missing from this component page that other pages in this library have?" produces useful structural feedback. The AI doesn't need design judgment for this. It needs pattern recognition, which is what it's good at.
The common thread: AI is good at the structural, mechanical, comparison-driven parts of documentation work. The parts that don't require knowing why your team made a particular decision.
The places where AI consistently produces bad documentation output share the opposite qualities: the task requires team-specific context, the right answer isn't checkable against an external reference, or the AI is being asked to invent rationale it doesn't have.
Context is the biggest gap. AI doesn't know why your team named a component the way you did, why the API has the props it does, what mistake the do/don't section is meant to prevent, or which patterns the system has deliberately rejected. Asked to fill in that context, the AI invents plausible-sounding answers. Those answers will be wrong in ways that look right.
Design rationale falls into the same trap. The "why" behind a decision is what makes documentation valuable to future readers, and the why is almost never written down anywhere the AI can access. An AI generating rationale is making up reasons that sound competent. Documentation that contains invented rationale is worse than documentation that admits it doesn't have any.
Novel patterns are another gap. If your design system has a pattern that doesn't have widespread industry precedent, the AI's reference set isn't there to draw from. The output will average toward the closest common pattern in its training data, which is often wrong for your specific case.
Accessibility notes are particularly dangerous. AI is happy to assert that a component "is accessible" or "meets WCAG AA," and those assertions are often wrong. Accessibility claims have to come from actual testing or audited specifications. Letting AI fill in the accessibility section is one of the fastest ways to produce documentation that actively harms users who rely on it.
Voice and tone average toward generic. AI output tends to be polite, slightly formal, slightly verbose, and devoid of the small distinguishing patterns that make a team's documentation feel like its own. Without explicit voice direction, the writing reads as documentation-shaped rather than as the work of a particular team.
The most damaging way to use AI in design system documentation is to generate full pages from a prompt and ship them.
Documentation isn't just words on a page. It's a contract with the reader: someone has thought about the questions you might have and tried to answer them. When the documentation is generated wholesale, the contract is broken even when the words are fine. Readers can tell. They develop a sense that the documentation is approximately right but not really sure of itself, and they start treating it that way.
The trust problem compounds. Once readers learn that they can't take a particular kind of statement at face value (the accessibility claims, the rationale sections, the example code), they start checking everything. The whole documentation site becomes a source of suggestions rather than answers, and the teams that were supposed to use the documentation go back to messaging the design system team directly.
There's a related failure mode where AI generates documentation and a human "reviews" it before publishing. The review tends to be light: catch the obvious errors, ship the rest. Light review doesn't catch the kind of subtle wrongness AI produces. A prop that doesn't exist gets caught. An invented design rationale doesn't.
The pattern that works is the inverse: humans write the structural and rationale parts, AI accelerates the mechanical parts, humans review and ship. The AI is doing work that's checkable against reference material. The humans are doing work the AI can't credibly do.
A useful test: would a reader be able to detect that a section was AI-generated by reading it? Yes? It needs a human pass. No? The AI can take a heavier hand because the section is mechanical enough to be checkable.
There's a useful distinction between using AI as a writer and using it as an assistant.
Using AI as a writer rarely works well. The team writes a prompt. The AI generates a page. The team reviews lightly and publishes. The work the AI did invisibly (deciding what to emphasize, what to leave out, what rationale to claim) shapes the whole page, and the reviewer can't easily see what the AI chose to invent.
The alternative is to use AI as an assistant. The team writes a draft, or an outline, or a structured set of decisions. The AI fills in the mechanical parts: prop tables, do/don't variations, formatting passes, consistency checks. Or it reviews what the team wrote and points out gaps, unclear language, or inconsistencies with other pages. The team stays in control of what the documentation says. The AI accelerates the process of writing it down.
The same distinction applies at a smaller scale. Asking AI to "rewrite this paragraph for clarity" is assistant work; the team chose the substance, the AI cleaned the surface. Asking AI to "write a paragraph explaining when to use this component" is writer work; the AI is making substantive choices the team should be making.
A practical rule: AI handles work that's checkable against an external reference, such as code, an existing template, or another page in the docs. The work that requires inventing or judging stays with humans.
A few practical changes worth naming.
Templating gets faster. With a documented component page template, AI can produce competent first drafts of new component pages in a fraction of the time it used to take. The draft isn't the finished page, but it's a workable starting point.
Consistency reviews get cheaper. Pulling an entire docs site through an AI consistency check (sentence case, terminology, voice) is a job that used to take a content designer days. It's now a script that runs in minutes. The findings still need human judgment to act on, but the discovery cost has collapsed.
Cross-referencing gets more thorough. AI is good at noticing when a button mentioned on page X isn't linked back from page Y. The cross-linking density that good documentation needs is finally tractable to maintain.
Component-level documentation gets generated from code. TypeScript types and prop comments are reliably translatable into prop tables. This was always possible with tools like react-docgen, but AI extends the pattern to looser code that wasn't written with documentation tools in mind.
Documentation discovery is changing too. Chatbots-over-the-docs are gaining traction, including one built against the zeroheight API. Whether they replace the docs site is an open question, but they change how documentation gets consumed.
Contextual help is where this gets interesting. Surfacing relevant documentation directly inside the design tool or IDE, prompted by what the user is actually doing, is a workflow that's only really feasible with AI in the loop. Most teams aren't there yet, but the direction is clear.
A few places where the work should stay in human hands.
Design rationale and decision context. The why behind a decision is the most valuable thing in good documentation and the thing AI is least equipped to produce.
Accessibility notes. Claims about WCAG conformance, ARIA behavior, or screen reader support have to come from testing, not from generation. AI-written accessibility sections are a liability.
Voice and tone. Without explicit, narrow direction, AI averages toward generic. If your team has a distinctive voice, AI output will smooth it out.
Anti-patterns and do/don'ts that respond to real mistakes. AI can produce plausible do/don'ts, but the ones that matter are the ones that address things your team has actually seen go wrong. AI doesn't know what your team has seen.
Novel components and patterns. If a component is novel to your system, AI will pattern-match to the closest common precedent in its training data, which is often wrong for your specific case.
The shape of the answer: use AI for the parts of documentation that look the same across most design systems, and reserve the writing yourself for the parts only your team knows.
AI changes the cost structure of documentation work but doesn't change what good documentation looks like. The qualities from Article 02 (clarity, depth, consistency, discoverability, maintainability) are the same. The work to meet them is partly cheaper now, and partly identical to what it was.
For practical prompts and patterns you can use today, the companion blog post ChatGPT prompts for component documentation covers specific examples.
The other articles that pair well with this one are Article 03 (How to document a design system component) for the structural template AI works against, and Article 13 (Keeping your design system documentation up to date) for how AI fits into ongoing maintenance.
