← Back to LabDebora’s Lab / Publication

Your design system doesn’t need more components. It needs better evidence.

A practical way to find repeated decisions, separate useful variation from drift and decide what a design system should actually own.

Written from practice↓ Read the field note
[ 00 / Premise ]

I used to think the first job of a design system was to define the right components. The product taught me to start somewhere less comfortable: with the decisions teams were already repeating.

[ 01 / 04 ]

The visible problem was inconsistency

TAP Mindset had eight card variations, six chips and four inputs. Most looked related but behaved differently. Consolidating them sounded like the obvious answer.

The deeper problem was maintenance. Knowledge lived in individual files and documenting a component took 45 to 60 minutes. Every new feature made the library harder to understand.

[ 02 / 04 ]

Count usage before drawing the answer

I mapped the critical flows and inspected more than 28,000 component instances. I was not looking for the most popular rectangle. I was looking for repeated product decisions.

  1. Load-bearing patterns used across critical journeys.
  2. Accidental variants representing the same concept.
  3. Local exceptions created for a constraint that had never been evaluated systemically.
28,000+Instances audited
55 → 38Public concepts
45 → <2 minDocumentation time
[ 03 / 04 ]

Turn the audit into a decision tool

For each cluster I recorded its job, states, usage, behavioural differences and cost of change. That changed the review from ‘which version looks cleaner?’ to ‘does the product need these concepts to behave differently?’

The useful output was not a giant spreadsheet. It was a smaller set of decisions with enough evidence for Design and Engineering to challenge together.

[ 04 / 04 ]

What I would reuse

Start with one important journey, capture concepts rather than screenshots and record uncertainty explicitly. Do not promote a pattern into the system just because it appears often: repetition can be evidence of debt too.

The goal is not perfect consistency. It is a system where a shared decision is easier to use than another local exception.

[ Technical evidence ]

Three artefacts. One inspectable system.

The proof follows the same path as the work: inventory what exists, structure the decisions, then publish the result where Design and Engineering can question it together.

01 / Code inventory

First, I made the real maintenance surface visible.

Each component lived with its implementation, styles, Storybook story and public export. The inventory let me compare product concepts instead of relying on a collection of screenshots.

VS Code repository showing the component inventory and the files that make up AppHeader.
02 / Token architecture

Then I separated values from meaning and component decisions.

Core, semantic and component layers use typed JSON and aliases. Style Dictionary transforms the same inspectable source instead of asking every component to store its own interpretation.

VS Code showing tokens.json with core, semantic and component layers and token aliases.
03 / Shared reference

Finally, the decisions became visible where the team reviewed the work.

Storybook connects the token inventory with the components that actually ship. Designers can inspect intent and states; engineers can follow the same decision into its API and source.

Storybook Design Tokens Library showing token categories, downloadable JSON files and token values.
[ Open materials ]

What you can reuse.

Not just a conclusion: these are the working artefacts behind the argument. Open them, question them and adapt what is useful.

01

Layered token source

Core, semantic and component decisions expressed as inspectable JSON aliases.

Open tokens.json
02

Component anatomy

A real component kept beside its styles, story and public export.

Inspect AppHeader
03

Published token inventory

The maintained token source exposed where the team reviews the system.

Open Storybook