Documentation that answers real questions
Good documentation is written for someone in the middle of building something. For each component and pattern it covers:
| Section | Answers |
|---|
| When to use | Which problem this solves - and what to use instead in similar situations |
|---|
| Anatomy and variants | What the parts are and which variants exist |
|---|
| States and behaviour | How it behaves in every state, on every device |
|---|
| Content | Label length, tone, error and status wording |
|---|
| Accessibility | Keyboard behaviour, focus, screen-reader output, contrast values |
|---|
| Do and don't | Real examples from your product, including common mistakes |
|---|
| Code | Component name, props and token references for engineers |
|---|
| Changelog | What changed, when and why |
|---|
Rules should be specific enough to settle a disagreement. "Use primary buttons sparingly" is advice; "one primary button per view" is a rule. The same principle drove the infrastructure brand system's measurable specifications - see enforceable design systems vs style guides.
Governance: five decisions to make
Ownership. A named person or small team maintains the system and approves changes. In smaller companies, often one designer and one front-end engineer with protected time.
Contribution. A lightweight route for teams to propose new components or changes: check the system, propose with a use case and draft, review, build, document, release.
Release and versioning. Regular, small releases with a changelog and clear migration notes for breaking changes.
Deprecation. Old patterns marked deprecated with a replacement and removal date, and usage tracked until it reaches zero.
Exceptions. A way to approve justified one-offs with a reason and an expiry date - and a review of repeated exceptions, which usually signal a missing component.
Governance that speeds teams up
The goal of governance is fewer decisions, not more approvals. Anything built from existing components, tokens and patterns should ship without extra review; only genuinely new patterns go through the contribution process. When governance works, it measurably speeds delivery - Figma found designers completed a task 34% faster with a design system - because people stop re-deciding solved problems.
Health metrics
| Metric | What it tells you |
|---|
| Component coverage in production | How much of the product actually uses the system |
|---|
| Detached or overridden instances | Where the system isn't meeting needs |
|---|
| Hard-coded values in code | Where tokens are being bypassed |
|---|
| Contribution requests and response time | Whether the system responds to teams |
|---|
| Accessibility defects from custom UI | Where bypassing the system creates risk |
|---|
| Time to build a standard screen | Whether the system is delivering speed |
|---|
Reviewed monthly, these numbers show where to invest next - and give leadership a reason to keep funding the system.
