Image for post
Image for post
An example component hierarchy



├ Primitives
├ Elements
├ Compositions

Understanding the Hierarchy

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.

Image for post
Image for post
A spectrum of high flexibility and low structure to low flexibility and high structure. Primitives, Elements, and Compositions roughly taking up a third of the scale.

If we think of flexibility and structure as a spectrum, different types of components will live along that scale. Primitives at the bottom of the hierarchy are the most flexible. And as you move up in the hierarchy to Elements and Compositions, components become less flexible and more structured. This allows more specific, opinionated components within your library to be consistent, while also providing space for lower-level components to maintain their flexibility. …

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 talents doubled his money and was praised by the man. The second with two talents also doubled his money as was praised. The third however hid his talent in the ground for fear of losing it. …

guidelines for building shared components

Image for post
Image for post
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 intuitive, then discoverable, and last standardized. …

decoupling purpose from outputs

Image for post
Image for post
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 more quickly. This system also has outputs: heat, light, smoke, and sound. Sometimes the outputs are the purpose, but usually they serve a larger purpose. In the context of a campfire, light, smoke, and heat are not the purpose of the system. It’s likely we started this campfire to provide warmth and comfort, or to prepare food, or to have a nice place for conversation. …

Image for post
Image for post
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 across teams, even teams who really care about consistent styling is really hard. You can argue that the cascade is a design flaw, but I’d disagree. We’re scaling CSS in ways no one could have imagined at its inception. …

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 to create self-sufficient UI sections. …

Image for post
Image for post
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 harmonious when you look at the typography. …

Applying Progressive Disclosure to Your Component APIs

Image for post
Image for post

Image for post
Image for post
styled-system logo


Component-based design is an increasingly popular process for developing web interfaces. It was once common for organizations to rely on libraries such as Bootstrap or Material UI. But with the advent of improved tooling, many teams today are building their own themes, component libraries, and design systems. This influx of design and development collaboration is generating many new, exciting systems. That said, rolling your own systems comes with its own challenges and pitfalls. A recent library, styled-system, is an effective tool for navigating some of these issues.

This is an admittedly vast topic riddled with rabbit holes. So, I’d like to limit the scope of this article to four common problems I’ve found in less mature component libraries and how styled-system can help solve them. …

Building Composable Components

Image for post
Image for post
Block Animation


In a previous post, we discussed how our team organizes lower-level tiers of our UI by using Blocks, Elements, and Modifiers. This section will focus on Components, and Part III we’ll cover Compositions. But before we hop in, let’s review the overall structure:

  • Compositions: responsible for handling application-level data and logic
  • Components: responsible for handling UI logic and rendering Blocks & Elements
  • Blocks: responsible for rendering their child Elements and their own context (logic-less)
  • Elements: responsible for rendering themselves and handling their modifiers (logic-less)
  • Modifiers: responsible for modifying Block & Element styles in a predictable manner


Rigid Component APIs

As mentioned above, Components are responsible for UI logic and rendering Blocks and Elements, and they look like common React components. …


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