Building a Design System across four platforms

The same questions kept appearing across products and platforms: how a component should behave, which token to use, what changed between web and native, and what engineering should treat as the source of truth.

Each team had an answer, but there was no shared one.

It simply made the work harder than it needed to be.

I took the idea of solving these decisions once to my manager, then started by mapping what already existed.

A new project usually meant another conversation about spacing, colours, states, platform behaviour and implementation.

Nobody was doing anything wrong. The decisions simply lived in too many places.

I compared the existing product libraries and mapped where the same concepts had different names, values or behaviours.

I looked at existing design systems before building our own.

They were useful references, but none gave us the structure we needed across web, iOS, Android and the website while still respecting platform behaviour.

Reusing one wholesale would have moved the inconsistency rather than removed it.

Before scaling the system, I tested the workflow with one button.

The test covered the full chain: variables, semantic tokens, platform component, documentation and implementation.

If that chain didn’t work for one component, there was no point building fifty.

But it worked.

From there, expanding the library became a much safer investment.

A component wasn’t useful because it looked complete in the library.

Engineering needed to know how it behaved, what changed by platform, which states were valid and what not to invent during implementation.

That changed how I designed the components. I started treating the implementation rules as part of the component itself.

I documented accessibility alongside component behaviour instead of keeping it as a separate checklist.

That included touch-target values, contrast in light and dark themes, colour-blindness checks and usage guidance.

APCA was useful for comparison and learning, while WCAG remained the standard I designed against.

Documentation started as something I expected to add after the components.

In practice, writing it exposed gaps in the components themselves: unclear variants, missing platform differences, undocumented accessibility rules.

Each component needed enough context for someone to use it without me in the room.