Design Systems at Scale: Lessons from Scalapay

The problem with shared components

When four teams depend on the same button, who decides what the button looks like? This was the question that kicked off our design system initiative at Scalapay.

We had 12 different button variants across the codebase. Some had loading states, some didn't. Some handled icons on the left, others on the right, one supported both. The checkout team had built their own tooltip. The merchant dashboard had a completely separate modal implementation.

Starting small

The temptation is to build everything at once. We resisted. We started with three components: Button, Input, and Modal. The rule was simple: if three or more teams use it, it goes in the system.

// The API we landed on after 3 iterations
<Button variant="primary" size="md" loading={isSubmitting}>
  Complete Payment
</Button>

What actually worked

Tokens over hardcoded values. Every color, spacing unit, and font size came from a single source of truth. When marketing wanted to "refresh the brand", we changed 12 variables and the entire product updated.

Composition over configuration. Instead of a mega-component with 40 props, we built small pieces that composed naturally.

What I'd do differently

I'd invest in documentation from day one. We built great components but nobody knew how to use them. The adoption curve was steeper than it needed to be.