Design System
Documentation as
Infrastructure
Overview
Before this system existed, design knowledge at RYVYL lived everywhere and nowhere. Across multiple products and a growing cross-functional team, every handoff was a negotiation. Designers pulled from detached components. Developers re-derived spacing values from screenshots. PMs referenced screens from two sprints ago as if they were current. The questions never stopped. They moved to the next Figma file.
Over three years, I took over a partially-built library and rebuilt it with a token architecture, documentation, and an adoption strategy it lacked: a single source of truth for color, typography, spacing, components, and usage guidelines across 5 products and a team of 4 designers and 50+ engineers.
Problem & Goals
Whoever opened the file made every decision from scratch.
A developer couldn't find the correct hex value, so they'd drop a comment and wait (sometimes for a full day, across a 12-hour time zone difference). A PM would reference a screen from two sprints ago, not realizing it had been updated. A designer joining a new product would detach components because they didn't know how the library was structured. Each moment was small. Across a sprint and five products, they added up to weeks of lost time.
Nobody was at fault. Nobody had established rules for how the system should work, so everyone improvised their own version.
Developers had no shared reference for design specs and defaulted to asking me. I was fielding questions about previous projects while trying to ship new ones. I proposed the design system to move those answers into documentation.
Design challenge: The challenge was making the decisions behind the components legible enough that teams could act without asking.
Process
I built the system in layers: foundations, tokens, components, adoption. Each layer targeted a specific category of ambiguity.
text/brand-heavy.
Outcomes & Results
Figma comment threads stopped piling up. Handoffs that had required back-and-forth clarification became self-serve. Dev timelines shortened by ~25% as engineers pulled specs from token documentation instead of re-deriving values. Design-related comment threads dropped by ~70%.
Beyond the metrics, the bigger shift was organizational: design knowledge stopped living with specific people and started living in the documentation, available to anyone without asking. Engineers resolved spec questions from the docs without pinging design. Designs came back from engineering with fewer implementation errors.
Learnings: Changing how people worked was harder than building the system. Teams with workarounds need a concrete reason to switch. I'd establish the system from the first product.
I'd pair the Figma library with Storybook. Coded components previewed in isolation give engineers a buildable reference alongside the design specs, reducing the gap between what's designed and what ships. I built a proof of concept to show what that would look like in practice.
View Storybook