We’ve released Clarity Angular v12, and we’re making some simple updates to how we ship Clarity Angular to align better with Angular’s release cycle.

We’re excited to announce Clarity Angular has a new version available, with Angular 12 support! This anticipated release is easy to install, run the following with the Angular CLI to update your Clarity Angular packages to the latest release that will work with Angular 12:

ng update @clr/angular@12

This will update your Clarity Angular packages to the latest release that will work with Angular 12.

Why the version change?

We are releasing the next major version of Clarity Angular as version 12, which skips a few numbers ahead to align with Angular version numbering. Aligning versions with Angular has the advantage of making it clearer which version of Clarity Angular and Angular are compatible.

When we released Clarity Angular v1 several years ago, we similarly updated our release cycle to match Angular’s releases. We will continue to update Clarity Angular to work with each new major Angular release.

What is new in Clarity Angular?

The only changes are related to updates for Angular 12 and TypeScript compatibility. There are no other breaking changes if you are updating from Clarity Angular v5. We will continue to fix and release patches for bugs in Clarity Angular on an ongoing basis as well.

If you haven’t seen our updated support strategy, rest assured that we are continuing to maintain and support Clarity Angular into the future as long as there is critical use. As part of that strategy, we also are not making major feature improvements and avoiding breaking changes to Clarity Angular, so it can be a long term stable platform for teams who are still using it.

What about Clarity Core?

We worked to separate our Clarity Core and Clarity Angular codebases, which will allow us to release each independently of one another. That means that Clarity Core will continue to release under v5.x release branches until we have a breaking change. We are working on a Clarity Core v6 later this year, but more will come on that later.

We’ve recently launched 7 new Core components into beta: Table, Tree View, Cards, Panel, Vertical Navigation, Breadcrumbs, and Navigation. Documentation about these can be found in our Storybook demo app, and we’ll be adding them to our main documentation site in the coming months. We’re currently working hard on the Datagrid and Dropdown components and expect the beta versions to arrive in the coming weeks.

Common questions

Let’s quickly address some of the common questions and concerns that we’ve been answering related to these changes.

• Is Clarity Angular being deprecated or abandoned? — In January we outlined our path forward with Clarity Angular and nothing has changed. We will not release any new components or major features in Clarity Angular, but we are continuing to support it with bug fixes and updates for major Angular releases. The goal is to ensure that Clarity Angular is as stable as possible so you can continue to use it as long as you need.
• Can I get the Angular documentation with interactive demos? — Yes, we are nearing completion of several efforts with our documentation, which will bring the original Clarity Angular website back with latest updates. Look for updates on this soon!
• Should I quit using Clarity Angular? — You can safely continue to use Clarity Angular as long as you need it. We recommend that you consider planning your journey for how you expect to evolve your application and anticipate how you can adopt Clarity Core on your own timeline to get the new features, better accessibility, and long term stability. If you start with a new website today, we recommend using as much from Clarity Core as you can, and fill in with Clarity Angular if needed until we have finished Clarity Core components.

By fully separating Clarity Core and Clarity Angular, we have a better path forward to support our communities while also innovating for our framework independent goals. It is going to enable us to move faster, to more easily document things, and make it easier to support applications looking to transition from Clarity Angular to Clarity Core on their own timeline.

Got questions? Ask in GitHub or connect on Twitter!

Clarity Angular version 12 is available! was originally published in Clarity Design System on Medium, where people are continuing the conversation by highlighting and responding to this story.

Type System | Spacing and Layout | Theming

