My Five Biggest Design System Mistakes

Lessons learned from bootstrapping a small design system from scratch

Steve Dennis


Image by Midjourney, directed and edited by the author.

A lot of design system articles focus on the ideal or best ways to approach certain problems. There’s a lot less written on what doesn’t work, and what was learned from it.

Our design system team has always been small and scrappy, trying to do what we can with limited resources, often while juggling other responsibilities. I’m incredibly proud of what the team has been able to build, punching way above our weight in some areas. But mistakes were made (often by me), despite good intentions.

Here are my five biggest mistakes, and what I’d do differently next time.

1. Not adopting component tokens

When we built Castor in 2019, one of the major pain points was supporting dark mode and theming. We did this using design tokens. Design tokens have been around as a concept since 2014, but they really started gaining traction in smaller design systems over the last few years. Engineering tools to support them are in a pretty good state, but design tools are still catching up.


I advocated for splitting our token architecture into two layers, base tokens, and semantic tokens. The semantic tokens were things like background-main, content-secondary, or border-input and are the colors we encourage designers to design UI with in Figma. We ensure all our components are built using only these tokens so that they support our dark/light mode themes out of the box.

A visual example of what happens to our semantic token values when dark or light themes are applied.

I was concerned about having too many available options and duplications in the palettes available to designers, so I chose a naming approach that aimed for a balance between being broad enough for one color to cover multiple uses, but also being specific enough to know what colors to use in different scenarios.

Examples of our content and background design tokens. content-main, background-main, content-secondary, background-surface, etc…



Steve Dennis

Senior Design Manager @ Onfido, writing about design systems, product design, leadership, and tech @