Here's a number that should bother you: 89% of design systems ship code examples, but only 37% include usage guidelines. The components exist. The props are typed. The Storybook stories render correctly. And developers are still rebuilding buttons from scratch.
That's not a component problem. That's a documentation problem — and it's more structural than most teams admit.
Code Examples Are the Floor, Not the Ceiling
When a team ships a component, the first thing they document is how to render it. Makes sense. It's the easiest thing to write, it's what Storybook generates automatically, and it gives you something to point at in a PR. Done.
But "here's how to import and render this component" answers exactly one question: can I use this? It doesn't answer the questions developers actually get stuck on: should I use this here? What's the difference between this and that other similar component? What does the design team expect when I reach for this pattern?
The analysis of 158 design systems makes the drop-off visible. 89% have code examples. Usage guidelines: 37%. Accessibility documentation: 21%. Content guidelines: 13%. Each layer that requires judgment — rather than just syntax — gets skipped. The systems that score across all seven layers are Shopify Polaris, Twilio Paste, and eBay Playbook. The gap between them and the median isn't a resources gap. It's a prioritization gap.
The pattern this reveals: teams document what's easy to generate and defer what requires thinking. Code examples are automatable. Usage guidelines require someone to make a decision about intent.
The Comprehension Gap Is a Velocity Problem
This is where the tradeoff bites. A design system with thin documentation doesn't just create confusion — it creates parallel work. One team at 45 production-ready components watched developers rebuild buttons, forms, and modals from scratch. Not because the components were bad. Because "we never had time" for documentation — it was always the thing that would happen after the next release.
That's the trap. Documentation feels like overhead until you calculate what undocumented components actually cost: the duplicate implementations, the inconsistency bugs, the onboarding time for every new developer who has to reverse-engineer intent from props.
I'd argue the velocity hit from poor documentation is worse than the velocity hit from a slightly over-engineered API. A complex API with good usage guidelines gets learned once. An undocumented component gets re-investigated every time someone new touches it.
The broader failure mode is that design systems don't collapse because of bad components — they collapse because the understanding of how and why to use those components was never made explicit. The artifacts exist. The mental model doesn't transfer.
What Actually Needs to Be Written
The shadcn/ui model is instructive here, even if it sidesteps the problem rather than solving it. When you run npx shadcn-ui@latest add button, you get the component source directly in your repo. You own it. You can read it. The CVA variant system makes the intent legible from the code itself:
const buttonVariants = cva(baseStyles, {
variants: {
variant: {
default: '...',
destructive: '...',
ghost: '...',
}
}
})
The variant names are documentation. destructive tells you something. ghost tells you something. This is better than a component that exposes type="secondary" with no indication of when secondary is appropriate.
But even well-named variants don't answer the harder questions: when do you use ghost vs outline? When is a destructive action appropriate without a confirmation dialog? Those decisions live in usage guidelines — the 63% of systems that don't write them are leaving developers to guess.
The three things that actually need to be written, in priority order:
When to use vs. when not to. This is the highest-value documentation and the most commonly skipped. A single paragraph that says "use this for primary actions; if you have more than one primary action on a screen, reconsider your information hierarchy" prevents more bugs than a dozen code examples.
The relationship between similar components. If your system has both a Modal and a Drawer, document the distinction explicitly. Developers will pick one arbitrarily if you don't.
What the design team expects. Not just what's technically possible, but what the system is optimizing for. This is the layer that most systems never make explicit — and it's the layer that determines whether the system actually produces consistent product decisions.
The Heuristic
If your component has more than two variants, it needs a usage guideline — not a code example for each variant, but a written decision rule for when each one applies. Write it before you ship the component, not after. Once the component is in production without documentation, it will never get documented; there's always something more urgent, and the window closes permanently.
The 37% of systems that write usage guidelines aren't doing it because they have more time. They've decided that undocumented components aren't actually done.