Prototypr

Prototyping, UX Design, Front-end Development and Beyond 👾 | ✍️ Write for us…

Follow publication

Getting design system guidelines into Sketch

A (cautiously optimistic) attempt at supplying design documentation that people will actually use. Co-written with Jürgen Zimmermann

So we’re a small crew of meta-designer drones, busily documenting our components and patterns, and supplying our designers with Sketch libraries for iOS, Android and Web.

A noble cause indeed, but we quickly ran into a problem: new designers tend to review our online documentation just once, after which they refer only to the Sketch libraries.

This is a Very Bad Thing because our design system is still evolving (as it should). Meanwhile, design components tend to be misused because designers rarely get around to reading up about how and where a component should be used in the first place.

Documentation is for dorks

Vexing stuff indeed, but there’s no sense in getting snippy about this sort of behaviour. People naturally look for shortcuts. We avoid complexities. We’re busy, lazy, confused or, in rare cases, merely stupid. Designers are just humans trying to get through the day.

It also dawned on us that we’re really being naive dorks for expecting everybody to willingly refer to our documentation. In fact, the same thing happened to our content strategist too, with his merry lists of copy components and guidelines: “Oh, you have a list of standard CTA copy? Labels? Error templates? Gosh, I didn’t know! I guess I missed the workshop. It’s a shame, really. Ah well…

A lovely, detailed list of standard copy components. A pity that so few people know. Or care.

Plugin and float on

Feeling depressed and a little annoyed, we asked ourselves the question: how can we make it easier for our designers to access and use our design system documentation?

First off, here’s how it used to ‘work’: A designer working in Sketch decides they need more guidance around using a particular component. To do so they’d need to leave Sketch, open a browser, visit the design system site and finally rummage around for the component documentation they’re searching for. They might find it, they might not.

It’s no surprise that few people bothered — and we can’t blame our designers, most of whom work in high-pressure environments. Very often there simply isn’t time to worry about dusty documentation: “I have the component. I’m going to use it this way, or perhaps that way — and to hell with the guidelines.

Fair enough.

Our first attempt at a solution was to add our documentation to the Sketch library files and attach guidelines to the components themselves. That didn’t work. We ended up with too much clutter in our Sketch libraries. It looked terrible and made a mess of everything. This approach also didn’t solve the fundamental problem of ensuring that our guidelines were up to date.

Screenshot of the sketch app showing a floating window
Our design system as a floating window in Sketch

Breaking through the Sketch barrier

Then we started fiddling with plugins for Sketch, our primary design tool. First of all, we created a plugin that displays our design system website as a floating window in Sketch. On the surface it’s not a big deal, but it means that designers needn’t open a browser to check component documentation. We’re killing unnecessary clicks. Hooray!

Next up we realised that Sketch records the name of the component the user selects — and that if we’re smart we could use this recorded data to make a database query. Since component naming in Sketch was aligned with our design system naming, all we had to do was record the name and send the query directly to our (floating window) design system.

An example of a design system component and associated documentation and guidelines

This solution seems to work. Our designers can now retrieve and display component documentation simply by selecting the component in Sketch. In other words, we have:

  • A direct link between the design system and our primary design tool
  • An easy way to find and review design documentation
  • Instant access to standard copy components and guidelines

It’s still early days, but we’re getting positive responses from our design teams. In time we’ll follow up with more revelations. Good ones, hopefully.

Do you have similar problems integrating your design system into the humdrum realities of work? How did you solve it? We’d really like to hear your stories.

Sign up to discover human stories that deepen your understanding of the world.

Free

Distraction-free reading. No ads.

Organize your knowledge with lists and highlights.

Tell your story. Find your audience.

Membership

Read member-only stories

Support writers you read most

Earn money for your writing

Listen to audio narrations

Read offline with the Medium app

Published in Prototypr

Prototyping, UX Design, Front-end Development and Beyond 👾 | ✍️ Write for us https://bit.ly/apply-prototypr

Written by Chanetsa

Design System Lead at Absa | Tech fiend, Design Junkie, Dad

Responses (4)

Write a response