Mistakes made when setting up contribution process for the design system

Introducing an inbound feature request and/or contribution process in the org? Betting it’ll help the core design system team make the design system and all its users more successful? I’d been there, I’d made a few mistakes, and I’d like to share them — no sugar, — so that you know what’s ahead and what non-obvious miscalculations you are prone to make along the way. Here we go:

Didn’t explain what a feature request really means

Mistake: I assumed that we’ll converge on mutual understanding of what a well-formed, useful inbound feature is.

Design system and inbound requests
If a design system is a product, inbound requests from the developers is direct customer feedback.


If the org was stable, I think we would have achieved a state of mutual understanding of what it takes for a feature request to be understood by the design system team and eventually fulfilled by anyone, in or outside the core team. We would have run through a few cycles with each and every contributor, and use each of them as a practical exercise at requesting something for a design system from the point of view of someone who’s much closer to the product and therefore needs time and conscious effort to switch into a different mode of thinking.

In reality, there was a handful of regular contributors, with whom this approach worked exceptionally well! And then there were al the other contributors from the product teams who were so deep in the product work, they’d assume that a thing they need is the right thing and the only possible solution to a problem. Also, they’d skip the problem statement entirely and start from describing their solution. That was exactly what we expected, but we did not expect that there was gonna be a lot of first-time contributors, and that walking each of them through the whole thought process from “this is gonna work for your part of the product” down to “this is gonna fit the entire system” was going to take so much time.

There was also a side-effect of first-time contributors bouncing and going back to their microfrontend or their small local library of components in Figma and just making changes there. It wasn’t really a fork of the design system, — people would build on top of their product UI code, not on top of the UI library code. That’s a bummer, and to this day, there’s some UI implemented this way, which blocks massive redesign, for better or worse.

Didn’t explain what a contribution really takes, end to end

The continuation of the inbound feature request story is actual contribution story. The story usually went this way: someone would send a feature request (for example, “add ‘async action in flight’ variant to form and button components”), the core team would host a discussion and lead it to a decision, then the core team would align this decision with the rest of the org, and after that give a green light to the author of the feature request. The author would go ahead and start making changes. But! if the author were a designer, they’d make changes in Figma only; if an engineer, in code only.

This sounds really stupid and obvious: isn’t the design system supposed to stay in sync between Figma and code? Sure it is. But there’s no way we could expect an engineer to also update stuff in Figma. So we had to involve a designer from that same team, or we’d go ahead and make changes ourselves, or — more often — we’d schedule that work (create a ticket) and do it eventually, maybe never. As a result, a lot of the time Figma lib and UI component lib were out of sync.

Robin Rendle noticed that design systems are hyperobjects, and that sounds about right to me for sure. Figma lib is a reflection of the design system into design tooling, where as a library of UI components implemented in react is a reflection of the design system into code. There might be many more reflections. If one is present and another missing, it means inconsistency, it means the integrity of our hyperobject is broken, — how are we gonna fix it?

This was partially the capacity problem: if we only had more engineers and more designers, we’d definitely keep things neat. Or not. History shows time and again that simply being a bigger org doesn’t mean things get done more systematically or with higher quality.

And this was partially the expectations problem: at the core team, we didn’t want to intimidate contributors too much, especially during first contribution, and allowed them to finish their part of the change in the design system. If we dropped more expectations on them, it was really a game of chance. Only very few people had enough breadth in skills to actually pick it up. Most of the time, the response was either direct “I can’t or don’t have time” or half-committal “I’ll discuss this with peers on my team”. Follow-up almost never happened.

Now, I don’t want to put responsibility on shoulders of people who wanted to get their thing done and move on. Failure to keep the quality up is always a problem in the communication streams, decision-making structure, and system of priorities. Each situation is unique. Sadly, I don’t have any advice at this point on how to get contributions done end-to-end, except to document things, educate people, and reinforce the right behavior. Speaking of which:

Didn’t praise contributors enough for the time they’ve put

Almost all of the contributions to the design system were coming from people outside of the core team and outside of any of the platform teams. The authors were people in the product teams, which are much closer to the end user and the customer who pays the money that fuel the business. For these people, making a contribution to the design system means taking a much, much longer route than they would have otherwise taken, and while the motives might be 100% altruistic and/or curiosity-driven, it takes a bit of positive reinforcement, for which praise is the most common and simplest tool.

We did give some praise, for sure. We integrated giving recognition to contributors — the primary driver of the design system growth — into almost all parts of our communication plan. But we didn’t go beyond that, we didn’t feel, as a team, strong enough urge to give praise.

Now, it’s all touchy-feely. Why feel something, isn’t saying it not enough? I have a theory and, you guessed it, feeling gratitude is a really important component of giving praise.

It was my fault. I was so occupied with getting smarter, studying things, learning about design systems, improving and fixing every big and little thing, that I didn’t provide the team with what was important: the feeling that we live or die by contributions.

People are not stupid, they understand the words, and I was saying that we should leverage the rest of the org to grow and expand the design system. But I think I failed to convey the meaning of these words.

That’s my theory, and I might be terribly wrong about that, but the end result was: we didn’t give enough praise and we should have been giving more.

Didn’t work with managers to carve out time for people to make contributions to the design system

