Documenting Patterns is a Designer's Job

Feb 1, 2022 • 3 min read

“Writing documentation is a boring job. In addition, it’s upon the dev team because of coding. “

This reasonable statement is the classic designer’s parachute.  Above all because of the code.

I think it comes from a legacy of a past where software solely was designed, coded and documented by computer engineers.

Designers were late to the party.  So, we adapted to a pre-established system.

Today, however, we could lead the entire process, acting as a link between teams, departments and stakeholders  - or rather must do.

We are privileged. We just have to make good use of it.

For this reason, I believe that anyone who loves (and cares) designing software interfaces cannot refrain from the task of documenting the patterns library that he himself has designed or contributed to.

Dimensions, styles, variants, content. All these are design elements. 

We shape them in out preferred design tool.  We makes choices, foresees scenarios. So, we are the repository of meaningful information that must end up in the patterns library.

Our work never ends up with a mockup or a Design Kit.

But naming things is freaking hard

I read this sentence on a lot of websites, blogs, LinkedIn posts and more.  Well, it’s true. If we can’t describe what we create, we’ve have done half the work.

Patterns or Components?

A pattern library - which may also be referred to as a component library - is a central and digitalized collection of a brand’s reusable assets.

It’s totally different from a Design Kit.  It lives in the browser.  And you have to know little about code to work on it.

Today, the designer’s toolbox get expanded: Fractal, Style Dictionary, Storybook and more. 

You simply can’t avoid to know and use them.

The Pattern Card

In my workshop on Design System there is a moment of practical exercise in which I ask participants to try their hand at a pattern card.

It’s interesting - and fun - to see the people reaction (90% are designers) putted in front of this task. They are quite confused. They don’t know where to start or what kind of information they have to write, even though they know those UI elements.

What Include

Let’s see what kind of info we need to put in it:

  • Pattern Name - use a name you and your team can memorize and quickly refer to
  • Description - succint description of the pattern focusing on what it allows to do, not what it is
  • Usage - what do users need to know in order to properly implement this pattern? Discuss any UX, visual, frontend, accessibility, content, backend, etc considerations. Show do’s and dont’s. When should users consider an alternative pattern? Include links to internal and external resources.
  • Variants - specifiy any pattern variations: size, spacing, colors, etc.
  • Preview - live preview of the pattern
  • Code - the pattern template (HTML or whatever) and related assets (CSS, Sass, Javascript)
  • Meta Info - additional informations like pattern’s status (work in progress, draft or published), changelog, version number, dependencies or anything more that you need

Benefits

Getting your hands dirty with a Pattern Library will bring you three key benefits as designer:

  1. Increase your product knowledge, following all steps of the project from rough sketches to final implementation
  2. Improve communication with developers, speaking the same language,
  3. Be aware of technical constraints, making more aware design decisions

Exercise Yourself

Now, I’d like to do the same exercise with you. Think of a pattern/component you have been working on recently and describe it.

You can use the file I prepared for my workshop (made in Markdown, but choose the format you’re most comfortable with).

Download the pattern card template

When you are done, you could share your work with me if you want (write at me[at]francescoimprota.com)

I would love to discuss it together.