Design system documentation that actually scores
Most design system entries are component galleries. What we look for instead: decisions recorded, accessibility built into components, adoption evidence, and documentation written for the person in a hurry.
Design system entries are among the most common we receive and among the least well entered. The usual submission is a gallery: here are our buttons, here are our tokens, here is a page of type specimens. All of it true, none of it an answer to the question a Design Systems entry is actually asked — does this system make good work easier to produce than bad work?
The four questions behind the score
- 01
Is it used?
Adoption is the only evidence that a system works.
- 02
Is it decided?
Components encode decisions, not just styles.
- 03
Is it accessible by default?
Doing the right thing must be the path of least resistance.
- 04
Is it maintainable?
Versioning, deprecation, and a way to contribute.
1. Adoption is the evidence
A beautiful system nobody uses is a library. The strongest entries lead with adoption and are specific about it: how many surfaces, how many teams, what proportion of production UI, and — most persuasively — what happened to the things that used to go wrong.
- "Eleven of thirteen product surfaces, 84% of production components by render count."
- "Time to build a standard settings page: four days → half a day."
- "Contrast failures found in audit: 46 → 3, and the three are in a legacy area with a removal date."
- "Two teams have contributed components back; one was rejected with a written reason, which is in the changelog."
If adoption is partial, say so and say why. A system at 40% adoption with a credible plan scores better than one claiming 100% that an editor can disprove by opening two screens of the product.
2. Components encode decisions
The difference between a component library and a design system is that the system has opinions. A button that accepts any colour is a style container. A button with four intents, one of which is destructive and has a required confirmation pattern documented next to it, is a decision made once on behalf of everyone.
A library
- Props for every visual variation
- Docs describe appearance
- "Use whichever looks right"
- Every team re-decides the same questions
A system
- Props for intent; appearance follows
- Docs describe when to use which, and when not to
- One recommended pattern, with the rejected alternative noted
- Decisions made once, recorded, and revisitable
3. Accessibility is in the component, not in the guidance
This is the strongest single signal in a design system entry. If accessibility depends on a developer reading a note, it will fail at scale. If it's in the component, it holds.
- Focus management inside dialogs, menus and sheets — handled by the component, not documented as a warning.
- Colour pairs defined as tokens that can't produce a failing contrast combination.
- Icon-only controls that require a label prop, enforced by types or lint.
- Form fields that can't be rendered without an associated label.
- Motion tokens that already respect reduced-motion.
Where something can't be enforced, the honest move is a lint rule plus a documented exception process — and saying so in the entry.
4. Documentation written for someone in a hurry
Design system docs are read by a developer at 4pm who wants to know one thing. The structure that survives that is the same every time.
| Compared on | Useful | Decorative |
|---|---|---|
| Opening | What it's for, in one sentence | A paragraph of philosophy |
| Guidance | When to use this, when to use something else | "Use thoughtfully" |
| Examples | The real default, plus the awkward case | Only the ideal case |
| Accessibility | What the component handles, what you must do | A link to WCAG |
| Code | Copyable, with the props that matter | A screenshot of code |
| History | Changelog with reasons and deprecations | None |
5. A record of decisions
The single artefact that most raises a design system score is a decision log. Not a changelog of versions, but a record of the arguments: why the system has one date picker and not three, why destructive actions are never the default, why the team rejected a dark mode built on inverted tokens.
A system without recorded reasoning has to re-litigate every decision each time someone new joins. That cost never appears in a roadmap, and it is the largest one a system carries.
What to send
Documentation links we can reach without a login, the product surfaces the system is actually used on, and — if you have one — the decision log. Then one measured claim about adoption.
Note that Design Systems is one of the categories that requires documentation as part of the entry: without it, there is nothing to assess. If your documentation is internal, a read-only export is fine; an editor only needs to see how it reads, not to keep it. Enter your system.
Versioning and deprecation, which nobody enters but everybody needs
A system's second year is harder than its first. What separates systems that survive is not the component set but the machinery around changing it.
- 01
Announce
The change, the reason, and who it affects — before it ships.
- 02
Overlap
Old and new coexist for a stated period, with the old one marked.
- 03
Migrate
A codemod, a checklist, or a person. Not a wiki page and hope.
- 04
Remove
On the date you said. A deprecation that never ends teaches teams to ignore them.
Contribution: the part that proves it's a system
A system with no contribution path becomes a bottleneck, and then becomes ignored. Editors look for evidence that other teams can propose changes and that some proposals were refused — with reasons — because a system that accepts everything isn't making decisions.
Tokens that survive a rebrand
The test of a token layer is whether a visual change can be made without touching product code. Systems that name tokens semantically (surface-raised, text-muted, border-strong) pass it; systems that name them by value (grey-200) don't, because the name stops being true the first time the value changes.
This is worth mentioning in an entry: a rebrand or a dark mode delivered through tokens alone is concrete evidence that the abstraction was right.
Questions we get asked
Can we enter a design system that is only used internally?
Yes — that's most of them. What we need is documentation we can read and the product surfaces where it is used. A read-only export of internal docs is fine.
Does the system need to be open source?
No. Open source neither helps nor hurts the score; adoption and the quality of the decisions do.
What if adoption is only partial?
Say so, with the number and the plan. Partial adoption with a credible route scores better than a claim of full adoption that two screens of the product disprove.
Figma library or code library — which do you assess?
Both, and the relationship between them. A design library that has drifted from the code is a common and visible finding.
How important is accessibility in a design system entry?
Decisive. A system is the one place where accessibility can be solved once for everyone, so a system that leaves it to the consumer is failing at the thing systems are for.
Assessed work that scores highest on ui & consistency
Chosen by score from the work the editors have assessed, not by hand.
- design systems
- documentation
- adoption
Written by
The UXE editors
The team that selects the work, uses it, scores the seven criteria and writes every verdict on this site.
Keep reading
Craft & practice6 min read
UX writing that scores: the words editors actually notice
Interface copy decides how competent a product feels. The error messages, empty states, button labels and confirmations that raise a UX writing score — and the habits that quietly lower one.
The UXE editors
Accessibility6 min read
Accessibility scoring: exactly what editors check, in the order they check it
Accessibility is one of the seven criteria on every UXE entry, in every category. The tests editors run in the first ten minutes, what an honest conformance claim looks like, and why disclosed gaps raise a score.
The UXE editors
Craft & practice6 min read
What separates the best SaaS dashboard UX design from the rest
The patterns behind the best SaaS dashboard UX design: default views that answer a question, density that respects real data, states that are designed, and the performance budget nobody talks about.
The UXE editors