(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.

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: https://medium.com/microsoft-design/leading-trim-the-future-of-digital-typesetting-d082d84b202

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: https://www.w3.org/TR/css-inline-3/ 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.

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:

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

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.

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.

Clarity City is available here:

• vmware/clarity-city
• Designing

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.

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.

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.

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." https://www.figma.com/blog/behind-the-feature-the-making-of-the-new-auto-layout/ 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.

Layout

Theming

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.

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.

Conclusion

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.

• Clarity Design System
• JavaScript is not available.
• vmware/clarity

Links and further information

• Web Components Overview
• Core (@cds/core) | Clarity Design System

Clarity Design Architecture Part Two was originally published in Clarity Design System on Medium, where people are continuing the conversation by highlighting and responding to this story.

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.

Clarity Design Architecture Part One was originally published in Clarity Design System on Medium, where people are continuing the conversation by highlighting and responding to this story.

Intro to Clarity Core

Clarity 4.0 was one of the most impactful releases in the history of the Clarity Design System. In 4.0, the new Clarity Core package of web components emerged from its 3.0 preview/beta status and introduced almost two dozen new components. Clarity also released the Clarity React library in 4.0, extending Clarity support for the first time to teams using React.

This is a huge milestone for Clarity and marks the beginning of a new era of framework independence.

But something new rarely manifests without changing what has come before.

With the 4.0 release, the Clarity Icons (@clr/icons) package will be deprecated. The Clarity team’s current plan is to end-of-life Clarity Icons at a currently unspecified future date. After the 5.0 release, however, @clr/icons will have no new icons added to it and new major versions will stop at 5.0.

What?! Why do this?

Clarity Icons was important to Clarity for a couple of reasons:

1. It was one of the first projects to use web components to deliver a library of SVG icon glyphs. When I delivered the original proof-of-concept for Clarity Icons in November of 2016, the dominant implementation of icon libraries were “icon fonts”. Icon fonts used icon glyphs that were accessed through the private use area (PUA) of a webfont. This was a good solution at the time. But it had its limitations. And then there was that horse problem. Clarity Icons allowed us to leave all of that behind and embrace the future with web components and SVG.
2. Clarity Icons were a precursor to our current framework-independent future. While the web component portion of the original Clarity Icons package was not as full-featured as the web components in Clarity Core, Clarity Icons played a significant role in sparking conversations among the Clarity team about using web components as a basis for a full library of components. Even though the delivery of a Clarity web component library with @cds/core would ultimately make @clr/icons redundant, there would not be a Clarity Core without Clarity Icons.

Now that Clarity has delivered a library of web components, it makes sense for us to roll Clarity’s library of web component icons into the project where all the other web components live. And, while the @clr/icons package is deprecated, its vision and mission will live on inside of Clarity Core.

A great reason to use Clarity Core… tree-shaking!

In addition to carrying forward the functionality and icons from the previous library, moving over to @cds/core allows Clarity to offer upgrades to the library that will improve developer experience, bundle sizes, and performance.

When the original Clarity Icons library was created, our build architecture was not tree-shakeable. “Tree-shaking” here refers to the capability of build tools like Rollup to remove unused JavaScript code from a project when it is bundled for delivery. The point of tree-shaking is to reduce the amount of JavaScript in an application by removing code that the application doesn’t need. Larger files take longer to download and longer for the browser’s JavaScript engine to parse.

Tree-shaking results in smaller bundles. So it’s a good thing.

When we began writing code for Clarity Icons, the Clarity team was using Gulp to package and deliver its component library. Webpack was the better part of a year away for us and getting the project on Rollup/Webpack and creating the icons library were parallel items of work. Clarity Icons was largely complete when the Rollup/Webpack work was just getting started.

As a result, tree-shaking was still just a thought experiment for us when @clr/icons was introduced. Many teams who have migrated their codebases from pre-Webpack to post-Webpack are likely familiar with the limbo of “we didn’t know what we didn’t know” when it comes to optimizing their project’s ability to treeshake.

As a result of architectural decisions early on in the Clarity repository, Clarity Icons would not be tree-shakeable. This meant that if you used one icon in an icon set all of its friends would be coming along for the ride!

We identified this as a problem long before Clarity moved to Webpack in version 0.10.8 (October 2017). But fixing this problem would require an overhaul of how our repository was structured and how the hundreds of icon glyphs were delivered.

Like technical debt in a lot of projects, re-writing the Clarity Icons library and re-structuring our build never jumped to the top of our list of priorities.

Clarity Core gave us an opportunity to tackle this.

As my colleague, Cory Rylan, demonstrated in a recent article, being able to re-imagine a new component library from the ground up gave us an opportunity to redouble our focus on improving performance, maintainability, and bundle-sizing. The result has yielded a tree-shakeable library of icons. This makes the @cds/core icons library a significant upgrade over its predecessor.

Migration

By now, you are hopefully super-eager to jump onboard Clarity Core. The migration path to the Core icons from any prior version of @clr/icons is straightforward because the Core icon library is backward-compatible to a large extent.

Here are the detailed steps for migrating from Clarity Icons to Clarity Core:

1. Add @cds/core to your project.
2. Substitute clr-icon web components in your application with cds-icon. A developer may be able to do a find-and-replace to complete this step.
3. Add icons to the ClarityIcons registry as needed. Depending on how ubiquitous the icons are in your application, this may be incredibly easy or a chore. Whether your team chooses to create an inventory list of all icon shapes in your application and then add them all in one big listing in the application module or whether your team prefers to add the icons on a component-by-component basis, Clarity Core icons offer multiple paths to migrate.

Here’s an example of what a migration could look like:

Core icons are backward-compatible but…

In Core version 4.0, Clarity Icons’ full API — including all CSS classnames, icon shapes, and aliases — was re-implemented to make migration easier.

This legacy code, however, has been replaced with an improved API in 5.0.

For illustrative purposes, the following code examples demonstrate how tasks in Clarity Icons (before) can be accomplished with Clarity Core (after 5.0).

Note that Clarity Core versions 3 and 4 are under the @clr/core package name on npm. In versions 3 and 4, the CSS classname-based API of Clarity Icons’ “clr-icon” component should work as expected but we recommend applications migrate to the new Clarity Core code examples.

Using Icons

Previously, using an icon in Clarity required importing the Clarity Icons CSS file and the @clr/icons file.

Including a CSS file to display icons is no longer necessary in Clarity Core.

In addition, loading the @clr/icons file would automatically load the “core set” of icons. Clarity Core no longer does this. To use an icon in your application, it must be added to the @cds/core ClarityIcons service as shown below.

Clarity Core also has a separate registration file for the icon web component that needs to be imported.

As before, icons are rendered in your application via a custom element (a.k.a. web component). That has remained the same but the prefix of the web component’s tag name has been changed.

Why change the tag name prefix?

Tag names in @clr/angular and @clr/icons are prefixed with “clr-” and all tag names in @cds/core are prefixed with “cds-”.

To prevent namespace collisions and overloading for teams using Clarity Core alongside Clarity Angular (or even Clarity Icons by itself), Clarity Core (@cds/core) could not use the same tag name as the other Clarity libraries.

We did not want to force users to choose between Core and Clarity Angular or Clarity UI, so we needed them to work alongside one another to some degree. Changing the prefix for Clarity Core’s web components was the best path forward to achieve that.

While the old “clr-” prefix was a derivative of the word “clarity”, the “cds-” prefix is an abbreviation of the phrase “Clarity Design System”.

How to add icons to the API

Clarity Icons could always add custom icon glyphs to the icon registry and share them across an application. @cds/core supports this as well.

As mentioned previously, the 4.x Clarity Core icons API is backward-compatible. So all of your old code will still work if you point it to the v4 or earlier Clarity Core icons API — assuming you’ve changed your tagnames from <clr-icon> to <cds-icon>.

Support for this legacy API will no longer be available after 5.0.

That makes this is a great opportunity to learn how to move forward with Clarity Core after legacy support ends.

Why “addIcons()” when “add()” is more succinct?

When we delivered the Clarity Core icon API, we wanted to make sure we had at least one version that was backward-compatible. addIcons() was the clearest choice for a method name because add() was already taken by the legacy API. We couldn’t change the call signature (a.k.a. the type and number of arguments passed to the add() method) without breaking backward-compatibility.

In the future, add() will be re-introduced as a method of the Clarity Core Icons API but will be an alias for the existing addIcons() method. So, in the future, the Clarity Core Icons API add() static method will have an identical call signature to the current addIcons() class method.

What are you doing in the arguments with the arrays?

Technically, the icon name and shape “array arguments” are tuples. They are easy to work with and don’t carry around a lot of the baggage associated with a vanilla JavaScript object. No checking for hasOwnProperty and all that.

One day, JavaScript will have a true tuple data structure. Until then, we have this “array thing”.

Add a custom icon

We’ve gone over the method that will add an icon to the Clarity Core Icons API. But we haven’t covered how to format a custom icon to have it fully integrated with the API.

There are a couple of ways to do this. One way is straightforward and requires a bare minimum of work on a developer’s part. The second way makes a custom icon a first-class citizen inside Clarity Core but requires a little more understanding of the internals of the icons API.

Let’s go over both of these approaches now.

Using an SVG

The easiest way to add an icon to the Clarity Core icons API is to pass an icon name and the SVG of the icon as a string in the tuple argument of ClarityIcons.addIcons().

• The appeal of this approach is that it is easy. There’s not a lot of extra work to get from an SVG that a designer sent you to a glyph stored in the API.
• The drawback of this approach is that the badging, status colors, and other functionality will not be available for that icon. It will only render what you pass to it.
• Make sure you remove widths and heights from the <svg> tag itself. These might introduce unintended side effects when sizing your icon.

Using an icon template

Those who are familiar with Clarity Icons understand that the icon components do a lot more than store an SVG in a registry. So how can you create an icon that takes advantage of all that built-in functionality?

The answer is using a Clarity Core icon template.

• The renderIcon() function in the example above converts your icon template into an SVG. It builds the SVG for you and applies the formatting the icons library needs to be able to show solid, outlined, badged, and alerted icons when you tell it to.
• Icons inside an icon template should be designed with a 36px x 36px viewbox.
• The icon template accepts <path>, <circ>, <rect>… virtually any SVG you throw its way. SVG wrapped in a <g> tag or other nested SVG structures may cause problems for it, however. Pass only flat paths and shapes and make sure that all SVG shape tags are self-closing (<path … /> instead of <path …></path>).
• In the early days of Clarity Icons, we had trouble using CSS styling to customize strokes in some problematic browsers. As such, our library has always recommended using filled paths instead of strokes. This has not changed. Icon templates will be your best friend if you convert strokes and fonts in your glyphs to outlines/paths before exporting SVG from your vector art program of choice.
• Not all of the properties in an icon template need to be defined. In the example, my-dot only has an outline and solid path. custom-icon has paths for everything! Core icons are smart enough to fallback to outline if you don’t have a solid variant or the solid or outline variant if badged and alerted variants are requested but not defined.
• Including the badge-dot or warning-triangle in your badged and alerted paths is not necessary. The icon service applies those for you. But your icon will look better if it allows space for the circular badges and warning triangles. Even still, the icon library will apply the dot or triangle over any path you send it if the badged and alerted properties are defined in the icon template, as shown with custom-icon in the example.

Aliases and sets

The Clarity Icons API gave users the ability to “alias” icon glyphs under different names and also load large sets of icons all at once.

This meant you could refer to icon glyphs by different names like “menu” instead of “bars”, “settings”, or “gear” instead of “cog”. In addition, sets gave users the ability to load dozens of icons with a single command. A lot of that changes in Clarity Core.

Don’t use sets. With Clarity Core, we recommend against loading sets of icons because it presents challenges with tree-shaking. Products rarely use all the icons in a set and it is not wise to load all 129 icons in the “essential” set yet only use ten of them. Clarity recommends adding icons as they are needed. This is the optimum way to ensure applications remain lean and performant.

Add icons, don’t alias them. As far as aliasing goes, @clr/core supports aliasing in 4.0. But we have a preference for adding icons instead. It does the same thing under the hood and there is no need for an application to be required to use Clarity’s naming conventions. Feel free to name our icons anything that makes sense for your application’s domain.

Using an icon in your app

Besides the new cds- prefix, using a Clarity Core icon in your application is no different than it was in @clr/icons.

But the new Core icon library has given us an opportunity to improve the developer experience.

The following examples are going to compare and contrast common use cases in @clr/icons with the preferred way to do the same thing in @cds/core. There are some running themes and migration should feel logical once a developer has a little practice migrating a couple of features.

Size

A stealth improvement in @cds/core is related to how icons can be sized. Previously, a @clr/icons component could be sized in one of two ways: setting the style attribute on the icon or passing a numeric string into the icon’s size attribute.

The numeric string approach caused problems for teams with strict content security policies. This is because passing a number to the size of the attribute on the <clr-icon> element causes the web component to programmatically set its own style attribute. Some CSPs view this as a violation.

Clarity Core improved the size attribute so that it can now accept t-shirt size values (xs, sm, md, lg, xl, xxl). T-shirt sizes resolve those CSP concerns by setting the icons to a handful of predefined dimensions without writing to the style attribute.

Direction

As with the old @clr/icons web component, users can set an attribute to rotate the icon glyph. In @clr/icons, this was the dir attribute. In @cds/core, the attribute is direction.

But, wait, there’s more!

@cds/core also introduces the flip attribute. This inverts the icon along its horizontal or vertical axis.

Solid

Similar to other items listed above, @cds/core accomplishes the same thing as the legacy @clr/icons did but by using an HTML attribute instead of a CSS classname.

This is consistent with how solid and outlined (filled and not filled) icons are rendered.

In @clr/icons, users had to use the is-solid classname on the web component to display an icon’s solid variant. In @cds/core, users only need to add the solid boolean attribute.

Inverse

An “inverse” icon is an icon that is filled with a light color instead of a dark color. By default, this color is white. These are helpful when you need an icon on a dark background.

The difference between Clarity Core and Clarity Icons should start to feel familiar by this point.

Instead of burdening applications with Clarity-specific CSS classnames, Clarity Core accomplishes the same styling through HTML attributes. This is consistent throughout all of our components in Clarity Core.

As with solid icons, inverse icons used to use the “is-inverse” classname in @clr/icons. But now they use the inverse attribute.

Statuses and Colors

Clarity Icons also allowed for the icon glyphs to show in a number of predefined colors (green, ochre, red, and blue) in addition to the icon inheriting its host element’s text color (generally the default dark gray).

These colors are aligned with statuses in Clarity and constitute the familiar triad of “stoplight colors” –success, warning, and danger–with blue as an “info” or highlight color.

As with the other cases above, @cds/core uses an attribute — called status — where @clr/icons used a CSS classname.

Badged and Alerted

In both Clarity Core and Clarity Icons, icon glyphs can have “badged” and “alerted” variants. These variations feature a decoration in the top right corner of the icon glyph.

• For “badged” icons, this decoration is a round dot.
• For “alerted” icons, this decoration is a triangle.

This remains consistent in Clarity Core and Clarity Icons.

In @clr/icons, badges and alerts on icons were shown by adding a CSS classname. If you didn’t skip ahead, the next part should come as no surprise.

In @cds/core, badges and alerts are shown by adding an HTML attribute.

Clarity Core has one new twist that was not available in @clr/icons, however.

Both the alerted (or “triangled”) icons and badged (or “dotted”) icons can now be set to an “inherit” mode.

An inherit-mode means that the icon decoration will display with the same color as the rest of the icon.

By default, the badged dot is red and the alert triangle is dark orange (a.k.a. ochre). By setting them to inherit the color of the rest of the icon, you make the badge, the triangle, and the rest of the icon all one color.

In summary

The introduction of @cds/core gave the Clarity team an opportunity to revisit Clarity Icons and improve its API and performance. Now that those upgrades have been introduced, it’s time to say goodbye to @clr/icons.

The @clr/icons package has been deprecated in 4.0 and will end-of-life in the future. The exact date has not been determined (yet).

It is recommended that all teams using @clr/icons migrate to @cds/core as soon as possible. The 4.x version of the @clr/core library is fully compatible with the public API of @clr/icons. We did this to give teams a chance to migrate at their own pace. But no new icon glyphs will be added to @clr/icons and no future support will be given to it after it reaches end-of-life.

The Clarity team is incredibly grateful for @clr/icons. The effort of Shijir Tsogoo and many others put Clarity on the bleeding edge of icon libraries as one of the first SVG and web component-based solutions in early 2017. It also served as the proving ground for what eventually became Clarity Core and our drive for framework-independence.

We hope that current users of Clarity Icons will find that the icon library in Clarity Core carries forward the innovations introduced in Clarity Icons. We also invite current users of @clr/icons to join us on our journey as we continue to embrace web standards and a framework independent future.

Goodbye Clarity Icons, Hello Clarity Core! was originally published in Clarity Design System on Medium, where people are continuing the conversation by highlighting and responding to this story.

The concise guide to using Clarity Core, in any project, right now.

Last year, we shared an article about our Clarity Core initiative and our drive towards a new future. Many applications have already been using Clarity Core (our web component implementation of Clarity) in their projects, and it is already getting over two-thirds the number of weekly downloads Clarity Angular has been getting for the last two years! We’ve shared that our web component implementations are Clarity’s future because it helps any application quickly adopt and align to Clarity patterns and components regardless of what frameworks they use.

If you haven’t started using Clarity Core, this is your guide. This post is aimed at projects using Clarity Angular today, who haven’t yet adopted Clarity Core. Major changes in a design system can have a big impact on productivity, and we’ve worked hard to provide a path forward to give existing Clarity Angular projects the flexibility and freedom they need to choose when and how to adopt Clarity Core. For applications that are using Clarity Angular today, we made the following promise:

The goal is to make [adopting Clarity Core] as minimally impactful to existing Clarity Angular applications as possible.

In this post, I’m going to walk through how we’re going to support you in leveling up your application by adopting Clarity Core. I’ll outline the path for applications using Clarity Angular and share details about how we will partner with you on this journey to align on Clarity Core.

First, we need to understand where things stand with Clarity Core and how it relates to Clarity Angular.

Clarity Core is Available NOW, with FREE Expansion Packs Coming!

Clarity Core is the implementation of Clarity written in web components. We created Clarity Angular using Angular as the foundation, and therefore requires applications to be written with Angular to get the full benefits of Clarity. As we aim to support all applications, written in any framework, Clarity Core is central to making that possible.

Clarity Core has made significant progress in the past year and has been available since February 2020. However, we recognize that for many existing projects it doesn’t offer much that wasn’t already in Clarity Angular. Some people wonder why you would update to the latest Xbox when it doesn’t have any games that are worth updating for yet. We have more work to do to bring our library of web components up to parity with Clarity Angular, so you can expect to see more in the coming year.

Today, we have over two dozen components available in Clarity Core, which account for more than half of the components we have in Clarity Angular. This first wave of Core components includes frequently used and fundamental building blocks, such as buttons, alerts, and modals. As we move into 2021, more complex components, like the datagrid, will become an area of focus for us. (Oh yeah, and these expansion packs are free because Clarity is open source, unlike expansions for Fortnite.)

We’ve also provided many improvements and new capabilities not found in Clarity Angular — most notably the design tokens and layouts. We have found that using Core’s design tokens and layouts can easily remove the majority of the custom CSS applications have to write to supplement Clarity Angular and provide more standardization across an application. Think of it like an upgrade game engine under the hood of your application that makes everything smoother.

You may have noticed we’ll have two independent implementations of Clarity, if so you can get some bonus points. The long term goal is to deprecate our existing Clarity Angular component library and support only Clarity Core. This will only happen long after reaching parity between both libraries, which we expect to take more than a year to achieve.

You can depend upon Clarity Angular for the years to come, as long as it suits your needs. With our upcoming v5 release, we will also feature freeze Clarity Angular and focus on accessibility and bug fixes. This will help stabilize Clarity Angular for the long term, and it means we have no breaking changes planned in the future. We will update for major Angular releases as needed, just like all your phone games update regularly to support the latest iOS or Android. Just like if you can still play a Nintendo 64 but you don’t see new games being developed, Clarity Angular will continue to be reliable for your application for the years to come as long as you need it.

Now, let’s try adopting some Clarity Core components inside of an existing Clarity Angular application!

Cheater’s Guide for using Clarity Core in Angular

For new applications, adopting Clarity Core is as simple as following our documentation at https://clarity.design/storybook/core/. We’re working to incorporate this documentation into our main website early next year. You’ll be able to update Clarity Core as new releases come to get the latest enhancements and components.

For existing applications using Clarity Angular, you have the opportunity to adopt Clarity Core as you go instead of having to worry about a major and complex migration process. As we release Clarity Core components, applications can choose when and how they update their usage from Clarity Angular to Clarity Core.

This is beneficial for applications because using Clarity Core is not tied to Angular, and can work with any recent version. This avoids the pain of updating Angular and Clarity Angular to adopt updates.

To help illustrate how to get started, here is a simple Angular project that uses an alert, button, badge, and modal. Now we’ll step through how to update it to use the web components in Clarity Core.

Before: Stackblitz Demo
After: Stackblitz Demo

Step 1 — Activate Clarity Core in your project

First, you’ll need to install Clarity Core, which is done by using NPM or Yarn:

npm install @cds/core #If you use NPM
yarn add @cds/core #If you use Yarn

This installs Core into your project, but it won’t have any impact until you try to incorporate a component into your project. With Clarity v5, you’ll get this installed by default with Angular projects.

Right now, you’ll also have to add the CUSTOM_ELEMENTS_SCHEMA to your NgModule schemas so the Angular compiler doesn’t get upset. We are working on a solution that won’t require this step for v5

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
// ...the rest of your module definition
})

