There is a moment when you realize the system you built is no longer serving you, you are serving it. For me that moment came somewhere around client number forty.
I remember opening Figma one morning in January and counting how many pages were in our main design file. Thirty-one. Some of them were named things like "Client 7 - Tables FINAL" and "Client 12 - Dashboard v3 (their version)". The file had become archaeology. I had to dig through layers of decisions made six months ago to understand why a button was that particular shade of blue.
We had just crossed 70 institutional clients. Investment banks, hedge funds, asset managers across fifteen countries. VALK was growing fast, $4 billion in transaction volume flowing through interfaces I designed. And the design system that worked perfectly for seven clients was quietly falling apart under the weight of seventy.
This is what that experience taught me.
The white-label problem is actually a philosophy problem
VALK is a white-label platform. This sounds simple until you live inside it. Every financial institution that comes onboard wants the product to feel like their product. Not a vendor tool. Not "powered by VALK." Their platform, their brand, their color palette on the buttons.
When we had seven clients, I handled this manually. Client comes in, I adjust the colors, tweak the typography, export new assets, coordinate with the dev team. Two days of work, done. Fine.
At fifteen clients this approach started to feel uncomfortable. At thirty it was breaking. At seventy it was completely unsustainable; and we were already inside the problem by the time I fully understood it.
The mistake I made early was thinking of white-label as a visual problem. Change colors, change logo, done. But institutional clients do not just want different colors. They want the product to match their visual identity at a level where their compliance officers, their traders, their investors, none of them feel like they are using a third-party tool. That is a much deeper requirement. It touches typography scale, border radius on cards, density of data tables, even the language used in empty states.
White-label customization is not a skin. It is a dimension of the entire product.
Design tokens were not optional
I had worked with design tokens before VALK, but in a casual way. Mostly color variables with names like primary-blue and background-dark. Useful, but not load-bearing.
At VALK I had to rebuild how I thought about tokens completely.
The system I created had three levels. Global tokens were the raw values, #1A2B4C, 16px, font-weight-600. Semantic tokens mapped those to meaning: color-brand-primary, spacing-component-padding, text-heading-size. Component tokens then referenced the semantic layer, table-header-background, button-primary-text.
This structure meant that when a new client needed their brand color applied throughout the platform, I changed one global token and the semantic layer propagated it everywhere. In theory. In practice, this required the dev team to implement tokens in code the same way I defined them in Figma, which meant extensive documentation and several conversations I was not expecting to have about why this mattered.
Anton and Alex on the frontend side were genuinely good to work with. But developers have different mental models for this. Getting them to honor the token hierarchy, not to just hardcode hex values when they were in a hurry, that was an ongoing effort that lasted well into the year.
What happens to components at scale
When I designed the first version of our data table component, I think I had four variants. Compact, default, with actions column, without actions column. That covered everything we needed.
By February 2021 I was looking at a table component with something close to fifteen different configurations. I am being precise: I counted.
Row density. Header styles, sticky or not. Action columns ranging from none to full dropdown. Pagination modes. Selection states. Expandable rows. Status columns.
Each axis multiplies with the others. Not all combinations exist in the product, but enough of them do that the component had to be built to handle the matrix, not just the cases I had currently imagined.
This is what "component variants explosion" actually feels like. It is not a one-time decision. It is slow accumulation, each request sounds completely reasonable in isolation. "Can we add a row selection mode for this client's workflow?" Of course. Reasonable. But it added another dimension to the component, and that dimension then had to exist and be documented and tested in every other context where the table appeared.
I started maintaining a decision log for major components. Not formal documentation, just a private Figma page where I wrote short notes about why certain variants existed and what client use case drove them. This saved me probably hours of confused re-investigation later.
The "one small customization" pattern
Every enterprise client has one. Mentioned almost apologetically on the second call after they sign. "We know you have a standard platform, and we love it, but we just need one small thing..."
Sometimes it actually is small. A logo placement change, a different default currency display. Fine.
But there is a pattern in enterprise software where "one small customization" is a signal for something larger. The client has an internal stakeholder, a head of UX, a CTO, sometimes just a very opinionated senior trader, who has already decided the product does not quite fit, and they are testing how flexible you are before making their real requests.
I started tracking these differently after month three of rapid growth. Instead of evaluating each request on its own, I started asking: does this need to be solved in the component system, or is this a client-specific override? If it was a systemic gap, I would fix the component and all clients benefited. If it was a preference unique to that institution, I had to be honest that we could not build the entire product around it.
This required saying no sometimes. That was new for me. At a small agency you often say yes to everything because each client is a large percentage of revenue. At VALK with seventy clients, saying yes to every preference request would have destroyed the coherence of the product within months.
How the Figma file structure had to change
The "one big file" approach did not survive scale. I know this sounds obvious in hindsight. It was not obvious when I was inside it.
What replaced it was a library architecture. One master component library, all the base components, variants, tokens defined. This file no real person opened to work in. It was the source of truth. Connected to it were brand-specific theme files, essentially overrides of the token layer for each major client group. Then separate working files for active product design work.
The team that needed to understand this was small, mostly just me and whoever was reviewing my work. But the file structure had to be clear enough that if I was sick for a week, someone could navigate it without me.
Figma's component library system in 2021 was already capable enough for this. The harder part was discipline. Keeping the master library clean, not letting quick fixes sneak in as local components in working files, making sure that when I updated a component it actually propagated correctly through the themed variants.
I failed at this discipline many times. There are still, I am certain, components somewhere in our older files that diverged from the master library and nobody knows when or why. That is the real cost of moving fast.
Documentation became half the job
I want to be honest about this because I did not expect it and it bothered me for a while.
When I joined VALK I thought of myself as someone who designs things. Interfaces, flows, components, systems. Documentation felt like the afterthought, the thing you write after the real work is done.
By early 2021 I was spending something like forty percent of my time writing. Annotating. Creating specification pages in Figma that explained not just what something looked like, but why it looked that way, what the edge cases were, how it should behave on mobile versus desktop, what happened in empty and error and loading states.
With seventy institutional clients and a dev team moving as fast as ours, underdocumented components created bugs. Subtle ones. A table that rendered correctly in the default state but broke in the expanded row state because the developer had seen the design for the default state and assumed. A form that handled the happy path perfectly but had no visual design for the error state so the developer made something up.
Every one of these bugs was ultimately my fault. Not because I designed it wrong, but because I did not communicate the design completely.
I stopped resenting documentation time once I reframed it this way. An undocumented component is an incomplete component. The spec page is not the chore you do after the work, it is the last part of the work.
I wish someone had told me this three years earlier.
The pressure of real money
There is a difference between designing for a startup where a few hundred users will see your work and designing for a platform where $4 billion in transactions passes through each year. The stakes are different in a way that is hard to explain but very easy to feel.
This did not create constant anxiety. But it created a different level of attention to certain decisions. What does a user see when a transaction fails to process? What does a first-time investor see when their portfolio has no assets yet? Is this number formatted to two decimal places consistently everywhere, because these are financial figures, and inconsistency in a financial context reads as an error.
Investment banks are extremely sensitive to interface quality. They are used to Bloomberg terminals, to expensive internal tools, to interfaces that convey professionalism through density and precision. A misaligned column, an inconsistent border, a tooltip that appears in the wrong position, in a consumer app these might go unnoticed for weeks. In a platform used by institutional traders they are noticed immediately and they erode trust.
This pushed me toward much more rigorous visual QA. I started treating the staging environment like a design artifact, reviewing it the same way I reviewed Figma files. Finding small inconsistencies. Logging them. Following up.
Not everything got fixed, there was always something more urgent. But the habit of looking carefully at the built product, not just the design file, was worth forming.
What I underestimated completely
Time. Specifically, how long documentation takes.
I knew it would take time. I planned for it. I underestimated by a factor of probably two and a half.
Writing clear specifications for a complex component, something like a multi-state data table with six interaction modes, takes far longer than designing the component itself. You design in visual thinking. You document in linear language, and translation between those modes is slow.
Documentation also becomes outdated faster than you expect. You document version one of a component. Three months later the component changes significantly. Now you have documentation that is wrong, which is in some ways worse than no documentation because it actively misleads.
Keeping it current meant building documentation into my process for every component change, not just new component creation. That habit took time to form.
If I were starting over, I would allocate documentation time separately from design time from the very beginning. Design the component. Stop. Document the component. Ship. In that order, every time.
Where this leaves me
We are two years into VALK and the design system is in genuinely better shape than it was six months ago. It is not finished, design systems are never finished, I think that is definitional, but it is navigable. A new engineer joining the team can find the component they need, understand its variants, read the documentation, and build something that looks correct.
That was not true in the middle of last year.
The difference is not beautiful Figma files. It is mostly disciplined, unglamorous work: documenting, organizing, having conversations with developers about why the token hierarchy matters, saying no to customization requests that would fragment the system.
Scale reveals every assumption you made when things were small. The comfortable shortcuts become visible as technical debt. The things you meant to organize become urgent to organize. The documentation you were going to write eventually becomes documentation you have to write now.
I do not regret the chaos of the growth period. Growing from seven clients to seventy in a year is not something you can plan perfectly for. But I understand now that the design system is infrastructure, not something you build once and maintain. Something you build continuously, and the investment compounds over time.
Originally published on kargaev.me. Imported to blog.deeflect.com archive.
Top comments (0)