Level Up Your Application by Adopting Clarity Core
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 YarnThis 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 importsimport "@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.
- 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.
- Clarity Core components are often more flexible and customizable than their Angular counterparts.
- 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!
