05In developmentMIT
Design System Maturity Check
A 24-question self-assessment that scores a design system across documentation, versioning, governance and adoption, and returns level-appropriate next steps for each.
Awaiting real capture — /media/design-system-maturity-check/interactive-run.mp4
Screen recording: the terminal assessment being answered question by question, with the help text expanded on one of them.
The interactive run. Twenty-four questions, keyboard only, roughly ten minutes.
The problem
Most maturity models are a slide with five columns and no instructions. They tell a team it is level 2 and leave it there, which is the least useful half of the exercise: the gap was never the diagnosis, it was knowing which three things to change before the next quarter. Worse, the advice that does exist is written for a system that already has a design council and a token pipeline — level-5 answers handed to a team that still has no changelog.
Awaiting real capture — /media/design-system-maturity-check/report.avif
The rendered report: four dimension scores with their level names, each followed by three effort-tagged next steps.
The report. Four scores, and twelve things to do — sorted by effort, not by severity.
Awaiting real capture — /media/design-system-maturity-check/comparison.avif
A second run compared against an earlier JSON export, showing the change in each dimension.
A quarter later, compared against the earlier export. No database was involved.
How it works
The score exists to select the advice.
Every level in every dimension carries three concrete, effort-tagged next steps written for a team at exactly that level. A level-2 team is never handed level-5 advice, because the number is a lookup key, not a verdict.
Four dimensions, one question each.
Documentation: can a new team use a component without asking anyone? Versioning: can you ship a breaking change without breaking trust? Governance: who decides, how fast, and is that written down? Adoption: do teams actually use it, and do you know?
The arithmetic is deliberately boring.
Answers are worth one to five points, questions carry a weight of one to three, and a category score is the weighted mean of the questions that were answered. The overall score is the unweighted mean of the four categories, so no dimension wins by having more questions. An honest “I don’t know” is skipped, never counted as zero.
The export is the database.
There is no account and no server, so a JSON export is the persistence layer. Re-import last quarter’s file and the report renders the delta. Free-text notes stay in the local export and are never encoded into a share link.
The catalog is data, not code.
Questions, weights and next steps are plain JSON validated against a published schema. The same engine can assess API governance or content operations by swapping the catalog — which is also how a team replaces our wording with their own.
What it does and does not do
Detected automatically
- A weighted score per dimension, and an overall score that weights each dimension equally.
- A level band from 1 (Ad hoc) to 5 (Optimising), with the threshold that produced it stated in the report.
- Three next steps per dimension, selected for the level reached and tagged with the effort they take.
- The delta against an earlier JSON export, dimension by dimension.
Needs a human
- Whether the answers are honest. This is a self-assessment; nothing reads your repository to check.
- Whether a practice that exists on paper is actually followed by the teams using the system.
- Whether a low score matters here. A two-person team with one product may be right to stay at level 2.
- Which of the three next steps is politically possible this quarter.
100% local.
Everything runs in your terminal. No account, no telemetry, no network call — the questions ship with the binary and the report is rendered locally. The only thing that ever leaves is a file you exported on purpose.
- License
- MIT
- Status & roadmap
- CLI in development, first release pending. Next: a static web version running the same engine, so a workshop can answer it on a screen instead of a laptop. After that, published reference catalogs beyond design systems.