Component Design Guidelines

Write the Words and Add the Pictures to Empower Designers

Nathan Curtis
Jun 15, 2018 · 9 min read
Image for post
Image for post


Start with the Words

Design guidelines begin as a writing exercise, even if eventually they aren’t just words (more on that later). Well written words matter. With a predictable structure organizing advice, any reader — especially designers — can make better choices when using a component.

Organize Guidelines Per Section by Discipline

Some guidelines are better than none. However, a massive list of unorganized bullet points discourages readers. Consistent headings, organized by type of design concern, establishes a familiar pattern for readers and encourages authors to consider implications across concerns.

  • Visual Style to inform judgment about color, type, space, and more (alternative headings: Visual Language, Design Language, Foundations).
  • Behavior to cover how to cope with events, outcomes, and transitions (alternative headings: Interaction).
  • Editorial advice covering copy and images flowing into each element (alternative headings: Voice & Tone, Content).
  • Accessibility checklist(s) that inform design decisions like color contrast.
Image for post
Image for post
Different components can result in different available guidelines. Hide headers of empty sections.

Use When

While a component introduction may hint at relevant use, rely on a Use When section to illustrate the many cases when to use or not use a component.

Visual Style

Visual style guidelines help designers tailor style given their conditions. Topics include color, typography, iconography, borders, space, size, and other visual properties. Just as common, this section elaborates on how to arrange multiple instances (example: aligning primary and multiple secondary buttons) and relate the component to adjacent elements.

Behavior

Whether or not your built component offers heavy logic built in, a Behavior section offers you the opportunity to elaborate on all the interactive details useful for a designer crafting an experience. Examples include:

Editorial

Whether atomic (like a Button or Input) or composable (like a Card or Menu), components almost always have words or images. The Editorial section can offer advice on labels, tone, length, punctuation, and writing samples. Examples include:


Top Tips for Writing Effective Design Guidelines

Voice and tone guidelines vary by design system. As a team begins authoring, I’ll propose the following conventions as a starting point:

  1. Omit needless words. If you can say something with fewer words, do so.
  2. Assert non-negotiables with Always… or Never….
  3. Encourage a reader’s judgment with Consider… or Avoid….
  4. Succinctly redirect to an appropriate alternative with a subsequent sentence beginning with “Instead, use Tooltip.”
  5. Favor positives over negatives, such as “Always include a logo in global navigation” over “Never omit a logo from global navigation.”
  6. Favor lists over paragraphs. Readers want to learn quickly or find an item. So don’t bury advice in dense prose unless absolutely necessary.
  7. Limit guidelines length to two sentences or less.
  8. Favor specific advice that’s objective, concise and often quantitative over subjective, qualitative, and laborious explanations.

Image for post
Image for post

Enhance with the Pictures

A picture is worth 1,000 words. Or, at least it’s often over the many, many words it replaces, especially for the most important advice you impart.


Do Use Do’s and Don’ts, Especially Comparatively

As I edit, vital or wordy guideline bullets often trigger a comment of:

Image for post
Image for post
Image for post
Image for post
Image for post
Image for post
Image for post
Image for post
Image for post
Image for post

Enrich Storytelling with Compelling if Expensive Custom Demos

As an investment in design guidelines deepens, so to does a team’s willingness to invest in more custom exhibits, including:

  • Videos, animated GIFs, and other custom demos that capture an arc of interaction, animation, or quick looping sample. (Example: Google Material Motion)
  • Additional live code examples, enriching understanding beyond the list of variations.

Avoid Redundancy with Coded Examples

If readers have already encountered a list of rendered examples with code equivalents (as suggested in Component Examples), strongly avoid repeating the examples in design guidelines to tell the same story. Such examples — effectively labeled and ideally coupled with succinct “Use When”-style statements — have already exhibited the range of relevant cases.


EightShapes

A collection of stories, studies, and deep thinking from…

Nathan Curtis

Written by

Founded UX firm @eightshapes, contributing to the design systems field through consulting and workshops. VT & @uchicago grad.

EightShapes

A collection of stories, studies, and deep thinking from EightShapes

Nathan Curtis

Written by

Founded UX firm @eightshapes, contributing to the design systems field through consulting and workshops. VT & @uchicago grad.

EightShapes

A collection of stories, studies, and deep thinking from EightShapes

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store