Step 2 — Replace a component

Let’s start by replacing the label component. The relevant code snippet for this component is below, which is a simple HTML/CSS element in Clarity Angular.

<span class="label label-danger">Danger Tag</span>

In Clarity Core, the label component has been renamed to a tag, because labels are a semantic HTML element for forms and we want to avoid confusion. You can see the tag documentation for the details about the component. We will need to register the Core component so it is available to use, by adding the bolded line below to the Angular module file imports list.

import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from "@angular/core";
// Other imports

import "@cds/core/tag/register";

@NgModule({
// Rest of your NgModule definition

This is necessary to do once per Angular module within which you wish to use the Core component. Alternately, you can do this globally at the AppModule level. This import makes the browser aware of the Core component and is similar to adding a component to the NgModule declarations array.

Now that our tag is ready to use, we can replace our span snippet above with the following tag component.

<cds-tag status="danger">Danger Tag</cds-tag>

That’s it! We’ve adopted a Clarity Core component to replace an existing Clarity Angular component with minimal effort. You may notice a change in colors, which improves the accessibility of the tags for color contrast requirements.

Step 3 — Achievement unlocked!

That is all you have to do to begin using Clarity Core in your Angular projects. During step 3, you can bask in the glory of obtaining your new achievement badge.

Now it's your turn! Can you try to replace the alert component with a Core version? Remember you have to first register the Angular component and then replace the components in the template. I’ll go play some arcade games while you try it out.

Did you get it? First, register the alert in your module like this.

import "@cds/core/alert/register";

Then replace the alert component in the template like this and you’ve got it!

<cds-alert-group status="info">
    <cds-alert>This is an info alert!</cds-alert>
</cds-alert-group>

I really like the cleaner API that Clarity Core components have over the original Clarity Angular API. The APIs are simpler and have a consistency that makes the components more intuitive. I hope you also find it to be an improvement, as we’ve spent a lot of time considering the API carefully.

The last two components are the button and modals, and the steps are the same basic steps. First, add the imports to the module file.

import "@cds/core/button/register";
import "@cds/core/modal/register";

Then we have our template to update for the button and modal. The structure of the Core modal is more complex due to the header, content, and footer, but it also has a more consistent and clean API.

<p><cds-button (click)="getImage()">See Random XKCD Comic</cds-button></p>
<cds-modal *ngIf="comic" (closeChange)="comic = null" size="lg">
  <cds-modal-header>
    <h3 class="modal-title">{{comic?.safe_title}}</h3>
  </cds-modal-header>
  <cds-modal-content>
    <img [src]="comic?.img" [alt]="comic?.alt" />
  </cds-modal-content>
  <cds-modal-actions>
    <cds-button (click)="comic = null">Close</cds-button>
  </cds-modal-actions>
</cds-modal>

The final version of this demo is in this Stackblitz example. That is it, we’ve managed to replace the Clarity Angular components with Clarity Core with minimal effort, and could even remove the ClarityModule from the project!

Is Core in beta, should I wait?

Clarity Core is considered stable and ready to use! We have worked hard to build out the foundational platform so future enhancements will come to you with minimal friction. Better yet, you don’t have to camp outside of a store to get access to it. Clarity Core is already in use with some of our high profile products at VMware.

Hopefully, using Clarity Core is pretty straightforward and makes sense for you. However, if not, why bother changing? Glad you asked! It might not be obvious why you will want to do this.

1. Clarity Core components will be eligible for future enhancements. The more you use them, the easier it will be to get new features such as search input, input groups, and circular progress that are only available in Core.
2. Clarity Core components are often more flexible and customizable than their Angular counterparts.
3. Clarity Core components have a more consistent API, better theming support, accessibility improvements, and work in any frontend framework.

I recommend that you consider using Clarity Core components for all new work in your project when possible. As you update or enhance parts of your application you can update any uses of Clarity Angular that you see. It will take a while for Clarity Core to get full parity with Clarity Angular, but there is no reason you can’t start to adopt today where you can!

Got some cheat codes?

While the steps above are pretty straightforward and simple, it is not something that you will want to do for every single component that you are using today. The good news is we can automate some of these tasks for you. (It might be as easy as pressing up, up, down, down, left, right, left, right, B, A and Start.)

First, we’re building out an adoption guide that will show before and after examples like these for all of our components. We plan to launch the initial version of this guide in early 2021. This will be a useful tool for anyone looking to see quick comparisons between implementations.

Second, we’ve been building out ESLint rules to help detect usage of Clarity Angular components. This will help you find the places in your application where you are using a Clarity Angular component and help identify Clarity Core adoption opportunities. Since this uses ESLint, it will work with any frontend project framework since some teams use other frameworks with our CSS components. Details about how to use this will come out with v5.

Finally, we’re going to work on adding fixers to those ESLint rules that can automatically update your code. Given the complexity of some components, we don’t expect to be able to make them for every component or to be able to auto-fix every use, but we do expect it to make a huge impact on adopting Clarity Core components. It will be opt-in to use the fixers when you are ready, so you can choose when to run it in your project.

Nothing is perfect, and we know you might run into a few challenges along the way. Some existing implementations might be fairly complex and require more work to use Clarity Core, or you might have some customizations on Clarity Angular that would have to be redone. That is why we don’t want to automatically change everything for you, so it doesn’t create unexpected side effects that make your life painful.

Reach the bonus levels of Core

How else can you begin to adopt Clarity Core?

• You can begin to use Clarity Core components in new work for your application.
• You can use Clarity Core in any legacy aspects of your application that aren’t running on Angular.
• You can prototype new ideas using Clarity Core components.
• You can use the new Design Tokens for creating Layouts, Color, Spacing, and Typography, which are one of the most understated features of Clarity Core as it can greatly reduce having to write your own CSS for these common tasks.

There are no limits to when and how you can adopt Clarity Core inside of your projects. You’ll be able to level up your application consistently as more components are released.

So what’s next?

We will deliver on the v5 release and the initial vision for adoption support early next year. However, v5 beta is available today! You can download it using npm install @cds/core@next to add it to your project. You can read the current documentation on Clarity Core.

Let us know how it goes from our GitHub project at https://github.com/vmware/clarity and open issues for problems you face or give us feedback in our new discussions area.

Keep an eye out for more details coming soon about how we’re going to help you adopt Clarity Core!

Level Up Your Application by Adopting Clarity Core was originally published in Clarity Design System on Medium, where people are continuing the conversation by highlighting and responding to this story.

Design Systems serve as a foundation for consistent and accessible user interfaces. Components within a design system can also serve as a foundation for the performance of a UI. With Clarity Core, our Web Component library, we wanted to ensure we kept components lightweight to continue a high standard of performance as we develop new components.

Creating fast user interfaces on the Web is no easy challenge. The same challenges apply to any UI component library. With the development of Clarity Core, we identified the following key concepts to help keep Clarity’s performance on track.

• Dependency Management
• Modern build targets
• Tree shaking (Components, Icons, CSS)
• Bundling and CDNs
• Rendering
• Measuring and Automation

Dependency Management

Excessive JavaScript is one of the largest contributors to slow Web applications today. With Clarity Core, we take careful consideration when using an external dependency.

• Can this be accomplished with something existing in the Web platform today?
• Is this utility tree-shakable and side effect free?
• Can we guarantee it does not change the public API of our components?
• Is the kbs cost worth the value?

Clarity Core uses only a few critical dependencies such as lit-element to make it easy to build and maintain Web Components.

The direct dependencies are all internal in Core and not exposed in any public API. By keeping dependencies internal, we can help ensure long term stability with the component APIs. The optionalDependencies allow applications to choose if a particular dependency needs to be installed. Keeping polyfills an optionalDependency teams can conditionally load them as needed for their target browser support.

Modern Build Targets

For Clarity Core, we ship the latest es2015+ JavaScript code. Core does not ship ES5 or UMD style bundles. This choice is for maintainability and performance. By shipping modern JavaScript as the default, we can significantly reduce the amount of code sent to the client. By providing a modern JavaScript source, applications start with the lightest option and can optionally downgrade to ES5 for older browser support. This strategy gets us the broadest amount of tooling support in the JavaScript ecosystem.

For applications that need to target ES5 browsers, the code can be consumed and transpiled with Babel or TypeScript. Many framework tools like the Angular CLI have this ability built right in.

To learn more about the details of packaging Web Components, I highly recommend these two articles:

• https://open-wc.org/publishing/
• https://justinfagnani.com/2019/11/01/how-to-publish-web-components-to-npm/

Tree Shaking Web Components

Tree shaking is a concept where a build process removes unused code from a final build output. When using a comprehensive design system like Clarity, you may only use a subset of its components. When this happens, we want only the used components end up in your final output shipped to the client. Removing or tree shaking this unused code can significantly improve the startup time of an application.

To promote tree shaking, we have organized Core to have multiple entry points. Multiple entry points mean there is more than one starting location to import from in a package. Example, a single entry point library may look like the following:

In many cases, this works; however, if we split this into smaller entry points, we can help promote patterns that will improve tree-shaking.

Each component has its own entry point enforcing a hard and clear boundary between components. This boundary helps prevent accidental bundling situations since the components are not referred to in the same entry point file.

If there is code we need to share between component boundaries, we move it to our internal @clr/core/internal package. This entry point allows us to safely share internal code between component boundaries and encourage code de-duplication at build time.

Side Effects

Many libraries and even some applications will have a sideEffects key defined within their package.json.

This flag signals bundlers like Webpack and Rollup only to keep code that is exported and used within other modules. This optimization can further reduce the overall bundle size of your applications. However, JavaScript modules natively support side effects. So what is a side effect? A side effect is produced whenever a piece of JavaScript code executes and changes state outside of the executed function. Let’s take a look at this example:

This file, we have a variable statement, a console log, and two exported functions. With the sideEffects: false flag a bundler will bundle the add() and sub() functions if used in another module. However, the console log and variable will be removed from the final build output. The log and variable are side-effects or code that do work outside the scope of being statically exported.

With side effects set to false, the bundlers must assume the default JavaScript behavior and include everything in the file/module. That means if you only use the add() function in your application, the bundler will still include sub().

With our Web Components, we want the optimal performance, but there is a bit of a wrinkle in our sideEffects: false plan. We have to register our components to the custom elements registry to use the in the DOM. The act of registering a component is a side effect, so if we use sideEffects: false in them, our components will never be registered.

So how do we get around this? We move the side effects into a single register.js file.

By moving the side effect of registering our Web Component, we allow the rest of the library to be fully tree shakable and side effect free. We can tell bundlers that we have only one specific side effect file in our package.json.

Now, as a user of Clarity, you can import the registration statement to use the component and still get advanced tree shaking capabilities.

Tree Shaking Icons

With Clarity Core, we have extensive strategies in place to ensure your final build only includes the components that you use. We can take it one step further and tree shake at the symbol level.

A symbol is anything imported through an import statement. Most build tools like Webpack and Rollup rely on import statements to safely determine what code can or should not be bundled.

By relying on this behavior, we can improve our icons API to promote tree shaking. With almost 500 icons, we want only the icons you use to make it to the final application build. Including all icons would cause users to download hundreds of kb of embedded SVG in your application. By supporting tree shaking at the icon level, performance can improve as less JavaScript is needed to be parsed on application startup.

By leaning on the side effect free behavior we discussed earlier, a bundler can safely assume only the ClarityIcons service and two icons are used. This explicit import of the icons used within your application allows Webpack or Rollup to safely drop the other 400+ icons from the final production bundle saving hundreds of kbs of JavaScript from having to be sent to the client.

You can start using Core Icons today within your existing applications, even if you currently use the @clr/icons package.

Bundles and CDNs

Along with shipping modern, side effect free JavaScript, we do not bundle or minify the source code. This may seem counter-intuitive at first but bundling and minification are application concerns. These optimizations work better at application-level tooling as these tools can understand all dependencies of the entire application.

Bundling code at the library level can cause dependencies to become difficult to tree shake or de-duplicate in the final build. By keeping everything as plain modern ESM, most bundlers can better optimize your usage of library code.

By not bundling, we also open the door for the first time to support build-less versions of Clarity. When we keep the source unbundled, we can use native ES modules via a CDN. Using native ESM, the browser can natively load only the modules required with no bundler or build step.

Prototyping with Clarity has never been easier with CDN support. Check out https://skypack.dev/ or https://unpkg.com/ for more details on ESM support.

Global and Utility CSS

Another significant performance improvement with Clarity Core is our global CSS payload size. Component CSS is inlined within the component. This means that, if you use the button component, the button component CSS is included within the JavaScript. This allows us to significantly reduce the amount of global CSS needed.

To use the global CSS in Clarity Core, you can import the global file.

The global stylesheet provides a basic Clarity specific reset, CSS Custom Variables, layout utilities, and typography utilities. Together these total to a final bundled, minified, and compressed output of ~7kb.

If you only want a subset of these utilities, you can import them directly instead of importing the single global bundle. This lets you pick and choose what you need — resulting in even smaller bundles. We do, however, recommend including the normalize and reset styles at a minimum.

Our layout and typography utilities cover many use cases. This causes the initial global CSS bundle to come in around 177kb uncompressed and unminified. But the repetitive nature of the utility selectors allows us to leverage text compression behavior.

Compression tools like Gzip and Brotli heavily optimize for repetitive text. Because of this behavior, we compile our utility CSS in an order that places similar selectors next to each other in the final output. This enables a 177kb CSS file to be ~7kb with minification and Brotli compression or 10kb with Gzip compression.

With some tweaks to our CSS output, we can shrink our CSS significantly with text compression. But even though we have a small network payload, we still are sending a lot of potentially unused CSS.

Tree Shaking CSS

The provided global CSS utilities are also used internally within our Web Components. The Core CSS utilities are extensive and we may only use a small subset of the utilities provided within any given component. We can optimize for this by ensuring only the utilities we use are bundled within our Web Components.

For this, we use a tool called Purge CSS that ensures we only bundle CSS utilities which are used within the component. We run Purge CSS as part of the build process and it tree shakes our CSS within our internal templates.

For example, if our button only uses a couple of the CSS utilities, we don’t want the 7kb+ of CSS bundled with it nor bundled multiple times for each component. By running Purge CSS, we can check what is used within our component templates and strip out any unused CSS. Here is a snippet demonstrating how we tree shake the CSS in our components.

By tree shaking the CSS used internally by Core components, we further drive down the bundle sizes. While we use Purge CSS at the library level, you can also use it on your applications to reduce your CSS payload. The less CSS that is sent down the wire, the faster the browser can start rendering the page.

Rendering

With our components using Shadow DOM, we can guarantee a certain amount of containment with CSS layout and behavior. External styles don’t leak into our component, and our component styles don’t leak to the global scope. With this behavior, we can optimize the browser rendering by using the CSS contain property.

Using the contain property, we tell the browser this element is self-contained and can optimize when to render and re-render it. This can significantly reduce render times on the page as the browser can skip layout recalculations. To dig into this topic, check out the Google Developer Docs on CSS Contain.

Now that we have identified all the different strategies to keep Core running at optimal performance, how do we stay on track and prevent performance regressions?

Measure and Automate

We run a check against our final build output for final payload sizes with each build in our CI process. We use bundle-size, which can check what our final file sizes are compressed.

The bundle-size tool takes a config with maximum sizes for given files. If a file exceeds that size, then the build will fail. This helps catch mistakes that would cause unexpected size increases or issues that would break tree shaking.

Here is a sample of what our config looks like:

We have a small Webpack build that runs against a single JavaScript file to catch tree shaking regressions.

This simple file will allow us to test that Webpack can successfully import our two components and icon without bundling any other components or icons. This tests that we are successfully tree shaking at the component level and symbol import level.

We benchmark our bundle sizes against Brotli Compression rather than gzip. Brotli is a modern compression format and provides significant improvements over gzip. Most web services and CDNs now support Brotli automatically and it is widely supported in browsers.

Results

With all these optimizations in place, we can create a hello world Clarity app consisting of only 17kb of JavaScript and 8kb of CSS with a basic Webpack build. This demo app includes two components: the badge and icon component and two icon shapes. The CSS is our standard global bundle and the normalize.css package.

While this is lightweight, we can do more. We are only using a fraction of the CSS utilities in this simple demo. Using Rollup, we can push the performance even further in our application with just a few adjustments.

With Rollup, we can provide a couple of lit-element specific optimizations for our application build. This includes dropping polyfills and minifying our templates.

With both component and icon tree shaking, we can use the Source Map Explorer tool to verify we are only loading the code we use and our dependencies in our final bundle.

Using PurgeCSS, we can tree shake our unused Global CSS. This pulls our hello world Clarity app down to around 1kb of compressed CSS and around 15kb of compressed JavaScript! While simple, this demo demonstrates the optimizations made possible by component, icon, and CSS tree shaking.

With such a light payload, we get an initial render of around 1 second on a simulated 3g connection. Take time to check out the running demo application and the source code. You can find more demos in various frameworks in the Clarity Core repository on Github.

Design System Performance with Clarity Core Web Components was originally published in Clarity Design System on Medium, where people are continuing the conversation by highlighting and responding to this story.

Clarity v4: How Clarity expanded and improved

Clarity has a history of growing and becoming more diverse with each major release. Clarity v4 is no exception, as we have continued to iterate and enhance the ability to build accessible enterprise products!

Clarity Core, improved by 14 form components

Late last year, Clarity promised to move towards a framework-independent design system based on web components. We’ve honored that promise by creating 14 new components for the web, which we call Clarity Core.

After working with hundreds of real world scenarios utilizing Clarity Core, we were faced with the reality of the foundational need for forms to be integrated into any application that supports a rich interactive experience between users and data. The result was 14 new components that help build your own customizable forms.

Read more about implementing clear and concise forms that have strong response rates, using several of our new form controls such as:

• Input groups
• Time picker
• Search input
• File input
• And others!

Added support for React

React is by far the most popular framework among Clarity users. We recognized this when we acknowledged one of the most frequently requested features was React wrappers. Our community is important to us, so we dedicated a large slice of v4 to React wrappers in order to support more people and more teams building more products.

We enhanced the developer experience by adding the @clr/react library of React wrappers to support React applications.

React can work with web components, but typically it requires a bit of work on the applications to integrate them correctly. Our library provides a lightweight integration that bypasses the work for developers to integrate. To learn more please view the Core React Documentation.

Added combobox to Angular

Clarity Angular is built to work with the popular Angular framework, and we remain committed to supporting a great developer experience in Angular.

Combobox

One of the most frequently requested components that came from our community was the combobox. After careful auditing for accessibility, we created a highly useable and customizable combobox. Additional documentation can get you started in using this new component.

Beyond Combobox, we’ve had a number of other improvements, fixes, and enhancements that you can read about in our v4 release notes.

Getting started with v4

Angular

If you are using the awesome Angular CLI, it is the easiest way to update your application and use Clarity v4.

ng update @clr/angular

You can also upgrade manually with NPM or Yarn:

npm install @clr/angular @clr/icons @clr/ui

yarn upgrade @clr/angular @clr/icons @clr/ui

Core

To upgrade to the latest version of Core, use one of the following commands for NPM or Yarn.

npm update @clr/core

yarn upgrade @clr/core

Need help?

Inevitably, we all need help from time to time. Clarity recognizes that and we have a lot of different avenues to make sure your experience using Clarity is frictionless.

• Start a discussion on Github Discussions (a new support channel!)
• Reach out on Twitter (@VMwareClarity)
• Report bugs using GitHub Issues

Additionally, when determining if there is a usage question or an issue with one of the components, we recommend isolating the use case and identifying the steps that demonstrate the problem encountered. To that end, we provide versioned StackBlitz applications that will help both with determining if there is a question or an issue as well as giving us code that we can use to triage and investigate.

What’s next?

Clarity is far from being finished, we constantly iterate and improve. We have a lot of work ahead of us. What we have identified on our roadmap looks like this:

• Refreshed and enhanced website. We have been working hard on a refresh of our website. We’ve changed the design, updated and expanding our content, and are adding more demos and samples for everyone to use.
• More web components. Our next round of web components are underway, such as: Accordion, Vertical Nav and Dropdowns.
• Alignment between Angular and Core. We’re working on how to bring the API and behaviors of our existing Angular components in line with the API and behaviors of the Core component, which will help standardize Clarity across frameworks and also support future enhancements.
• Migration and update support. For applications already using Clarity Angular, we are already working on improving our tooling and automation to better support automatic updates for projects during major release cycles for minimal disruption.

In closing

As an open source project, Clarity values the community that makes us whole. The community engagement we receive is what helps us align with your needs while we continue to grow our offerings. Don’t see something on our product roadmap that you’re looking for? Lets us know.

QuadriClarity — The Clarity v4 Release was originally published in Clarity Design System on Medium, where people are continuing the conversation by highlighting and responding to this story.

1. Event Binding: One-way data binding, in which information is sent from a component’s template to the component’s class
2. @HostListener: Angular decorator that handles events on the host element of a component or directive

As we covered these methods, we learned how much they simplify the process of listening to DOM events while also providing many other nifty little features. However, a common aspect of these two methods is that they are both completely tied to their template or host element, which creates certain limitations. In this post, we will go over what those limitations are and how we can use Angular’s Renderer2.listen method to resolve them as well as many other cases where you can put it into use.

What is Renderer2 in Angular?

As Angular is a multi-platform framework, it offers secure and easy-to-use tools that manage and abstract away differences across browsers and platforms. One of those tools is Renderer2, which is an Angular’s built-in service that provides APIs for interacting with and manipulating DOM elements.

As different environments such as web browsers, web-workers, and server-side rendering have different implementations of DOM, these Renderer2 APIs are built to manage those differences and yield consistent results. Note that Renderer2 not only facilitates manipulating HTML elements, but also the types of XML, SVG, etc. To learn more about the intricacies of Renderer2, I recommend taking a closer look at its source code.

Angular Renderer2.listen vs Element.addEventListener

Let’s recall how we add and remove event listeners using native DOM APIs. If we want to listen to a mousemove event on some native DOM element and invoke its callback function, onMouseMove, we would call the .addEventListener in the following way:

nativeElement.addEventListener("mousemove", onMouseMove);

To remove this event listener, we need to call .removeEventListener on the same button element with the exact same matching parameters:

nativeElement.removeEventListener("mousemove", onMouseMove);

But it’s very easy to blunder when you try to match event listeners for removal. Properly removing an event listener that is added manually is crucial as it prevents memory leaks as well as performance drag on your application.

With Renderer2.listen, it becomes much easier to clean up event listeners. Take a look at its API pattern:

Renderer2.listen(target: any, eventName: string, callback: (event: any) =>  boolean | void ): () => void;

You can see that Renderer2.listen method itself returns another method with the type of () => void. That returned method is used for removing the event listener. This is much simpler than trying to match event listeners for removal. Just save the returned method’s reference to a variable or property, and call that whenever you need to remove the listener. Let’s see how this would play out in a simple example:

In the example above, I am trying to listen to the mousemove event on document. So I’ve imported Renderer2 into my component first and then added the mousemove event listener todocument through Renderer2.listen in theOnInit cycle.

Note that when I add the event listener, I’m saving the returned method to the unlistener property which will be called later to remove the event listener in the OnDestroy cycle, which gets called when the component gets destroyed.

Another important thing to note here is that I’ve passed document not as an object, but as a string. If we pass document as an object, we will see the following error when we try to run our app in a server-side environment:

ERROR ReferenceError: document is not defined

This is because there are no global objects such as window or document in environments other than web browsers. We could resolve this issue by checking what environment this code is running in. But with Renderer2.listen, we can simply pass either string "document" or "window" and let Angular do the checking for us and adapt to the environment that it’s running in.

Angular Renderer2.listen vs Event Binding

Let’s see an example where you want to create Drag and Drop functionality using generic mousedown, mousemoveand mouseup events. This example below accomplishes just that through template event binding:

The main idea here is that dragging should start with a mousedown event on the draggable element. Only after that first mousedown should we start responding to the mousemove event(s) on the document, as the element could be dragged anywhere on the document. To make sure mousedown is registered first, we check if the draggableEl property is defined in the mousemove event’s handler. On themouseup event, we reset the whole process by simply assigning null to the draggableEl property.

As you can see in the demo above, the code looks extremely simple… but there are some serious issues that we need to fix. For one, we’ve added three active event listeners on the draggable element that will always be listening until the target element gets removed from the DOM. To make matters worse, we are listening to mousemove and mouseup events globally because they are defined on document. So we are continuously listening and trying to respond to all mousemove and mouseup events on the entire app — and it doesn’t end there! Every time these events fire, they also trigger Angular’s change detection throughout all components and directives, which could cause significant performance deterioration.

The first step to solve the above-mentioned problems is to add the mousemove and the mouseup event listeners inside themousedown event listener’s handler. However, we cannot accomplish that with event bindings as they are inlined to their template elements permanently. In the case of using @HostListener, we would still face the same problem.

Hence, we need to use Renderer2.listen which allows us to dynamically add and remove listeners when only certain conditions are met. In our case, we need to add the mousemove and the mouseup event listeners to document only when the mousedown event is registered on the draggable element. In the example below, I’ve demonstrated how to do that using Renderer2.listen:

The code is a bit more involved compared to what we saw with the event binding example. Here, the important thing to pay attention to is how we are adding and removing event listeners. Now we have only one active listener on the draggable element instead of three as the event listeners on mousemove and mouseup are nested inside the mousedown event listener’s handler. And you can also see that the event listeners on mousemove and mouseup are removed when the mouseup event fires.

But we have to address another issue I’ve briefly mentioned earlier: every time one of these mousedown, mousemove, and mouseup events fire, Angular change detection would also run. Remember that Angular change detection runs through all components and directives in the following three cases:

• When event listeners respond to their target DOM events
• When setTimeout() or setInterval() executes
• When ajax requests respond

This is especially concerning as we are dealing with an event such as mousemove that fires on each pixel movement you make with your mouse. So Angular change detection might be unnecessarily triggered thousands of times. Fortunately, Angular lets us run our code outside of its change detection zone.

What we need to do is to make use of NgZone, which is a service that lets you run your code inside or outside of the Angular zone. To run our code outside of the Angular zone, we need to use the following API pattern:

NgZone.runOutsideAngular<T>(fn: (...args: any[]) => T): T

We also need to be careful while using the API above because any data binding changes made outside of the Angular zone will not take effect unless you are directly manipulating the DOM. In the case of our Drag and Drop example, we could add mousemove event listener outside of the Angular zone:

As you can see, I’ve placed themousemove event listener entirely inside this.ngZone.runOutsideAngular‘s callback method to prevent change detection from running. But for the mousedown event, change detection would still run when the event fires as this.ngZone.runOutsideAngular is used inside its handler. That’s an important difference to keep in mind. This is the reason why we cannot suppress change detection if we add event listeners through Event Binding or @HostListener methods. Hence, if you need to listen to events that fire frequently many times such mousemove, touchmove, or scroll, consider using Renderer2.listen with this.ngZone.runOutsideAngular.

Bonus tip:

Another cool feature Renderer2.listen offers is that you can listen to DOM events and also listen to Angular Pseudo Events. That means you could do this:

Renderer2.listen(nativeElement, "keyup.enter", event => { ... })

Renderer2.listen(nativeElement, "keydown.esc", event => { ... })

Renderer2.listen(nativeElement, "keyup.arrowup", event => { ... })

Renderer2.listen(nativeElement, "keyup.arrowdown", event => { ... })

If you want to learn more about Angular Pseudo Events, please refer to this article.

Let’s recap — Key Takeaways:

• Renderer2 is Angular’s built-in service that provides APIs for interacting with and manipulating DOM elements. Manipulating DOM elements through Renderer2 yields consistent results across different web browsers as well as environments.
• With Renderer2.listen, it becomes much easier to clean up event listeners. You no longer need to match event listeners for removal.
• Unlike Event Binding or @HostListener methods, with Renderer2.listen, you can manage complex event listeners by adding and removing them on specific conditions.
• You can leverage Renderer2.listen together with NgZone.runOutsideAngular to suppress Angular change detection.

Stay tuned for the next blog post of this series, which will be on RxJS and how we could use it to listen to DOM events in Angular app.

Four ways of listening to DOM events in Angular (Part 3: Renderer2.listen) was originally published in Clarity Design System on Medium, where people are continuing the conversation by highlighting and responding to this story.

Clarity turned three and just released 3.0

Omne trium perfectum translated into English means the rule of three, which roughly means that everything that comes in threes is whole and complete. True to that rule, the Clarity Design System has released one of its biggest updates to date with more new features in this release than v1 & 2 combined; with new components, enhancements, accessibility improvements and the initial set of elements for our framework independent Clarity Core initiative.

The focus of this release was to deepen our commitment to accessibility and usability in the enhancement of our most utilized components Datagrid and Form Controls, while officially launching Clarity Core.

Clarity’s top 3 new component enhancements:

The Detail Pane
The Datagrid has a new pattern for viewing details of a specific record, called the Detail Pane. This is our recommended way to show more complex details over the existing expandable rows feature, because it provides more space for your content, has stronger accessibility semantics, and has a better overall user experience.

Datalist Form Control
Browsers natively support the HTML Datalist form control, which is a lightweight way to create an input field that has autocomplete from a list of options. While the Combobox is still in the works, the Datalist component can meet many of the typical autocomplete form control needs.

Range slider
In addition to the Datalist, we’ve also create a new range slider form control to allow you to easily define a slider control to set a value between two numbers. Not all browsers support a range slider, and those that do have a very different visual appearance, but Clarity’s range slider works in all browsers and is visually consistent with the rest of our form controls, a big task for a small component.

There’s much more in this release, like our volume 17 icons, making Aria live service public, Angular 9 integration and more; check out the full release here.

Introducing Clarity web components library
We introduced our Clarity Core initiative last year, and v3 marks the first beta release. We’ve built 6 fundamental elements that will be used to build other more complex components so that non-Angular frameworks can be aligned with Clarity in a highly efficient, streamlined integration. More details on the Clarity Core initiative here.

We’re working hard to bring parity to all our components regardless of your framework, that is fully accessible, open source and enterprise ready. If you are using a framework other than Angular to build your applications, try out the Clarity Core preview and help us build the elements you need by contributing! For anyone using Angular, you won’t need to work with Clarity Core at this time. Learn more about the release here.

New Design and Accessibility Improvements

Clarity continues to improve by addressing usability and improving design tools available. We’ve worked hard to minimize disruptions to align the UI and expected behaviors to ensure smoother upgrades.

Updated HSL color system
We’ve aligned our color palette to use HSL instead of HEX codes, so that the color progression in a particular color series is based on the same hue. This change also makes it easier to calculate compatible colors. Color variables are provided to easily use the color options.

Updated over 100 accessibility tickets
In the past 6 months, we solved over 100 accessibility needs that help every Clarity consumer meet quality accessibility WCAG 2.1 compliance requirements, while saving months of time, generally a 25% savings in accessibility remediation. Clarity is proud to be fully accessible with minor exceptions we are prioritizing.

Published a new VPAT
Review our updated VPAT for v2.2+ with minor exceptions, we expect to publish a VPAT for v3 soon in the same location as well.

How to update to Clarity v3

We’ve updated Clarity v3 to work with the recent Angular 9 release. We’ll continue to release according to our release strategy; all new features and enhancements will be available in v3+, and v1 and v2 will continue to be supported with bugfixes. To update, you can follow the basic steps below.

1. First, update to Angular 9. Ensure that all of your other dependencies are also able to update to Angular 9, and follow the Angular update guide.

2. Second, update Clarity. Use the Angular CLI update tooling to update Clarity and run any migration scripts. ng update @clr/angular@latest

3. Finally, review your application for breaking changes in Clarity. You can view the full list on our release notes.

As only the major update versions have breaking changes, you can expect to update to any patch or minor release within the v3 timeline.

What’s next

Now that v3 is out, we’re working on our next major milestone. We expect to remain on the same release cadence to follow shortly after the next Angular release. We plan to focus on three key areas for v4.

1. Clarity Website — We are improving the clarity and depth of our documentation, the structure of the site’s navigation, enhancing the quality and consistency of the demos, and insuring a scalable structure for the future.

2. Form Improvements — In addition to the form improvements in v3, we plan to work on additional enhancements. We’re improving and expanding support for more complex form layouts to help our enterprise customers complex needs and introduce additional form controls to allow for greater scalability for the majority of our customers use cases.

3. Clarity Core expansion— Our Clarity Core initiative will bring more foundational details to our framework independent future. The design and layout tokens will allow you to create custom application layouts and will be usable with just CSS/HTML. More details to come.

We’d love to hear from you, follow us on twitter and reach out to help us know what’s working well and what we can improve. Thanks for reading and being a part of the Clarity community helping to contribute and scale the most accessible, enterprise ready, open source design system available!

Clarity 3.0: Good things come in 3's was originally published in Clarity Design System on Medium, where people are continuing the conversation by highlighting and responding to this story.

Two weeks ago, we announced the work we’ve been doing behind the scenes to build Clarity Core, a framework-independent design system based on web components. At a high level, these are our five key goals and drivers:

• Clarity is user-focused. Its design patterns are and will continue to be driven by our users.
• Clarity is committed to accessibility and inclusive design.
• Clarity is enterprise-ready and we think that raises the bar for usability.
• Clarity has always been and is committed to remaining open source.
• A big part of Clarity’s future will involve framework independence.

My colleagues have already written about our commitment to accessibility and the efforts to which we have gone as a team to build an inclusive library of components. Today we will address that last bullet point — framework independence.

What is framework independence?

A front-end framework is (generally speaking) code written by an outside group or organization that ships with a web application. A framework typically handles the following features:

• Routing: switching “pages” of the application without taking you to a new page
• Data-binding: when you change information in one place it shows up correctly in another
• State management: maintaining consistency of data so that everything remains as expected when you go from one page to another

Frameworks can do more than this, surely, but that’s the gist of what they do. And there are hundreds of them.

For the past decade, the front-end development community has been at the center of a veritable tempest of JavaScript frameworks. The most popular frameworks in use today are React, Angular, Ember, and Vue. And the landscape has been fairly rocky over the past 9 years, leading many to distrust that the current status quo will remain such for very long. That last part is called “framework fatigue” or sometimes “javascript fatigue”.

In the early days, Clarity rallied around Angular as a way to materialize our design system in a library complex, data-bound components and bring our product teams at VMware together on a common tech stack. This was a huge success for us as we saw the vast majority of products at VMware choosing Angular and Clarity to build their applications.

The good news is that we will continue to support and drive Angular adoption across the company. But the better news is that our patterns, services, and components will now be available to teams who rely on Vue, React, Ember, Elm, or any other framework.

We feel strongly that the future of all viable component libraries is framework independence and our plan is to deliver on this belief.

How are we going to do this?

Our plan is to deliver a core set of web components in an npm package we are calling Clarity Core. In addition to these components, the Clarity Core library will contain helpers, mixins, services, and utilities that are generally useful across Clarity Angular, Clarity Core, and Clarity Icons.

Clarity Core will become a foundational piece of the existing Angular library we have because Clarity Angular will reuse its services and components.

Why web components?

At this point in time, web components are a mature web standard. They are available in almost every modern browser and support can be polyfilled back to browsers that lack support.

We know that custom elements can work across all the browsers we support and that this is the right time to embrace them as a foundation for the Clarity Design System.

How will this affect the Angular library?

Clarity Core will not affect consumers of the Clarity Angular at all. Even when Clarity Core components and services are used as a foundational piece of the Clarity Angular library, the teams who rely on Clarity Angular will not know or need to know that it is there.

The goal is to make this as minimally impactful to existing Clarity Angular applications as possible.

An Angular application should not know or care whether a Clarity component is written 100% in Angular or is built on top of a Clarity Core component.

Additionally, Clarity will always rely on frameworks to do what they do best because it would be counter-productive for us to try and rebuild a framework inside of a library of web components. Our #1 framework at VMware is Angular, so we are committed in the long-term to supporting and growing Clarity Angular.

I’ve had a hard time with web components in React. How does this help me?

For the last few months, members of the Clarity team have been doing a deep dive into integrating web components with React applications. At the end of our journey, we identified an architecture of “React wrappers”. We’ve reviewed this architecture with some of VMware’s best React developers to make sure we had their stamp of approval before moving forward.

How are you building this?

The Clarity team put a lot of effort into researching the best path forward for this library. In the end, we identified three key attributes that we wanted to preserve:

• The architecture of the Clarity Core components library would be familiar enough that contributors with experience working with Clarity Angular could contribute to Clarity Core without a steep learning curve.
• The APIs of the current Angular components would transfer as closely as possible to help manage situations where a current Angular component would be moving to the web component library.
• The code underneath would adhere as closely as possible to emerging web standards as we continue to bet on web standards for the future.

After several explorations into a variety of possibilities, we arrived at five foundations for the Clarity Core architecture. Note that the following is a deeper dive into the technical aspects of Clarity Core. If that’s not something that interests you, please jump forward to the next question.

1. Typescript

Typescript is a super-set of Javascript. It is a combination of a type-checker and transpiler. If you are writing Angular code, you are no doubt already familiar with its benefits. Carrying this forward into the Clarity Core component library is fundamental to the goal of the codebase remaining familiar to developers who have been working on Clarity Angular in the past.

2. Custom Properties

CSS Custom Properties are the future and this is one big bet we are making on web standards. Custom properties already work in all major browsers.

Additionally, custom properties are the most direct way to enable theming in a library of ShadowDOM encapsulated web components.

3. Lit Element

Lit element is an incredibly solid and light foundation upon which to build a library of web components. Lit is maintained by the Polymer team at Google and our esteem for this library has grown the more we have worked with it.

Besides being a very lightweight dependency, Lit follows web standards — which was important to us because we believe web standards are the future. It also feels great to have your sole, major dependency be such a thin layer above the code running in the browser itself.

Lit is more than syntactic sugar, but one would be excused for viewing it as a convenient base class and nothing more. The simplicity and transparency of Lit also support our desire to keep the architecture as easy to work with as possible.

4. Minimally Stateful

In our research, we wanted to make sure that Clarity Core components would be easy to use for product teams working in Angular or React. For extra credit, we also dove into Vue and a couple of other frameworks. We did hit a minor speed bump, however.

Angular’s views and change detection cycle are just different enough from React’s Flux architecture and Virtual DOM that the way a developer works in one framework may not necessarily follow in the other framework.

Sure, Angular developers have NgRx and can use that for state management combined with advanced (or some would say proper) use of RxJS to implement the Flux architecture in their Angular applications. But we do not have the luxury of only supporting one implementation of the Angular application architecture.

It also became clear early on that the current Clarity Angular library of components offers functionality tied to Angular. This constituted functionality that it would make no sense for us to replicate in a library of web components.

To be more specific, we are talking about features in Angular like reactive forms, routing, and two-way binding. While most frameworks have their own spin on these features, it became clear that most frameworks weren’t always in alignment on the details. In the end, we found there was no one ideal solution.

Our team now jokingly refers to the task of building frameworks-within-frameworks as “Frankenstein Angular” and have decided against re-building “framework features” into a framework-agnostic library of components.

Instead, we decided the best path forward was to adopt a strategy of being “minimally stateful”.

There are some features of a component that it would be tiresome to have to turn on and off from your application. Being “minimally stateful” means we will handle those tasks for you, track them for you, and communicate any changes so you can keep your application’s state current if you need to.

But we also concluded that any features of a component that an application developer might reasonably want to circumvent should be driven and managed by the application’s state — not from within the component.

As a consequence, a datagrid in Clarity Core won’t manage large chunks of data like the datagrid in Clarity Angular does. Likewise, a wizard in Clarity Core won’t be managing the state of its pages and the user’s ability to navigate them in the same way either.

While this may be a little surprising for developers used to monolithic, black-box components that gobble up hundreds of lines of JSON configurations, we feel confident that this will ultimately be liberating for application developers because it puts a level of customization in their hands that other libraries cannot match.

It also lowers the requirements for developers to invest in learning a component library API — especially one that may run counter to their framework of choice.

5. Reduce Through Reuse

Ultimately, Clarity Core will be a refinement of the vision that resulted in the current library of Angular components.

The intent with this new initiative is not to duplicate the effort with an unrelated library that requires separate support, maintenance, and its own entire team. The real value of Clarity Core, for us, is in what we can abstract and reuse.

There are going to be some components in Clarity Angular that will always be built on top of Angular–even if they have a replicate in Clarity Core. But many, if not most, components in our Angular library will become wrappers for Clarity Core components. This will help our team differentiate between framework-driven features and core features of the components we deliver.

How do we get there?

We have a lot of work ahead of us and some effort towards fixing up the current Clarity architecture to allow for a new library of web components.

Presently, our roadmap to web components looks something like this:

CSS Custom Properties–3.0 release (Nov-Dec 2019)

Refactoring Clarity to use CSS Custom Properties is a big task — and one we completed just this month! We started by proving that we could use custom properties in all our supported browsers and reliably use them across the Shadow DOM.

The implementation involved cleaning up some technical debt in our SASS/CSS and then a significant chore of creating all the CSS Custom Properties. In addition, we handled the delivery in a way that isn’t a huge breaking change for teams that don’t need to theme their applications or prefer to use the SASS-based theming we support today through 3.0.

But to fully realize the benefits of the web components in Clarity Core, we have to deprecate SASS-based theming in 3.0. This means, starting in 4.0, CSS Custom Properties will be the only way to theme Clarity applications.

Move Clarity Icons to Core–3.0 release (Nov-Dec 2019)

The Clarity Icons migration is our first proving ground for the Lit-based architecture and a fundamental effort towards delivering our set of essential components.

Foundational Components–Q1 2020

Following the icons migration, we will see more foundational components entering the fray.

By “foundational components”, I mean components upon which more complex components depend. We cannot, for example, have an “icon button” without icons–or buttons.

Strategic Components–2020

After we complete our foundational components, we plan to move on to “strategic components” through the remainder of 2020. This phase two of component delivery will not constitute all of the components in Clarity Angular today but it will be a good number of them.

When designating something as a strategic component, we are looking for components that satisfy one of three criteria:

1. Components that fill an immediate need with a component that non-Angular teams interested in using Clarity do not have access to today…
2. Components that augment the Clarity Angular library with components that the library currently doesn’t have, and…
3. High-value components that are not easily replicated using the HTML and CSS Clarity currently offers.

This may mean that we don’t jump right into forms. Maybe we focus on something like the datepicker. Or the wizard.

It all depends on the intersection of need, value, and availability.

Contribution Guidelines–Nov 2019

Our contribution guidelines will be released early on during our work on the “foundational components”. By nature, these components will be simpler in implementation. There will be a lot of “low hanging fruit” componentry that we will not be tackling right out of the gate as we focus on foundational components and more complex, strategic components. This makes this a fertile ground for external contributions and, if you’re looking to contribute, keep an eye out for those contribution guidelines!

React Wrappers (2019 on…)

Lastly, the foundational component work will introduce our library of “react wrappers” for Clarity Core. So keep an eye on those for a preview of how we plan to support React teams with Clarity Core.

In Closing

When it comes to components geared towards building websites and web applications, we feel the future of the web is framework independence. That doesn’t mean frameworks go away.

But it does mean that component libraries that rely on a framework for their delivery will become less useful.

As one of the founders of Clarity, I can say that this team has always bet on the web. Whether it was ES2015/ES6, CSS3, SVG, or HTML5, we unanimously believed the best path forward was adopting web standards.

We have proven that the time is right for web components and we feel confident that the time is right for Clarity Core.

Please keep an eye on our github repository as work on Clarity Core progresses! And keep an eye on this RFC for more details and discussion on the architecture of Clarity’s next leap forward.

Clarity Core was originally published in Clarity Design System on Medium, where people are continuing the conversation by highlighting and responding to this story.