Why Design System Documentation Goes Out of Date

You can script a token rename. You can't script the paragraph that explains it. That gap is where your documentation drifts.

Your design system documentation is out of date. You know roughly where, and you have known for a while.

The usual explanation is that the team is stretched, which is true and is not the mechanism. Documentation drifts on well-resourced systems too, including ones where every automated pipeline works exactly as designed. It drifts because one specific part of the job stayed manual, and that part gets more expensive every time the system grows.

Take a single component description. It lives in the Figma component's description field, in your component inventory, and on the component's documentation page. Three copies of one sentence, kept in step by hand. Change the component and you owe three edits, and the third one is the one that quietly doesn't happen.

Multiply that by a real library.

The maintenance load is a number you can calculate

Design system documentation goes stale because the work of keeping it current grows with the system, while the time available to do it stays flat.

@gitlab/ui, at version 137.1.1, ships 138 components and 7,245 token values across 71 token files. In the last 365 days it published 162 releases, which is a new version every 2.25 days.

Now pick an ordinary decision. You rename a component, or you change a naming convention, or you deprecate a pattern. For each affected component you touch:

• The description in Figma
• The entry in your component inventory
• The component's own documentation page
• Every other page that references it by name
• Every usage example, code sample and screenshot caption that uses the old name

Call it five locations, conservatively. Across even a fifth of that library, one decision becomes well over a hundred edits. None of them are difficult. All of them are manual, and every one is a chance to miss something.

That work competes with shipping the next component, and shipping wins. So the edit doesn't happen, the docs fall a little further behind the system, and the gap becomes permanent.

Why scripts stop at the door

The obvious response is to automate it, and for some of this you already have.

Tokens are structured data. Component metadata is structured data. Deprecation flags, version numbers, prop tables, dependency graphs. Teams have written scripts against all of it for years, and those scripts work, because the input has a schema and the transformation is deterministic.

Documentation is prose.

A script can rename border-radius-md in every file it appears in. It cannot rewrite the paragraph explaining when to reach for it. It cannot notice that the usage example three sections down now contradicts the new name, or that a guidance note on an unrelated page still tells people to avoid a component you un-deprecated in March.

That work needs something that can read the sentence, understand what it's asserting, and decide whether it's still true. Until recently the only thing that could do that was a person, and a person doing two hundred pages is a week nobody has.

So documentation became the layer of the design system that never gets a maintenance pass. Not because teams don't care about it. Because it was the only layer where the cost of a pass scaled with the size of the system and couldn't be brought down.

What's actually sitting in your backlog

Ask any design system team what they'd fix given a free week and the answers rhyme:

• The naming convention we changed and only half-applied. Everyone knows which half.
• Ten component pages with ten different structures, because they were written by six people over three years.
• References to a component we deprecated, still sitting in guidance nobody re-read.
• A block setting we want changed everywhere, which means opening every page it appears on.
• Descriptions maintained in three places, drifting apart at their own pace.

None of these are hard problems. They're long ones. They sit in the backlog for quarters because each is a day of clicking and there's always something with a deadline in front of it.

What changes when an agent can edit the documentation

Agents could already read a design system. Connecting one over MCP meant an agent could ask what the spacing token was or which variants a button had, and answer from your system instead of guessing.

Reading solves consumption. It does nothing for maintenance.

Supernova's Editor MCP makes the connection two-way, so an agent can change documentation as well as read it. That covers the semantic pass a script can't do: reading two hundred pages, working out which ones assert something that's no longer true, and rewriting them. It also covers the bulk property work, like changing a block setting across every page it appears on, or aligning ten component pages to the structure of the best one.

Everything it does is also possible in the interface. The difference is that a job measured in days becomes a job measured in minutes, which is the difference between a task that gets done and one that doesn't.

Three things worth knowing about how it behaves. Publishing asks for confirmation twice, because publishing is destructive. Every change lands in page history, so you can see what moved and put it back. And actions are attributed to you, the connected user, rather than to an anonymous agent identity.

Where this still needs a person

A semantic pass over your documentation is not deterministic. Ask an agent to remove every reference to a sunset feature and it will find most of them, not provably all of them. It may also decide a sentence is about that feature when it isn't.

That's why the confirmation step and the page history matter more than they sound. The workflow that holds up is the one where the agent proposes at scale and you review before it publishes, which is roughly the same relationship you'd have with a capable contractor rather than a build script.

It also doesn't fix a documentation problem that's really a governance problem. If three teams disagree about what a component is for, an agent will faithfully propagate the disagreement across every page. Decide first, then propagate.

And the three-copies problem underneath all of this is still a structural one. Automating the sync is a real improvement over doing it by hand. Having one source the other surfaces read from is better than either.

Start with the one that annoys you most

Don't plan a documentation overhaul. Pick the single item from your backlog that you've re-read and postponed most often, and do that one.

The naming convention you half-applied is a good candidate, because you already know it's wrong, you already know roughly where, and you'll be able to tell immediately whether the result is right. Run it, read the diff in page history, and decide from there whether the rest of the list is worth reopening.

Your documentation didn't drift because you were careless. It drifted because the pass was too expensive to run. That's the part that changed.

See how agents read and write your design system.