Component QA in Design Systems

Establish a process to deliver on the quality you promise

Nathan Curtis
Jan 6, 2017 · 6 min read

Months after our first release, productivity was strong. We’d reached 20 components. Buttons and forms were behind us. We cranked through cards, tables, and nav bars. As another component went to review, comments unexpectedly overwhelmed the pull request:

“Why don’t we have this variation?”
“It breaks with a reasonably long label.”
“Did you check for accessibility? It’s missing an attribute for…”

As discussion quickened, everyone swarmed to ask more questions. Really good questions. The contributing developer was overwhelmed: a finish line thought close extended again into the distance.

Ugh. We had documented neither what we check for nor how we QA. At all. We just built things, “checked ‘em”, and moved on. System teams must hold themselves to a higher standard than that.

Systems Must Deliver on Promised Quality

Promote Using Quality

… aim to optimize for cross-device use, gracefully degrade in older browsers, and offer an experience that is immediately accessible.

This isn’t whimsical aspiration. It’s a promise, promoting that library parts ascribe to attributes of quality. In fact, one of my favorite system principles is Salesforce Lightning’s Beauty, with a keyword I really appreciate:

Demonstrate respect for people’s time and attention through thoughtful and elegant craftsmanship.

Get Funded with Quality

We guarantee the library includes only quality, accessible components.

Stakeholders–your director or VP–listen for those trigger words. To them, it signifies a library (at least partially) can unburden teams struggling with or ignoring things a leader cares about.

Prove You Deliver the Quality

What’s Quality? Our QA Checklist

✔ #1 Visual Quality

✔ #2 Sufficient States & Variations

A first pass may not comprehensively addressing states across all button types…

✔ #3 Responsiveness

Tab component, with options for responsive behavior

✔ #4 Content Resilience

Tab component, automatically shifting to alternate display based on content length

✔ #5 Composability

Tabs in different settings, positioned stacked after or on top of a photograph

✔ #6 Functionality

✔ #7 Accessibility

  • color contrast
  • ARIA
  • print versions
  • disabled CSS
  • svg and img attributes
  • descriptive headers
  • keyboard navigability, …

The list goes on, and could be augmented by testing with a screen reader like ChromeVox.

✔ #8 Browsers & Device Compatibility

✔ Usability Testing EXTRA CREDIT

We don’t gate releases of an component — particularly the smallest ones — by usability testing. But we do seek out opportunities to assess component efficacy in related product tests as well as commission our own studies of relevant concepts too.

How We Assure Quality: A QA Workflow

I credit my team with convincing us that the library is nothing if the quality is poor or below a stated standard. Sure, we’d done light damage. Components in the wild now needed light refactoring. And this did trigger a distracting major semver release with a bevy of small, breaking changes. But the library’s demonstrable quality — and team’s confidence — shot way up when we got our act together.

Takeaway: Devise your QA checklist and process as you build your first components. You’ll justify the promise you make to your customers, and improve confidence and reputation as a result.

Where? Using a “Kitchen Sink” Page

Documentation page structure tightly constrains component displays to fit in the article’s width and example box, limiting display options. Plus, the page loads all the CSS of everything it displays, conflating your no-longer-encapsulated component styles with everything else.

Buttons documentation page (left) and all 92,000px of vertically scrolled Buttons “Kitchen Sink” page examples (right)

As an alternative, our team creates a “kitchen sink.” The page bursts with examples: states (default, active, disabled, etc), content (too long, too short, just right, none), colors and themes, all across the many variations (text only, with icon, icon only, etc). We limit loaded CSS to only that component and base styles, improving encapsulation.

We publish sink pages named buttons-sink.html in the same folder as thebuttons.html documentation page. There it rests, a useful if orphaned resource for design reviews, quick reference and automated visual differencing.

Takeaway: Separate documentation from testing artifacts.

When? As a Build Concludes

For our team, QA is part of the Build task.

Takeaway: Incorporate QA as a clear step or sub-step that’ll prevent an item’s release if tests aren’t passed.

Who? The Associated Designer and Another Dev

Takeaway: Identify a predictable role expected to review each contribution.

About to embark on a design system, or need to dive deeper to discuss products and players? EightShapes conducts systems planning workshops and coaches clients on design systems. Let’s talk!


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

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

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