Even well-intentioned teams make the same mistakes when building design system documentation. Here are the ones worth watching for.

1. Documenting how, not why: Most documentation explains what a component looks like and how to implement it. Almost none explains why a decision was made. That context is what people actually need when they're trying to adapt something to a new situation.

2. Letting documentation go stale: Teams write thorough docs at launch, then stop. Outdated documentation is worse than no documentation in some ways, because it points people toward deprecated patterns with total confidence.

3. Writing for one audience: Designers, developers, content writers, and product managers all use the same component pages but need different things from them. If you only write for engineers, designers will stop reading. Build in layers.

4. Documenting every edge case: There's a version of thoroughness that becomes a wall of text nobody reads. You don't need to cover every variant upfront. Progressive disclosure exists for a reason.

5. Skipping accessibility guidance: ARIA attributes, keyboard navigation, color contrast ratios, focus management. If this isn't in the docs, someone will ship a non-compliant implementation and be surprised when it gets flagged. It always gets flagged.

6. Poor navigation and no search: Good content buried in a confusing structure might as well not exist. If someone can't find something in under a minute, they'll build their own version instead.

7. No contribution guidelines: Without a clear process for adding to the system, teams quietly build one-off components and never document them. That's how shadow design systems start, and they're a pain to untangle later.

8. Missing version history: When breaking changes ship without release notes, teams on older versions have no way to know what changed or why things broke. Versioned documentation is not optional once you have multiple teams depending on the system.

Most of these failures aren't about effort. They're about not treating documentation as a product that needs ongoing maintenance.