Visual Breaking Change in Design Systems

We Respect Code APIs. But What About Color, Type and Space?

Nathan Curtis
Aug 25, 2018 · 8 min read

Can adopters upgrade to a minor release confident that their UI won’t break due to a system’s visual changes?

Semantic Versioning (SemVer) offers clear criteria to communicate change across releases using major, minor and patch designations. Every design system I encounter uses SemVer and monitoring change in their package’s application programming interface, or API. This is familiar territory for developers coding JavaScript props and HTML markup. Break your API, and your next version must increment the version to a next major release, such as from 1.4.0 to 2.0.0.

Breaking Color

Most system teams feel safe in tuning a primary button’s background color. Maybe their motivation is to improve contrast against a usually white text label. “Let’s darken the teal a bit,” they say. “We’ll improve button’s accessible color contrast from a AA to AAA rating.”

Adjusting background color of a primary button

Example: System Text on Custom Backgrounds

Imagine a system team fine-tuning interactive blue to improve color contrast. The interactive-blue of v1.4.0 was accessible on a white background but failed on the charcoal background.

Color contrast checking via
Adjusting text color of a ghost button label on unpredictable backgrounds

Example: System Backgrounds with Custom Overlaid Text

Similarly, imagine a system darkens the Card component’sbackground-color. The Card’s content area includes a "safe" content-container zone where adopters insert whatever content and markup they want.

Adjusting background color of a Card that allows contained custom content
  • background-color on which an adopter's text color is overlaid.
  • background-color, border-color, text color, box-shadow, or other property composed beside, above, or below another component's edge or content so as to diminish contrast between elements.

Breaking Typography (By Wrapping)

Typography is a core facet of any visual style. Teams want to get it just right. And there are so many dials to tune: font-family, font-weight, font-size, text-transform, line-height, letter-spacing, and more.

Example: Wrapping Tabs Are Awful

Imagine your system adjusts tab labelfont-weight from normal to bold.

After a minor version upgrade, unresponsive tabs wrap. Not good.

Example: Letter Spacing Mayhem

Brand guidelines evolve, yielding new heading hierarchy and style. Thus, your system adapts by increasing each heading’s letter-spacing.

Breaking Space and Size

At least you can see color and typography. Space and size? Those are harder to define as concretely reusable, let alone monitor for breaking change.

Example 1: Removing Vertical Spacing

Your system team decides to remove vertical spacing applied form controls in the form of margin-bottom. This impacts <input>, <select>, <label>, microcopy and other elements.

Originally set with vertical spacing built in, a system removes margins. And so forms look smooshed.

Example 2: Custom Sizing Based on Assumed Spacing

After extensive design community debate, your system concedes to expand a Card’s content block’s padding.

A custom icon toolbar wraps after a padding change. Ewww.

Contained, Non-Breaking Spatial Change

Some spatial change doesn’t impact adjacent elements or page composition. For example, tightening or expanding the inset padding or stacked margin between items in a Menu would not be a breaking change because these adjustments are contained within a block that's completely specified by the system, includes no other customizable elements, and is layered in a manner that doesn’t otherwise impact page layout when opened and closed.

What Else Can Break Visual Style?

In general, changes in visual style could be specified as changes to a bevy of CSS properties, the range of which is exemplified by design token collections in Salesforce Lightning, Morningstar, REI, and Open Table.

Adjusting border colors of a component arranged near other components

So, What’s a Visual Breaking Change?

At this point, are you thinking: does this really matter? Shouldn’t we use our system to control our visual language? Are adopters really going to care?


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

Nathan Curtis

Written by

Founder of UX firm @eightshapes. Speaker. Writer. Fan of Arsenal, Hokies. Cyclist & runner. Father & husband. VT & @uchicago grad.


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