Clarity Design Architecture Part One
Enhanced Collaboration | Color System
We recently embarked on the large project of updating the way the design foundation of Clarity is built and organized. This article and its companion will go into the changes and enhancements we’ve made to our color, type, space and layout, and theming systems. These are all essential foundational parts of Clarity, and the opportunity to reimagine them has been both fulfilling and fruitful.
First things first
Where do you start when reimagining an already mature and well-adopted system? How can observation and understanding of the challenges in the current system help us to design and build an updated one that works better for everyone?
What changes and enhancements will most benefit our users?
What are the use cases and pain points to which these apply?
What research should we do to support this?
Referring to these questions while reviewing our day-to-day Slack discussions, office hours, and research initiatives, as well as feature and component requests, all pointed us in the direction of Enhanced Collaboration between design and development.
This idea of enabling designers and developers to collaborate more effectively based on a shared understanding became our focus. Given this guiding principle, we ask: What are the challenges to address in achieving this goal? How do we evolve a system already extensively employed in production?
One of the most interesting challenges is how to evolve a system that is mature, already working, and well adopted.
Making Decisions
To reach our goal, we had to answer many questions: How do we introduce breaking changes when they will cost product teams additional development effort and possibly introduce inconsistencies in cross-product workflows? How do we continue to evolve while supporting legacy browsers? How do we support development teams using various JavaScript frameworks? What kind of support and documentation will we need to provide? How do we help teams plan version upgrades?
With Clarity, these challenges included: Over 100 products and a highly engaged open source community, each using various releases and aspects of the system, and support for a large selection of browsers. These products are used by companies worldwide in every imaginable configuration. With such formidable challenges, a mature design system can find its success becoming a liability. Change must be methodical and incremental, considering how users will adapt, adopt, and migrate. We made a few key decisions and these gave us the freedom to significantly reimagine and rework the way the system is architected and implemented.
These decisions:
Web components — known as Clarity Core. This reworking of the library allows us to be framework independent. React teams can avail themselves of the benefits of the library while Angular teams can integrate web components piecemeal. See this article from Scott Mathis covering our web components strategy. https://medium.com/claritydesignsystem/clarity-core-72f6d3a029bc
A ‘small shift’ approach. Visual and functional parity for equivalent components would remain close enough to not be an impediment to incremental adoption.
Discontinuing support for IE 11. This was primarily because most Web APIs needed in modern Web apps are not supported. Since we made this decision, wider discontinuation of IE (Microsoft and Google Angular) has come.
With these added opportunities and a few impediments removed, we embarked on re-architecting the system. This work included a few enhancements I’ve been wanting to add for a while.
Enhancements
Color System: Offering both light and dark themes guided us towards creating a universal color system using tokens and aliases. This allows consistency, control for accessibility concerns, semantic accuracy when it comes to status, object and interaction styles, effortless theme switching, and additional useful structures such as support for a charts system. Switching to HSL was helpful by enabling alignment around exact hue choices, then using lightness and saturation adjustments to ensure accessibility everywhere. Once this foundational system of colors-as-global-tokens was created, a system of functional aliases was added to define usage in a semantic way, ensuring all traffic-light / icon / UI control / interaction style colors were consistent across applications.
Type System: Typography is always a top concern for any designer seeking to create visual elegance while achieving the usability benefits of finely crafted vertical rhythm and information hierarchy. Clarity’s initial type system had a few things I wanted to address with regard to this. The largest sizes were light and maxed out at 32 px. Line heights were based on a rigid adherence to 24 px with occasional allowance for 12 px resulting in some running text being overly tight while other text was excessively broad. Both can result in reading difficulty and occasional odd rhythms.
All type classes were gray values with 0% saturation which can be perceived as dull and lacking in vibrance. Classes and tags were tied together — when a designer wanted to use a class in a way that was at odds with its tag, the document would violate accessibility or the developer would have to build in an override. This created discontinuity between appearance and structure. These overrides often subvert the cascading aspect of CSS, meaning that upgrades might produce no effect and require teams to manually rewrite their code.
Space and Layout: Vertical rhythm and layout are often largely impacted by how components are built regarding margin and padding, and how these values are controlled. We had a lot of values coded into the components rather than abstracted to the system level. This sometimes led to inconsistent layout and brittle code as well as responsive and zoom problems. In addition, custom components made by product teams didn’t have a set of building blocks to which they could refer. All of this contributed to difficulties with maintaining consistency — one of the key benefits to a design system, and a very important one at VMware considering how many products and cross-product workflows Clarity impacts. By creating both spacing tokens and layout utilities, we were able to provide design and development with the tools for consistent rhythmic designs, as well as the flexibility to easily customize layout as needed.
Theming: All of these systems have allowed us to create a theming mechanism that is simple and elegant. With Clarity Core we can switch between light and dark themes with ease, and we are considering how this may enable many other useful customizations.
Color System
New for Clarity Core is a redesigned color system. We took this opportunity to address a few things we wanted to update. These include:
Switch to HSL
Increased saturation
Non-neutral grays
Global tokens
Functional aliases
Aesthetic enhancements
Charts palettes
HSL — we like HSL because the values are human-readable. It doesn’t take a lot of familiarity with the way colors work to learn where various hues fall. With this basis the saturation and lightness values become self-explanatory. Looking at the 3 numbers will give you a pretty good idea what color you are going to get. Tints, tones, and shades stay pegged to a central hue and calculating compliments is simple (add or subtract 180 from the hue). This also eases shifting hue either for simple warmer / cooler adjustments, or in more sophisticated cases such as keeping yellows fresh as they get darker. Hue shifting is also useful for multi-color gradients often preferable in data visualization and for colorblind users. see: cran.r-project.org intro-to-viridis
Increased Chroma — Upon reviewing the system as a whole, examining a lot of product screens, and interviewing many product designers, we found support for our observation that the system was lacking in saturation. Every opportunity to make an adjustment that favored a little more juice in the chroma was embraced, leading to a more vibrant palette. Working in HSL was extremely useful in this because, once a hue was locked, we could adjust saturation and lightness with attention to both aesthetics and maintaining accessibility compliance.
Non-neutral grays — other areas for improvement were the construction and typographic grays. Clarity was using flat values with no chroma. We took the opportunity to shift the system to using cool grays in service of added vibrancy and chroma as above. The saturation is quite low — just enough to ‘take the curse off of it’ as a great director I used to work with was fond of saying. We use these cool grays for type and for the construction lines that make containers, as well as for shadows. The difference is largely invisible unless you look at the before and after side-by-side when the increased life in the interplay of elements is apparent.
Global tokens. We did a meticulous survey of all the colors used in both the Clarity Light and Dark themes. This included an accessibility audit for bugs and desired enhancements and an aligned system for data visualization color themes. Given this understanding, we created a global Clarity palette to provide a universal set that supports all these needs. This set comprises 211 colors in total. These include 5 functional, 8 utility, 5 muted, and a construction set, each in 11 shades from pastel to rich. In keeping with our theme of human-readable code we use -black- and -white- instead of HSL or HEX values at these poles.
Functional aliases. To simplify the theming attributes and create consistency as well as human readability across the system, we refer to any frequently used values by way of aliases. Thus — cds-global-color-green-700 which functions as our primary success color, is referred to as — cds-alias-status-success. Should a theme require a different color for this function, remapping the alias to another global is all thats required. In addition to the primary status color, there are closely related aliases -tint- and -shade- in this case — cds-alias-status-success-tint and — cds-alias-status-success-shade which allow and support dynamic but related color shifts (such as hover) without employing transparency which can confound accessibility evaluation. This is also is useful for multicolored components such as alerts. Cory Rylan has been the master of this system of globals and aliases — his work has made this clear, useful, and easy to understand.
Aesthetic enhancements — We didn’t love the ‘yellows’ (actually more of a mustard or butterscotch) used in Clarity Angular. These were a source of a lot of discussion since they weren’t actually yellow. We took this opportunity to update these components to use a true yellow.
Charts palettes and system — charts have long been a user request for an addition to Clarity. Since this is a large undertaking for a small design system team we took the initial step of creating charts themes aligned with Clarity color. By creating charts sets via aliases which map global colors to their function in the chart, a collection of sets which can switch within and between themes is enabled. This allows applications to do things with charts that enhance usability, such as emphasizing a visualization dynamically through interaction, or creating differentiation within dashboards.
We are moving ahead with more complete themes for Clarity charts that include type styles and textures and will be adding them to the system. Stay tuned.
The opportunity to reimagine the way we define and organize color has allowed us to update it in ways that would be much more difficult were we required to do so in the system being used in live products. We made a serious effort to keep close to the existing colors to make migrations as invisible as possible. At the same time were were able to redesign the CSS including our shift to HSL, increasing the chroma overall, switching to non-neutral (cool) grays for type and construction lines as well as shadows. We codified all this with global tokens and employ these colors in an elegant fashion via aliases. We also made some aesthetic enhancements particularly with regard to using a true yellow and added a charts system derived from the same globals and based on the aligning principles.
The next article will include the Type System, our Layout Utilities and the Token Based Space Primitives they use, and how all these systems come together to enable Theming in a powerful and flexible way.
Visit us at our website https://clarity.design and connect with us on GitHub.
