Skip to content
UXE Award

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.

The UXE editors5 min read

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

What we assess
  1. 01

    Is it used?

    Adoption is the only evidence that a system works.

  2. 02

    Is it decided?

    Components encode decisions, not just styles.

  3. 03

    Is it accessible by default?

    Doing the right thing must be the path of least resistance.

  4. 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.

The same components, two philosophies

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.

What each doc page needs
Compared onUsefulDecorative
OpeningWhat it's for, in one sentenceA paragraph of philosophy
GuidanceWhen to use this, when to use something else"Use thoughtfully"
ExamplesThe real default, plus the awkward caseOnly the ideal case
AccessibilityWhat the component handles, what you must doA link to WCAG
CodeCopyable, with the props that matterA screenshot of code
HistoryChangelog with reasons and deprecationsNone

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.
From a Design Systems assessment

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.

Deprecation, done properly
  1. 01

    Announce

    The change, the reason, and who it affects — before it ships.

  2. 02

    Overlap

    Old and new coexist for a stated period, with the old one marked.

  3. 03

    Migrate

    A codemod, a checklist, or a person. Not a wiki page and hope.

  4. 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.