Creating a design system for PayPal’s customer-facing applications

At PayPal, almost every view belonged to a different team with its own repository. On the web that meant hundreds of apps, each with its own components and, for years, a mix of technologies. Even after the web converged on React, teams kept building libraries to match their designs. iOS and Android shared a few components, but most product teams built their own there too.

My team, the Marketing Publishing Platform team, owned PayPal.com. We had already built its first design system: reusable components for building marketing pages. With a brand refresh coming, leadership saw that our team had the technical depth, design partnerships, and product mindset to take that work company-wide, and invested in a small team to do it. That team was PayPal UI, and I was its engineering lead.

It covered every customer-facing PayPal application (consumer, merchant, checkout, and more) on Web, iOS, and Android. Internal tools were out of scope.

The inconsistency was everywhere: navigation, links, typography, spacing, and color all changed from one app to the next. Buttons were the clearest example. Padding, corner shapes, shades of blue, and hover effects all varied, and the running joke was that PayPal had hundreds of buttons.

Because nothing was shared, changing a single color meant changing it in every app, one by one: a line item on every team’s roadmap, and a coordination problem across the company. A brand refresh would multiply that across everything customers see.

Any fix had to work on three platforms with different languages and conventions, and for teams that already had their own components and no obligation to give them up.

1. Started with design tokens: every value that made up a component became a token in JSON. The tokens covered the foundations every design system needs (color, typography, spacing, sizing, and corner radius) and went further, down to individual components and their states: a button’s padding and margins, and even its background color when pressed, with tokens like btn-active-background-color. That way, a component’s look could change without touching its code.
2. Built the pipeline that turned the tokens into code for each platform (Sass, Less, and JavaScript for the web, XML for Android, and Swift for iOS) and the delivery that shipped it: NPM for the web, Gradle for Android, and CocoaPods for iOS.
3. On top of the tokens, each platform got its own native component library, and my team owned all of them. The web had two: a ready-to-use React library, and a CSS-only library with markup examples for teams on other frameworks that wanted to build their own.
4. Worked closely with five to six designers, who kept the source of truth in Sketch. We prototyped tools to convert Sketch into JSON, but day-to-day collaboration centered on the PayPal UI design site, where design and engineering shared examples and documentation for every component.
5. Treated the API surface as a contract. Tests covered it, so updates never broke a consumer.
6. PayPal was acquiring companies at the time and wanted to know whether PayPal UI could style their products too, so we built in theming. It wasn’t needed in the end, but the system was ready for it.
7. Won adoption with productivity first: teams no longer had to rebuild foundational components and typography. Leadership then put it on every team’s roadmap, on the web first and then on mobile.
8. Pitched the project to C-suite leaders several times, which is how the team grew from a product manager and me to a full team across three platforms.

• Roughly 90% of consumer apps adopted PayPal UI components.
• The system went on to be instrumental in later reboots and redesigns, significantly reducing their cost.

The biggest lesson: measure from day one. The team was driven by craft more than metrics and measured little. Measuring adoption and impact from the start would have made the system’s success easier to show and its direction easier to steer.

Years later, PayPal UI is still the work many former colleagues associate with me.