So, you’ve built your Design System and have spent hours, days, weeks or months painstakingly documenting your styles, components, spacing and grids and their usage. Only to discover every time you see a product screen from another team, it looks a little — off.

Documentation, aka the third big piece of the puzzle. That little booklet that brings it all together to build the ultimate Millennium Falcon you’ve always dreamed of. It’s designed to help teams understand exactly how to build incredible experiences. So, why tf isn’t it doing its job?

Well, let me ask you a question (lego aside) — how many times have you tried to build or program something without looking at the instructions? I’ll admit I’ve spent an embarrassing amount of time trying to reprogram the time in my car when the manual was literally sitting in the glove box, probably to the point where I’ve developed a deep disdain for daylight savings for all the wrong reasons.

My car watching me trying to reset the time
My car watching me trying to reset the time

Humans are curious creatures. Not only that, we’re stubborn, time-poor, and think we know better.

So why are we surprised people don’t want to read a how-to guide for our system every time they create something new or make a change?

Trust me, I know just how disheartening this can be. But expecting designers to read through documentation every time they design is ambitious. Some will do it, but many won’t. That’s not to say your documentation is useless, but you shouldn’t rely on others to read it as much as you are.

The problem here isn’t documentation itself. When done properly, it can be an incredible supplementary resource. The real problem is that we’re relying on it for everything, including making our system as user-friendly as possible.

Yes, you heard that right — the system designed to simplify our process, save teams time and create glorious user experiences has a fundamental UX flaw.

I might hear you yelling at your screen, but we use semantic colours— and all I have to say is, that’s a great start, but why did you stop there? A design system is an opportunity to continuously improve and find ways to make your system foolproof, from naming colours AND the rest of your foundations to the structural setup of your component props, all the way to your patterns and templates.

I could go on, but let’s get productive. Here are some ways to improve your setup and meet teams where they work.

Templates and patterns

First and foremost, lead by example.

Creating patterns, templates and core product screens as part of your system will create a toolkit for designers to start from — with the right grids, spacing and styles built in. This will save people time and also teach them through doing.

Semantic token naming

What is semantic token naming or semantic aliasing? Well, they’re very fancy terms to describe something very simple.

Naming your style/token for its use case rather than what it looks like.

Why is this important? Well, what happens when you call your default surface colour #white? For one, it won’t scale across different colour modes; for two, it doesn’t tell you when that colour should be used in your interfaces. Using terms like #background-screen offers much more versatility, scalability and usability.

But you shouldn’t stop at colours. Typography and spacing are great examples of places where you can use semantic token naming. What is a H3 used for anyway? Explore these through your own system, find your most common styles, and name them accurately. They don’t all need to be specific. But maybe an H1 could be a #screen-title instead.

Regardless of your direction, don’t forget to test these names with your teams, keep your collection lean and continue to iterate and evolve.

Smarter naming and descriptions

What happens when we don’t make things easy to find? We get more support requests, wrong components being used, or custom components being built — yuck.

When creating components or asset libraries, include search terms and any alternative names that might exist for your component. In Figma, these go in your descriptions. It makes them easier to find and indicates what they’re used for.

An icon for a heart might be called ‘heart’, but maybe it’s a product feature with a different name. You can’t always assume others’ mental models of naming and categorisation. Luckily, there are simple ways to find these things out, as in the case of icons, where you can play a game of ‘Name that icon’ to create better search terms and naming.

Component fidelity and structure

Another common struggle when it comes to discoverability is component fidelity and structure. When you try and become too clever with your component build in Figma and rely purely on configurations, you’ll find that designers struggle to find what’s available and ask painful questions like, don’t we have a secondary state for this?

Leading once again to support requests, wrong components being used, or custom components being created — a lot more of this last one.

Striking the right balance between component variations and configurations and splitting components entirely where relevant (input types are a great example) will make it easier for designers to know what’s available and give you more control over how people use your system.

The next stage is to ensure you create a consistent experience across your components using the same naming conventions with props and knobs.

Don’t know where to start? Well, it’s your lucky day because I’ve written a handy guide on the Figma build process that should point you in the right direction.

System onboarding processes

Getting your newbies engaged properly from the start will save you a lot of headaches. You can do this with an onboarding video series or a newbie onboarding meeting.

If you do a video series, keep it fairly high level so you’re not re-recording every other month.

As a start, it should cover —

  • An intro on what a design system is — specific to your business
  • How is your system set up
  • Where can they find the libraries, and how to navigate them
  • Where does the documentation live, and how to navigate it
  • Where can they go to get additional support

While it isn’t the solution for your ongoing support needs, it will create a different dynamic between your systems team and its users.

Continued education

It’s not enough to build and update documentation. You need to tell people about changes as well.

Some great ways to do this include —

  • Slack announcements for updates (small to large)
  • Product demos
  • A changelog on your docs site
  • Walkthroughs in your office hours (recorded for others to watch)
  • Presentations to your different guilds and communities
  • Workshops

And yes, these can all link back to your beautiful documentation site. But at least now you have the comfort of knowing your system is just as user-friendly as the product it’s serving.