Internal onboarding for design system teams

A new person joins a design system team you’re running. What information would you need to make it a pleasant few weeks?

Over a few months, I have compiled a list of things that, as a manager of an early-stage design system team in a mid-to-late stage startup, I wish I kept track of. Not talking about tactics here; instead, it is a collection of the ideas and the underlying problems to be solved, — some more useful for earlier-stage hires (first 1–2 people), some more useful for almost established teams.

“Why are we here?” — team’s mission

When it comes to internal platforms and tools, the “Why are we here?” is a composition of questions:

  • what is the economic reason the team exists?
  • who is the audience, whom are we serving?
  • and how do we know we’re achieving our goals of serving our audience the best way, even if they themselves can’t tell it yet?

For a design system team, there’s a range of obvious reasons to exist: to shorten the software development cycle, to unify the look and feel of the product, to let the teams do the least amount of duplicate work, to concentrate the expertise in one spot in the org and thus cut costs, the list goes on and on. A team that tries to say they exist for all these things is a team that is destined to stretch too thin, especially when the tough times (or quarterly planning) come. A team that has a clear mission statement that emphasizes what’s important and says “no” to things that are not is a team that can focus on achieving results. Someone who is joining a design system team needs to be exposed to the team’s mission as soon as possible.

I’ve been through a couple cycles of conversation about who the team’s audience is. We went from outward-focused (company’s customer who pays to use our product) to inward-focused (designers and engineers in product teams), to outward-focused by in a different way (third-party developers and designers), to inward-focused again (but also included product managers). At this point, I’m pretty sure a clear, perhaps a little uncomfortably opinionated, definition of the target audience is what the team needs to be able to make decisions about the design system autonomously.

And finally, a team that just works and can’t tell whether they’re achieving what they are supposed to is going to start breaking down eventually. Why? Because even if the feedback loop is tight, and there’s enough of critique coming it, only with a lens through which the team can see it, it can become objective and actionable. For a design system to succeed, it needs a clear definition of success, but “clear definition of success” sounds cheesy and, without actual hard choices what to focus on in place, means something different to each person in the room and nothing altogether.

So, long story short, that’s the first thing you need to include in your internal onboarding.

“What it’s gonna be like when it’s done” — target state of the design system

Maybe it’s engineering side of the brain, but I find it easier to operate — to do any work, actually, — when I know what piece of the bigger picture it is that the team is working on. Some design system teams are just fine with having 4- to 6-month horizon though, and it’s probably more realistic, considering that the target audience is probably going to change over time, from just a few team to a few dozen differently specialized teams, from internal usage only to the design system being a tool for makers you never have and maybe even never will meet. Still, a good strategy considers the end goal, even if that end goal is not realistically reachable. And it defines a possible sequence of changes, alongside with a framework for decision-making when stuff gets hard. You want that for the team.

When a new person joins the team, they are in a very tricky situation: the product is evolving, with new features being added and old features being decommissioned, the software is changing, some new functionality is aded, some old functionality slowly slides below the quality or maintainability threshold, there’s a lot of discussion going on, and it’s really hard to reconstruct the story from the bits of information flying around. It’s pretty hard to figure out the plot of a movie if you start watching a movie in the middle, — it’s much harder to understand the platform-level work if you join the party at the point in time when the team is on their hundredth iteration.

Still, I find it more convenient and attention-friendly to focus on the future and talk in terms of the current state vs. the target state.

When someone joins your team to work on a design system, give them a good sense of direction by providing a target state, however distant and hard-to-reach.

Source of truth: Figma or code or something else?

One very practical thing that is also quite confusing is, if a design system combines multiple tools that represent the same data, which tool is the source of truth? For example, for design tokens, — is it Figma, is it code, is it some special tool that’s responsible for the tokens, or maybe some spreadsheet with a bunch of rows that happens to feed this data into other tools designers and engineers use? Be very specific about it.

