My Five Biggest Design System Mistakes

Lessons learned from bootstrapping a small design system from scratch

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.

Mistake

I advocated for splitting our token architecture into two layers, base tokens, and semantic tokens. The semantic…