Versioning Design Systems

Communicating Change Clearly to People Using Systems

Nathan Curtis
Sep 17, 2018 · 12 min read
Image for post
Image for post


How to Version? Start with SemVer

Image for post
Image for post

What to Version? A Library or Features Within

Versioning the Library

library 1.4.0
├─ visual style
└─ components
├─ button
├─ button group
├─ card
├─ checkbox
├─ radio button
└─ ...

Versioning By Component

library
├─ visual style
└─ components
├─ button 5.3.1
├─ button group 2.1.0
├─ card 3.7.6
├─ checkbox 3.1.0
├─ radio button 1.1.0
└─ ...

System Versions Over Time

Image for post
Image for post
Rate of system change by version type, over a year and a half

The Peril of Major’s Perception


Bucketing Breaking Changes

Image for post
Image for post
JIRA’s Scrum Version panel, mocked up with typical version collections

Deprecation & Ending Life

Image for post
Image for post
During the 1.x.x period, Morningstar added new Notification favored over a deprecated original. Both remained in code and doc until the deprecated version was removed in 2.0.0.

Aligning Versions of Code, Doc, Design, and Tokens

✔︎ Version Doc Separate from Library, But Keep ’em In Sync

/doc-site
/components ## Doc site-only components
/code-example-pair
/do-dont
/tint-stack
/docs ## Doc site content
/about
/components
/contribute
/getting-started
/ux-patterns
/visual-style
/library
/style ## Library core style
/color
/space
/typography
/components ## Library & testing HTML, CSS, & JS
/card
/button
/icon
/radio_button

✔︎ Sustain Doc of Past Versions, By Version

Image for post
Image for post
Morningstar Design System access to past versions via highlighted “View Docs” link

✔︎ Align Design Assets Versions with Code

Image for post
Image for post
Linked library name
Image for post
Image for post
Component-specific version in symbol name
Image for post
Image for post
Component version annotation, in orange

✔︎ Consider Versioning Tokens Separate from Code, Too

EightShapes

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

Thanks to James Melzer

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

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