A design system you can read at a glance

A design system nobody could read at a glance

Start with one question. A business analyst planning a screen asks: is the date filter ready to use, or still a draft? The honest answer was to ask a developer, or to open the component's story and guess. The same question came up for every component, every rule and every open decision.

I work as a Design Engineer on an enterprise platform with a growing component library. It had a catalog of components, patterns and screens, business rules tied to some of them, and a list of open design decisions. Each lived in a different place: stories in Storybook, rules in spec files, decisions in a document.

Nobody could answer, in one place, what was ready, what was still a draft, which rules had passing tests and what was waiting on a decision. Business analysts had also started prototyping in HTML with AI tools, with no guarantee that the result used the real components.

What I owned

I was the only person building this. I decided what to measure, wrote the collectors that read the code and the specs, built the dashboard and wrote the documentation that the tools and the people share. The front-end team and the business analysts are the readers and users.

Where status goes missing

Before building anything I audited the system the other way round: I ran an accessibility, interaction and visual-regression pipeline over the real screens and compared them with the design system.

Modules of the real product audited, one at a time

14

Inconsistencies found, 28 of them confirmed in the real code with a root cause

31

• Not knowing what is ready

  A component could be finished, half documented or abandoned, and the only way to tell was to open its story.

• Rules with no visible coverage

  A business rule could exist without a test or a structured spec, and nothing showed the gap until someone went looking.

• Decisions with no owner or blocker

  Open questions sat in a document, with no trace of what each one was waiting for.

Choices I made, and what I gave up

• A health score from evidence, not from opinion

  Each front of the system (foundations, atoms, patterns, business rules, distribution) is scored from collected evidence, and the pieces are linked only by JSON files. That keeps the dashboard dumb: it shows what the collectors found and cannot invent a status.

• A dashboard route, not a separate tool

  The dashboard is a route inside the same Next app and embeds Storybook without depending on the visual-testing service's login, which would have put the catalog behind another account.

• Find, prove and equip, not fix

  I scoped my role to finding problems, proving them with evidence and equipping the people who fix them. The fixes in the product code stay with the front-end team, so the catalog and the tools are where my effort goes.

One place that answers the question, and two pipelines that use it

The dashboard opens on the counts that matter (ready and draft components, rules implemented, decisions pending) and a short list of what needs attention. From there, each section lists its items with a detail panel and a live preview, and every open decision shows what it is blocked on.

1. Home→
2. Section→
3. List→
4. Item detail

For business analysts: prototypes made from the real components

Two skills turn a Notion spec into an HTML prototype built only from the design system. The first reads the spec into a structured flow file. The second builds the prototype and runs a validator that checks component names and tokens before handing it back.

Of its elements sat inside a design system component

~94%

Of its CSS classes existed in the real component code

87.7%

I measured this once, by hand, on one flow (three states, 374 elements, 37 components). It is a spot check, not a benchmark, and the validator does not check props or internal structure.

For front-end developers: check the catalog before building

A developer pastes a task and the AI looks up the catalog through the Storybook MCP before writing anything: what already exists and which props it really has. It then builds from the design tokens and conventions, writes the story, and runs accessibility and interaction tests. Moving the finished component into the production repo is still done by hand.

What exists, and what I can't claim yet

In August 2026 I audited the design system for accessibility and fed the result back into the library. These numbers come from my own weekly reports, not from a measured outcome.

Components audited for accessibility

28

Fixes applied, including the empty state, the date filter and tab and keyboard navigation

6

Components added: Card, Combobox, Input Group, Textarea, Toggle and Tooltip

6

Gaps in the system recorded and prioritized

9

I then used the updated components in two real product modules. Building them showed which of the recorded gaps mattered in practice.

What exists now: a dashboard with six sections, navigable by mouse and keyboard, and two pipelines, one for analysts and one for developers, both built on the same catalog.

The people who saw the dashboard said it will help a lot with governance and organization, and called it excellent and useful. That is feedback, not a measure.

What I would change

I built the dashboard before a team had committed to using it, so how far adoption goes is the open question today. If I started again I would ask one team for one decision first, then build the dashboard around that decision.

The next thing I need is a before and after, for example how many business rules have no test today and how many a quarter from now. Without it, the dashboard describes the system but cannot yet show that it changed.