Tokens Pipeline
The first design token infrastructure at PayPal.com — a Token Studio pipeline syncing Figma Variables to a GitHub source of truth, giving design direct ownership over brand language updates for the first time.
| Prop | Value |
|---|---|
| role | Design Lead |
| year | 2024 |
| team | 1 designer · 1 engineer |
| status | stable |
| version | 1.0.0 |
The PayPal.com component library had existed since 2021. Brand lived in CSS custom variables — color only, engineering-managed. No design serviceability. Every system-wide update was a ticket, and it moved at engineering pace — a dedicated design team of roughly ten waiting on a team stretched thin.
In 2024 we introduced design tokens: a Token Studio pipeline syncing to a GitHub repo as source of truth, imported into Figma Variables as modes, covering typography and spacing beyond color. We picked Token Studio because Figma's native variable support was limited at the time — it's much better today. We handed off via a GitHub PR in the token repo and a live session to walk through the architecture together.
- iDesign serviceability over engineering dependency. Token changes should be owned and published by design without an engineering ticket. Design makes a brand update, pushes to the repo, and it's live.TradeoffToken Studio added tooling overhead that required onboarding designers who had never worked with a file-based token system. The ramp was real but short.
- iiGitHub as the contract. The repo is the source of truth, not Figma. Figma Variables import from the repo — not the other way around. This meant engineering could review token changes the same way they review code: via PR, with history, comments, and approval gates.TradeoffEngineers had to adopt a new PR review surface for design-originated changes. In practice it landed well because the PR format was already familiar.
- iiiFollow existing conventions, ship fast. The initial token schema mirrored existing CSS variable naming conventions to minimize adoption friction. Surface teams could adopt new tokens without renaming anything in their codebases.TradeoffSchema mirroring constrained future growth. The naming conventions in the codebase weren't built for multiple brands — that ceiling is what drove the v2 work in Multi-Brand System.
Even an imperfect schema makes a real difference for a small team — it cuts the ticket queue and frees time from manual updates. The mistake was mirroring the existing CSS variable conventions for the sake of a faster ship. It worked, but it set a ceiling that took a full v2 to break through. If I were starting today, I'd enforce naming contracts at the token publish step — not just in Figma — so the two surfaces can't drift.