Clarity Design Architecture Part Two

Type System | Spacing and Layout | Theming

Colin Miller
12 min readJul 15, 2021


(Continued from Clarity Design Architecture Part One)

Type System

Design systems need well designed type tools. Too many variations lead to inconsistency, while too few can make achieving proper hierarchy difficult. A carefully selected collection of sizes, weights, letter spacings, line heights and colors, result in the right balance of options to support both consistency and attention to detail. Taken together, these are essential for designers dedicated to creating the visual elegance and usability achieved through vertical rhythm and information hierarchy. The resulting nuanced typography makes the difference between acceptable and great.

Typography is two dimensional architecture, based on experience and imagination, and guided by rules and readability.

~ Herrman Zapf

In addition to the wholesale changes in the way our type system is architected, there were a few aspects of the existing system we needed to update. At a pure hierarchy level with regard to size and weight we lacked range, and nuance in line height. Both resulted in reading difficulty and occasional odd rhythms.

All type classes specified gray with 0% saturation which felt dull and lacking in vibrance especially in lighter values. Classes and tags were tied together. If a designer needed to use the H2 class as the page title (for example), the page structure would violate accessibility requirements, or the developer would have to build in an override. This was creating confusion and brittle code, also adding complexity to responsive design and making upgrades overly complex.

Clarity City Open Source Typeface

Type Enhancements

Classes: We created CSS classes that use names such as: Display, Headline, Title, and Section. This decoupling of tags from classes allows designers to structure applications using type elements that best support the information hierarchy, while developers specify headings and paragraphs that structure the document properly. Design, development, and accessibility all get what they need.

Heading Type Classes with Usage based class names

Line Height Eraser: We added a customization that has become known as the line-height-eraser. This was done so we could have precise control of line heights. Browsers apply line-height equally even if a line of text is the first, last, or only line of textual content. This means that text always has a little extra padding above and below. This is a common problem when one wants equal space above and below a text element to keep it exactly centered such as in the case of a button label. This is a great article looking into this issue:

We created a line-height-eraser that keeps all type within a bounding box that matches the character cap-height, so our leading and vertical rhythm can be precisely controlled. The first and last lines of text in a content block have no additional padding supplied by the browser. Visual alignment begins and ends where the actual text does.

There is a proposal for a new CSS property (leading-trim) that will correct this issue. see: Leading-trim is still only a proposal awaiting adoption by the CSS Working Group. We couldn’t wait until this was implemented in browsers so we built our own workaround. We expect to no longer need it when leading-trim is supported in browsers. In the meantime, it has enabled the implementation of variable line heights. Big props to Scott Mathis for his excellent and meticulous work getting this just right.

Variable Line Height: Clarity NG uses a proportional system based on 6 with baselines of 24 px and 12 px. The Clarity Core system is based on 4 and includes a number of line heights with more granularity. Line height has been further enhanced by adding options for compact, default, and expanded. This is primarily because vertical rhythm for type presents several challenges where enterprise applications are concerned. Power-users regularly request tight information density. To such users a broad and elegantly open screen that makes generous use of white space is perceived as wasteful and less usable. Because of this there is a constant awareness of considering opportunities for more compact layouts.

14 px type BODY with Compact 16px, Standard 20px and Expanded 24px line heights
14 px type BODY with 16 px Compact, 20 px Standard, and 24 px Expanded line heights

The compact line height is useful when type is within a container such as a table or alert. The needs for vertical rhythm are not defined by the type itself but instead by the bounding box of the container. This is an opportunity for type tighter than one might otherwise prefer. There will also always be screens of the opposite sort — landing and login pages, and those with a need for more broad marketing or magazine style layout. In such screens the type often stands alone. This means it must define the vertical rhythm unambiguously given no devices other than line height and negative space. Here compact line heights look incorrect and fail to create the required structure. To create a well designed, sophisticated and attractive design in such cases, expanded line heights are required. These 3 line height options are available in classes where such different contexts are likely.

