Designing a Design System's Documentation So People Actually Use It

The first design system we shipped for a client had beautiful Figma component libraries and almost no documentation beyond a color palette page. Engineers rebuilt half the components from scratch in code because they didn't know what existed, and design drift crept back in within two sprints. The library wasn't the problem — the lack of a searchable, code-adjacent reference was.

What changed things was moving documentation out of Figma and into a living site that sits next to the codebase, with each component showing its props, states, and a code snippet an engineer could copy directly. Designers still work in Figma, but the documentation site became the single source of truth that both disciplines actually opened during a sprint, rather than a design-only artifact nobody outside the design team looked at.

We learned to document the 'why,' not just the 'what.' A button component page that only shows variants and sizes doesn't stop someone from creating a fifth, unapproved button style when the existing ones don't quite fit their case. Adding a short rationale — 'secondary buttons are for de-emphasized actions in a pair, never used alone' — cut down on one-off variants across three separate client projects.

Search and findability mattered more than we initially budgeted for. On a system with 60-plus components, an alphabetical list wasn't enough; we added tags like 'forms,' 'navigation,' and 'feedback' so someone building a settings page could browse by intent rather than needing to already know a component's name. Usage of the docs site roughly tripled after that change, based on our analytics.

The system that gets adopted is the one that's easier to use than to work around. That means keeping documentation current as part of the definition of done for any component change, not as a cleanup task that happens 'later.' Later rarely comes, and stale docs are worse than no docs because people stop trusting them entirely.