How to write component documentation that people actually read

Design system documentation is almost universally bad. Not because the people writing it are bad at writing. Usually they're not. The goal is wrong.

The goal of most component documentation is completeness: cover every prop, every variant, every edge case. The goal should be usefulness at the moment someone needs it. These are different things, and optimizing for completeness produces documentation that's technically thorough and practically useless.

Who reads documentation and when

Before you write a word of documentation, ask who reads component documentation and what they're trying to do when they do.

The answer is almost always: a developer or designer is building something, they've selected a component, and they have a specific question. The question is usually one of: how do I use this, which variant should I use for this case, or what are the rules for when this component applies.

Nobody sits down to read component documentation the way they'd read a book. They land on it mid-task with a specific question, they want an answer, and then they leave. Documentation written for sequential reading will not serve them.

The page structure that works

Every component doc page should answer four questions in this order:

What is this for? One or two sentences. Not a technical description of what the component renders. A description of the problem it solves and the context where it belongs. "Callout is for editorial content that needs to stand out from surrounding prose. It works in documentation and long-form articles." Not "Callout renders a styled container with optional icon."

Which variant should I use? This is where most people go first, and most docs put it last. A usage guide that explains when to use each variant saves more time than a comprehensive prop table. Not what each variant looks like. When to choose it.

The props. The prop table is not optional, but it shouldn't be the whole document. Type, default, required, description. The description is the one people actually read; make it specific. "Controls the color scheme. Use 'warning' for cautionary information and 'error' for validation failures, not interchangeably" is more useful than "Sets the variant."

The things that break it. What shouldn't you do with this component? What misuse have you seen? Where do designers or developers commonly go wrong? This section often doesn't exist at all. It should. It's where the real expertise is.

The variant descriptions nobody writes

Prop tables tell you what the values are. They don't tell you when to use them.

"Variant: default | surface | outline" tells me the options. It doesn't tell me that default is for inverted contexts where you need strong visual weight, that surface is the neutral choice for most cases, and that outline is for when the component needs to sit on a colored background without fighting it.

Most designers and developers using your system don't have the institutional context to know this. They'll guess. They'll usually guess wrong. Documenting the decision logic is one of the most valuable things a design system team can do, and it's almost always skipped. Why these variants. When each one.

The dos and don'ts pattern (and its limit)

Dos and don'ts sections with visual examples are genuinely useful. A side-by-side showing correct and incorrect usage communicates faster than paragraphs. They're worth the production time for components that get misused in consistent, predictable ways.

But they have a limit: they show the cases you thought of. The misuse you didn't anticipate is the one that will actually happen. Pair visual examples with written rules stated directly, not just implied by the examples. "Never use a Badge as a button or interactive element" should appear as text, not just be inferable from the Don't example.

Code examples are not optional

For engineering audiences, a working code example is more useful than any amount of prose. Not a prop table. Actual usage. The simplest version of the component doing what it's most commonly asked to do. If there are two significantly different usage patterns, two examples.

The code in the documentation should be copy-pasteable and should actually work. This sounds obvious and it's often false. Documentation written by designers frequently includes code that references internal variables, imports from non-standard paths, or uses prop names that don't match the actual implementation.

If you can't have a designer write working code examples, pair with an engineer to produce them. The documentation for a design system is partly an engineering artifact.

Keeping it current

The hardest problem in design system documentation isn't writing it. It's not letting it go stale. Documentation that describes the old behavior is worse than no documentation, because users trust the documentation, act on it, and discover the mismatch.

The practical fix: documentation changes get merged with component changes. Not after. At the same time. The PR for a component update includes a documentation update. This requires treating documentation as part of the component, not as an artifact that lives in a different system and gets updated asynchronously.

If your documentation lives in a tool that isn't tightly coupled to your component implementation, this is a sign that the architecture isn't set up to maintain it. Either fix the architecture or accept that the documentation will drift.

---

Great component documentation is a user experience problem, not a writing problem. Your users are developers and designers under time pressure. They have a question. Design the documentation to answer it.