In order to make the line heights work properly with magnification we needed to refer to em values in the parent type class. To solve this we added CSS modifiers which scale line height relative to the parent by 1.25 (condensed) and 1.5 (expanded). These look like this:

[cds-text*=’compact’] {
line-height: 1.25;
} [cds-text*=’expanded’] {
line-height: 1.5;

Weight: For Heading type classes which were previously light (300) we increased the weight to medium (500). The added ink allows greater hierarchy as achieved through contrast between heading and content. VMware designers expressed a lot of support for these extended hierarchy tools. For P types — we added a scale of weights, greatly reducing the number classes.

Color: Clarity type classes had been desaturated neutral gray. The new system leverages the cool grays in the color system to add a little bit of vibrancy to the type.

Sizes: For Heading types — Some odd sizes (28, 22 and 18) were eliminated in preference to those that work well in a 4 px scale: (24 and 20). 32 and 16 which were present in the old system remained. We added a largest size of 40 px.

Core class vs Angular class

For Paragraph types — we reduced the number of sizes available from 8 to 2, referred to as body and secondary preferring to provide variety via 3 weights and enabling all 3 line heights. This includes guidance as to where each is appropriate and the net result is a calming down of an excessive number of small type sizes. For extra small we included caption and caption-small for use in cases such as footnotes, legalese etc.

Clarity City: We began the Clarity journey with an open source typeface called Metropolis. We liked many aspects of it and being open source aligned with our position as an open source system. Along the way we discovered some details and omissions we wanted to address and decided the best path forward was to fork Metropolis to Clarity City where we have made several of the changes we wanted.

Differences between Metropolis and Clarity City

Clarity City is available here:

Letter spacing: Metropolis and Clarity City are geometric typefaces with wide characters and generous letter-spacing that take up a fair amount of horizontal space. To the same end of space economy important for enterprise applications, many designers and users have been asking about a more condensed typeface. Because these typefaces are essential to the VMware brand, changing them has been ruled impractical for the time being. Some of this was addressed in Clarity City where we tightened up the horizontal flow (see above). The solution in type classes has been to tighten the tracking (letter-spacing in CSS) by as much as 0.5 px on the largest sizes, only allowing regular or expanded letter spacing on tiny sizes where space is not so jealously guarded. Opening up the spacing in these smallest sizes aids legibility.

Usage: In our type survey we found that many designers had questions about usage guidelines and were often concerned with product-to-product consistency. There were also some designers who hadn’t solid grounding in best practices for attributes such as line length / character count and title case / sentence case / all caps etc. Guidelines have been created to address these questions and to provide greater guidance for product-to-product consistency. This is currently a work in progress and will result in a ‘designing with type’ section in our type system documentation.

Type usage guidelines (excerpt).

Space and Layout

Vertical rhythm and information hierarchy are largely controlled by the spacing in and around components (i.e. margin and padding). We had a lot of values coded into the components. This was responsible for inconsistent layout, and brittle code was often created in the process of fine tuning spacing. Product teams did not upgrade as often as they would have preferred to, missing out on new components and enhancements, because re-writing these customizations was often more than their available resources could take on. Similarly, 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 of a successful design system. By creating both space and layout tools we were able to provide design and development tools for consistent rhythmic designs.

Spacing: We designed a system which employed space as a token that can be used against a zero margin / padding value to easily and consistently control layouts. The challenge was to keep this set as small as possible. A large set, while useful for fine tuning and subtlety, becomes cumbersome and performance suffers because the way the tokens are used by applications requires generated CSS which increases the number of values significantly.

The resulting set comprises 2 categories. The first are the space tokens. This is a larger set of values that are used for building components. These allow the construction of components to follow consistent principles and makes them scale properly given things like browser zoom, as well as preparing them to function appropriately in different tech stacks.

Token based -space-

The second set are the layout-space tokens. This is a smaller set which are used for controlling the white / negative space between components. These spacing tokens are in t-shirt sizes allow designers and developers to share a common language. A designer can specify “Use an SM here” and if upon review it is determined that the space needs adjustment, the selected token can be swapped. “Lets try an MD instead”. This becomes extremely useful not only for efficiency but also consistency within applications, and should greatly reduce the effort required when upgrading. This set results in a lot of generated CSS so we kept it to 9 values from xxxs to xxxl.

Token based -layout-space-

Layout Utilities: The companion to our spacing tokens are the layout utilities. These create sets of objects defined by their relationship to one another and the page. Layouts include arrangements such as vertical, horizontal, grid, wrap, stretch/shrink, align, fill, and responsive. With spacing tokens, referred to as gap by the layout utilities, a designer and developer can work together to define how a group of objects is to be arranged. These function just as auto-layout does in Figma.

There are three layouts, horizontal, vertical and grid. Each support main and cross axis alignment. The layouts and Figma auto layout API are almost a 1:1 match. Naming is slightly different.

direction: cds-layout="horizontal/vertical/grid"
alignments: cds-layout="align:top/bottom/right/left"
distribution: cds-layout="gap:xxxs/xxs/xs/sm/md/lg/xl/xxl/xxxl"
padding: cds-layout="p:xxxs/xxs/xs/sm/md/lg/xl/xxl/xxxl"

Figma autolayout is similar to how CSS Flexbox works. "Auto Layout should be a thoughtful subset of flexbox." The main thing Figma doesn’t have is Grid layout. Hopefully at some point they will be able to add support.

We added these layout-space components to Figma. By including the different sizes as variants employing the same names they have in the code, and using them with Figmas auto-layout function, the method almost exactly mirrors the implementation. Switching a space-token causes the layout to realign in the same way an application screen will when developer specifies a different size in the code.



All of these enhancements have allowed us to create a theming paradigm that is simple and elegant. Where our theme switching code was previously in the neighborhood of 17,000 lines of generated CSS it now is around 50. This huge change is largely due to the availability of CSS variables, and dropping IE11 made this massive improvement possible.

This represents a fantastic performance enhancement, and a 10x reduction in code we need to maintain. Less code to maintain means fewer mistakes or inconsistencies. Product teams can load any number of themes since they’re small or they may do so on demand, and in both situations they don’t experience a performance hit. With Clarity Core we can switch between themes with ease and we are assessing how this may enable other useful enhancements in terms of customization.

Dark and Light theme status colors

With the way the system is now architected, themes can use tokens and aliases to control a lot more than just color. Everything that one might wish to have control of from type scales and spacing to corners and shadows is controlled by tokens, so with a little bit of ingenuity (and lots of due diligence for accessibility) all can be adjusted and customized as needed. We foresee theming being useful for all sorts of things moving forward. A future article will discuss the how and what of theming Clarity Core as we continue to expand the system to serve additional needs.


All of these enhancements have allowed us to create a system that is much more useful for the key pain point we wanted to address, that being collaboration between design and development.

The opportunity to rearchitect a design system is rare and not to be taken lightly. With Clarity we embraced the opportunity to look into a lot of things we wanted to improve that might otherwise be impossible due to the cost of breaking changes to a large number of product teams using the system. We feel we have made a lot of innovative improvement to our system and are getting positive reviews from design and development and the enhanced collaboration we sought to achieve is already paying dividends. No discussion of this work would be complete without recognition of the amazing group of developers who brought this all to life, keeping this designer humble in awe of the brilliant work it takes to make it happen: Big up Cory Rylan, Jeremy Wilken, Jeeyun Lim, and Scott Mathis.

Clarity remains open source and we encourage anyone with an interest to take a look and see what our system can do for you. We appreciate all feedback and contributions. We’d love to hear from you.



Colin Miller
Clarity Design System

Design Innovation and Systems. From film, vfx, and advertising to 3D projection mapping —these days helping move UX forward.