Design system documentation people actually read

Right now, if you open the documentation site of a lot of design systems, you'll find long pages that describe every property of a component, and very little about when to use it. People skim them once and go back to copying whatever the last developer did. Documentation people actually read answers the question they have at the moment they open it, which is almost always: which component should I use here?

Start with when to use it, and when not to

Put "when to use" and "when not to use" at the top of every component page. The second one matters more than it looks, because it's what stops people reaching for the wrong component. Point them to the right one while you're at it.

Show one real example

One example from a real screen in your product is worth more than a grid of every variant. People copy examples, so make sure the example is the thing you want copied.

Keep it next to the code

Documentation on a separate site drifts away from the code, because updating it is a separate job. A short file next to each component gets updated in the same pull request as the component. Coding agents read it too, which matters now that they're building screens from your system.

Name an owner

Give each part of the system an owner, and put their name on the page. When people know who to ask, they ask, instead of working around the component. And when nobody owns the docs, they slowly stop describing the system you actually have.