Part One | Redefining Value

This is the first of three articles discussing aspects of shared component libraries, whether in a design system context or otherwise. Specifically, we’ll look at how we define value, understanding cost, and how to build for the future. This article will focus on how we think about the value of a shared component library. I find the value of shared components is often misunderstood and misrepresented, and it deserves a bit of redefinition before we can talk about the other aspects.

When folks describe the value of a shared component library, they often talk about a few common attributes: UI…

highway roads illuminated at night by cars and street lights
Photo by Amarnath Tade on Unsplash

Understanding the spectrum of control in design systems


When describing a design system, I usually default to Donnella Meadows’s definition of a system (which I’m paraphrasing) as interconnected elements that have a shared function or purpose. That’s an oversimplification, but it’s a good starting point. When talking about a design system, we often focus on the elements; the components, specs, docs, tooling, maintainers, consumers, et al. But I’d like to talk a bit about trust and control as a dyadic interconnection that binds these elements together. Systems are dynamic and complex structures that often behave in ways we don’t expect…

An example component hierarchy


├ Primitives
├ Elements
├ Compositions

The main purpose of the hierarchy is to provide a focused scope of responsibility for individual components and meaningful relationships between them. This allows components to be composed in ways that provide a healthy balance of structure and flexibility. Without structure the components become misaligned and inconsistent. But without flexibility, the components become brittle and tightly constrained in their use. For a healthy component library, you need both.

an open letter to white folks

I’ve been thinking a lot about Jesus’ Parable of the Talents¹ and how it relates to us today. If you’re not familiar, I’ll give you a short summary:

A man is going on a long journey and entrusts three servants with talents (money) before he leaves. To the first he gives five talents (~100 years’ wages for a laborer). To the second he gives 2 talents (~40 years wages). And to the third he gives one talent (~20 years wages). Upon returning the man settled accounts with his servants. The first servant with five…

guidelines for building shared components

Photo by Daniel McCullough on Unsplash


This is a high-level description of API guidelines for shared components. It is intended to provide a general framework for creating resilient and adaptable components. These guidelines are derived from three main concepts:

  • Make the right choices easy
  • Make incorrect choices obvious
  • Provide helpful off-ramps

Make the Correct Choices Easy

Documentation is great, but if users are constantly scouring the docs and source code to remember how to use shared components, that’s an indication of inconsistent APIs. Ideally, the library should teach you how to use it as you interact with it. There’s an interaction design hierarchy that describes this well:

Interactions should be first…

decoupling purpose from outputs

Photo by Marko Horvat on Unsplash

What are Systems?

Note: This article references several concepts from systems thinking, most of which are derived from Thinking in Systems: A Primer by Donella H. Meadows. If you’d like to learn more about systems thinking, I would highly recommend it.

We can think of any system as a collection of interconnected elements that serve a purpose or function. Let’s use a campfire as an example. We have elements: wood (fuel), oxygen, and heat. And those elements are interconnected. If you deprive the fire of fuel or oxygen, it decreases the heat. And if you increase the heat, you deplete oxygen and fuel…

Photo by Henrik Eikefjord on Unsplash

Is Actually Humans

The problem with CSS conventions is that they rely on developers to manually maintain them with a high degree of accuracy to be effective. This problem is compounded as styles grow. Each developer needs to know more context in order to effectively style UI. That’s why “You should just write good CSS” is an insufficient response to “How do we keep styles maintainable?” Even developers who write great CSS are challenged with an ever-growing problem.

All that to say, the problem with CSS isn’t CSS, it’s humans. We can only keep so much in our heads, and sharing that knowledge…

Coupling Containers to their Concerns


This document was created to clarify details about the composite component pattern and component responsibilities. It also includes examples and testing guidelines. The patterns described here are intended to be general guidelines, not requirements, and are intended to be used when reasonable. The purpose of establishing these patterns is to provide enough structure for consistency but also allow flexibility for adaptation. Regardless of the author, code structure should feel consistent but not necessarily uniform.

Borrowing from composite materials, which combine two or more different materials to create a single superior material, the composite pattern combines connectors, components, blocks, and elements…

Photo by Dawid Małecki on Unsplash

Lessons from a Failed Component API

It’s always fun to promote successes, but it’s also good to learn from failures. I’d like to share a bit about a component API I built that was a failure in hopes that your components will avoid a similar fate.


We use a double-stranded modular scale for all our typography and spacing, and it’s really cool. Here’s a great article if you’d like to read more about modular scales. The basic idea is using math to create a harmonious type scale. If you were looking at the individual values you might not think they were in pattern, but they feel…

Applying Progressive Disclosure to Your Component APIs

Alan B Smith

design systems @workday

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