Note on the side: you probably want to have as few primary sources of data as possible (what’s the plural of “single source of truth”?), and you want each particular kind of data to be represented by one source only. It’s okay to combine several data sources into one, for example, smashing design tokens and their values with naming guidelines to generate user-friendly set of tokens that follow proper naming convention (or fail the operation if something is wrong), but the two original sources better stay separate.

So, a new person on the design system team should as quickly as possible become very confident in answering the question: For this type of data, what is its source?

Levels of the building blocks, or layers of the system

If a new person on the team participates in decision-making, they should be able to reason about different layers of the design system in unison with the rest of the team.

There’s nothing wrong when someone brings their experience with layering the system into the team, but in the spirit of system-wide changes, you want this change to take place on the team in a way that, once it’s done, the entire team starts operating using the same vocabulary and shared understanding of the layers.

Design system decision-making process

Speaking of decision-making, it always looks to me that a typical design system team spends less time implementing something and much more time making choices about how to implement it. There’s so much that needs to be weighed in, to be considered, decision-making is a significantly more complex process that takes up most of the time.

When a new person joins your design system team, give them a reasonably defined framework for decision-making. Don’t throw them in the hot water without giving them tools for making sense of what’s been going on and what’s gonna happen when it comes to making choices and reasoning about the system, for example, in context of inbound requests. Even if they have experience in this particular area, it doesn’t perfectly translate from one company to another. You don’t want one person on the team contradicting the rest of their colleagues in the middle of a highly complex discussion just because they are uninformed about how things are done.

Adjacent topics and who’s working on them

And there’s one more thing: adjacent topics. For example,

design system team is working on overall voice and tone, but  a separate localization team is working specifically on the product, and a separate dev tools team is working on i18n tooling for software engineers,


design system team is working on a way to present different states of data, but a separate group of designers is prototyping various contextual state transitions (for example, when data is loading), and a separate UI runtime tooling team is working on a library to make fetching the data from APIs more uniform and less complex for developers,


design system team is working on a set of components to represent spatial data, but there’s an ad-hoc group in one of the product teams that’s also working on representing real-time location data in a way that would leverage their own UI and frontend infrastructure best.

When a new person joins your team, you want them to be aware about things that are happening behind the scenes that the design system team might need to act on in the future. Doesn’t mean all of that is gonna happen though, — after all, it’s a sign of a healthy experimentation culture when some groups shut their experiments down in the absence of desired outcomes. Still, you want to give every person on the team an opportunity to follow work of others that is, even if indirectly, related to the design system.

A few notes on the side

Onboarding starter pack: have important things documented

This is going to be true for all sorts of teams, not just related to design systems:

  • keep essential things documented
  • keep the amount of documents to the bare minimum
  • but retain all the records and cross-link them

Note: AIIM has a lot of material on documents and records, and difference between the two, but check out a quick comparison if you’re not ready to go deep.

Having things documented will help when people are overwhelmed, and it’s fair to say that onboarding is one of those episodes when the person undergoing it is probably not in their most comfortable mode of operation.

Intermediate level: keep the plan and reality in sync

Now, that’s hard for a design system, which is intrinsically something defined by a lot of different groups of people in the organization. But I came to believe that that’s the job, gotta take it as one of the team’s responsibilities and do it.

There’s nothing more confusing for someone who just joined the team than a plan that, when sliced at current time, is only partially true because it was based on different assumptions and never updated since. As a new kid on the team, I really want to get a high-level overview of how things are and what’s next, ideally both from one source of information, — a plan.

Practical step: get someone walk a new person through the plan

If I joined a team, and they have both a plan and something already in the works, it’s great to have a one-on-one walkthrough session where someone from the team is explaining the plan and compares it to the actual state of things. I like this exercise, because it it’s a source of immediate feedback on flaws in the plan and/or its current implementation. Which is good! — we can update the plan on the fly.

Onboarding is fun! It’s also an essential part of team’s evolution. The better the team can handle getting new members on board, the less of a productivity loss they undergo, and the more enjoyable to work is, sooner, and for everyone involved.

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.