Access code

This case study requires a six-digit access code. If you do not have one, contact me and ask.

Design Systems

Most design systems do not die of bad components. They die of undocumented deviation and governance nobody owns. The systems I build treat both as first-class problems.

  • Design Tokens
  • Component Libraries
  • Governance
  • Dual Documentation

How I work here

I build over the stack that exists. Rebuilding from scratch is usually indefensible; on the procurement platform the answer was a custom library on top of MUI and AG Grid: the scalability of the frameworks, a tailored visual identity, and a tokenized consistency layer.

Every component is documented twice: the UX intent, and exactly how and why it deviates from the framework default. That dual record is what prevents a system from quietly forking from its own foundation, and it is what turns a system into a delivery interface engineers can work from autonomously.

Adoption is designed, not assumed: governance cadences, decision logs, and terminology alignment, because language governs adoption more directly than component quality does. This is also the one area I take on as a standalone engagement: establishing or repairing a foundation, including the audit of one already in production.

Tokens first: the architecture layer

A system that starts at the component level inherits every inconsistency it was meant to remove. The work starts one layer down: primitive tokens for color, type, and spacing; semantic tokens that give them meaning per surface; component tokens only where a component genuinely needs its own vocabulary. That ordering is what makes theming, dark surfaces, and multi-brand variants mechanical instead of heroic.

Most real systems live on top of an existing stack rather than a blank page. Extending an established library means keeping its scalability while imposing a consistency layer above it: the framework does the heavy lifting, the tokens carry the identity, and the system stays upgrade-safe because it deviates deliberately instead of forking accidentally.

Documentation that keeps a system honest

Components get documented from two angles at once: the UX intent, and exactly how and why the implementation deviates from the framework default. The second half is the one teams skip, and it is the one that matters. Undocumented deviation is how a system quietly forks from its own foundation until neither designers nor engineers trust it.

Good component documentation reads like an API contract: states, permitted content, accessibility criteria, and the decision that shaped each. Written that way, the system stops being a design artifact and becomes a delivery interface engineers can build from without a translation step.

Governance, adoption, and the audit

A system without a decision-making model decays at the speed of its busiest sprint. Governance is designed like a product: who may propose, who approves, how versions roll out, where decisions get recorded. Terminology gets aligned early and mechanically: component names match what the code exports, token names describe role rather than value, and a rename ships as a deprecation with a migration note instead of a breaking surprise.

For systems already in production, the work takes audit form: an inventory of what exists, a measure of drift between design and code, a map of duplication, and a sequenced repair plan a team can absorb alongside feature work. The output is not a verdict; it is a backlog with an argument attached.

What this covers

  • Token architecture: primitive, semantic, component
  • Multi-brand and multi-surface theming
  • Component specification: states, content, edge cases
  • Accessibility criteria written per component
  • Dual documentation of intent and deviation
  • Governance, versioning, and contribution models
  • Adoption strategy and terminology alignment
  • Design system audits and repair plans

The work behind it

Questions, briefly

Build on an existing component library or from scratch?
On top, almost always. Rebuilding what mature frameworks already solve is rarely defensible; the value sits in the token layer, the domain-specific components, and the documentation that records every deviation. From scratch is reserved for products whose interaction model genuinely has no framework analogue.
When is a design system worth the investment?
When more than one team ships the same patterns, when a second brand or theme is plausible, or when reviews keep relitigating solved problems. Below that threshold, a well-kept component folder and a strict token sheet deliver most of the benefit at a fraction of the ceremony.
What does a design system audit actually produce?
Four things: an inventory of components and their real usage, a drift report between design and code, a duplication map, and a sequenced repair plan. The goal is a system teams can trust again, not a document that assigns blame.

Elsewhere on this site

If this is the territory your product lives in, the case studies carry the detail and the contact page carries the practical part: roles, embedded engagements, and where to start.

Contact