This one is also very personal. As a people manager, I have direct access to other people managers, and we talk. If you’re starting a design system team as a people manager, you also talk to other managers for sure, and that’s good! That’s a tool — you don’t want to overuse it or apply prematurely, but you want to spot the right moment to use it.

While the core team was operating successfully and working the contribution process well, and there was never a shortage of feature requests, I noticed that going from feature request to contribution was a bit problematic sometimes. Potential contributors would say that it’s too much work we’re asking them to do. I agreed with that, but I kinda assumed that it’s still worth it. And that’s where this subtle mistake is. Let me explain.

For a contributor, it’s exciting, it’s interesting to make a contribution. But they report to a manager, and sooner or later their job performance evaluation is happening, and if they’re not aligned with their manager on how important their work was, it’s gonna create a mismatch between their self-perception and their manager’s perception of them. And that’s a problem.

As a manager, I could have done much more, oh so much more, to make sure that if someone committed to contributing to the design system, their manager would understand the complexity and impact of that work, and give time. Engineering managers aren’t immediately aware of how hard or multi-dimensional design systems work is. Most of EMs have backend or data engineering background, and very few come from UI design and front of frontend.

That’s my personal mistake and one of the hardest lessons learned.

Didn’t run retrospectives on contributions enough

Running a good retrospective meeting that goes past “this is how I felt” and last-minute observations is a skill. A good retrospective meeting is more like a replay meeting, where the sequence of events is reconstructed, all emotions are removed, and clear causes and effects are recognized.

I didn’t ensure that replay skills are present enough on the core team (by staffing or training). We’d have a contribution, it would turn around in a week or two, and the whole thing would just kind of be forgotten afterwards. No real learning, only cursory feedback like “it would be nice to make changes faster next time”.

Retrospective sessions also yield artifacts, like notes and such, which help with communicating further to people who are otherwise too busy to attend the meeting but need the information nonetheless. From another angle, it’s an awesome exercise in writing good internal documentation, and I wholeheartedly recommend you to take on the adventure, because the outcomes are worth it increasingly over time.

For example, for a few dozen contributions in 2020, we only ran a handful retrospectives. One of them helped get a tense situation real and turn the conversation from “you guys blocked my work” to “wow, now it’s clear I blocked this because I switched to other stuff mid-way”. Not saying that running a retrospective is needed to turn tables on contributors, but it definitely helps with surfacing facts and putting them in front of everyone involved.

Didn’t make contribution to the design system look cool

I already talked about not talking to managers and convincing them that design systems work is hard, and I talked about not giving enough praise to the contributors. But there’s more. I call it “make the design systems work look cool”.

For a lot of product engineers and designers, working on a design system sounds like an awesome addition to their list of achievements. But when they actually turn a change around, it looks so small and insignificant, that they struggle to put it alongside other, flashier achievements related to the product.

I honestly believe that design systems work deserves to be seen as cool, and that there’s a way to recognize it at the same level of appreciation as successful product changes, but not at the much higher cost of making really significant changes in the system.

Of course we tried to make contributions sound cool. But we’d do it in a weird way, literally saying that contribution to the DS is cool. This didn’t stick to people. Why would someone believe it’s cool if there’s no social proof of that? And that’s precisely what I, together with the team, should have been working on towards making the contributions top of mind for people who wanted to make big impact or just look cool.

Didn’t do onboarding and education outside the core team

Originally, I wrote this point as “didn’t invest in onboarding and education”, but “invest in” sounds too bland and vague. Look at me, I just invested in the world’s knowledge by typing this paragraph — did I invest in making you understand my point better? The hard truth is, we did not do the onboarding, we did not do education, — at least, not enough of both.

That was the clash of priorities within a small team, and I did not make it a thing on the todo list for our team. The timing was tough. And, looking back, I’m pretty sure I’d push the team towards exactly the same choices if we were in exactly the same situation, so it’s one of those things that I need to think a lot more about to really find out what a better solution would be.

“Think big, start small” was the best principle to follow in that situation. It helped the team focus on getting a few basic things done. It did not lead to getting big things done, unfortunately, because other things took the remaining time.

Looking back, I think that, because we were a young team, there was a couple easy wins to be had. For example, recording a few short videos walking through the design system in its current form. Yes, they would be outdated in a month, but hey, that’s already two waves of new hires covered! Sure, making them would require good presentation skills, but we didn’t have to make perfect content, — useful content would have been enough. In an attempt to match imaginary high standards, I blocked the team from making tangible progress, and that sucked not only for us, but for all the people who joined the company, didn’t get any focused onboarding about our design system, and had to go through first-time contribution mess on hard mode.

Anything else?

There’s a lot more. The mistakes mentioned in this post are related to the feature request and contribution process. If I recall correctly, there was a bunch of speed bumps with developer tooling, we talked about making it stricter.

It was also a mess when the whole UI lib was one big package, and it became much less messy when we switched to multi-package monorepo, with each UI component being an individual package, with its own versioning and release schedule.

But besides that, I think I’ve covered most significant mistakes in this post. If you found them insightful, useful, or even actionable, please feel free to ping me on Twitter and let me know what you did differently and what worked for you.

Have a great day!

Subscribe to zero added sugar

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.