Write Design System Documentation That Stays Up to Date
Use when your team needs written docs for its design system. It sets what to cover, splits the work into pages by priority, explains each component by answering what, why, when, and how, and checks that docs, design, and code match before release.
To use this AI rule
## Decide What the Docs Cover, from Principles to Components
Document both the system’s intangible foundations—principles, decisions, and ways of working—and its tangible assets: patterns, components, usage rules, and implementation tools. Make the scope visible before writing so omissions become backlog items rather than surprises.
## Split the Docs into Pages and Start Where People Struggle Most
Break the work into self-contained pages. Prioritize areas causing the most friction, then frequently used or dependency-heavy components. Track progress and review priorities as constraints change. Use any tool the team can maintain, search, and share reliably.
## Explain Each Component by Answering Four Questions
For every component, answer four questions: What is it, including its states and options? Why choose it over similar alternatives? When does its context make it appropriate? How should it be used, including supported variations, examples, and explicit dos and don’ts?
## Write for Designers and Developers First, and Keep It Short for Others
Serve designers and developers first with clear behavior, decision criteria, implementation references, and code or story links. Give product, QA, and research roles a shorter verification path. Reuse strong patterns from other systems, but adapt them; functional access matters more than visual perfection.
## Check That Docs, Design, and Code Still Match Before Release
Treat documentation as a living product. Review new components and guidance in critiques, assess documentation needs at project kickoff, test components with users and accessibility checks, and verify design-code-documentation alignment before release. Change maintenance rituals when evidence shows they do not work.