Get started with Clarity Design System

Project Clarity is an open source design system that brings together UX guidelines, an HTML/CSS framework, and Angular components. Clarity is for both designers and developers.

Clarity’s designs stem from continuous exploration and research. These designs are built into our HTML/CSS components, which can be used any web UI, regardless of the underlying JavaScript framework. Clarity also offers a set of well-designed and implemented data-bound components built on top of Angular, one of the most popular JavaScript frameworks in the industry.

How to Use Clarity

We offer three approaches for utilizing Clarity: just the UX guidelines, UX guidelines and our HTML/CSS framework, or put everything together with our Angular implementation.

Using Clarity Design Resources

Jumpstart your project with one of our Sketch or Figma-based design resources. Start by downloading the Metropolis fonts. Then download your resources of choice. We recommend that with your UI Library selection, that you also select the matching Icon Library as the two work together.

Primary Font

Metropolis (R8)

Figma Libraries

UI Library - Light ({{sketchVersion}}) UI Library - Dark ({{sketchVersion}}) Icon Library ({{sketchVersion}}) Color Library ({{sketchVersion}})

Sketch Libraries

UI Library - Light ({{sketchVersion}}) UI Library - Dark ({{sketchVersion}}) Icon Library ({{sketchVersion}})

HTML/CSS Framework

If you just want to use our HTML/CSS implementations, you need to get the latest code from NPM and then add the assets to your project.

You'll need to include one of the files found at node_modules/@clr/ui/clr-ui.min.css for the normal theme or node_modules/@clr/ui/clr-ui-dark.min.css for the dark theme into your build tooling.

You can also load this CSS file from a CDN like you see below. See unpkg.com for more details.

Angular Option 1: Installing using Angular CLI (Recommended)

For any Angular application, which uses the CLI v6 or greater, we recommend using the ng add feature of the CLI to install Clarity for you. This works regardless if you have a brand new application, or one that you've been working on for some time, just as long as you have Angular 6 setup.

We highly recommend that all Angular projects use the CLI, because we'll also work on supporting migration features which will make it easier to keep Clarity and Angular up to date.

  1. Generate a new Angular application (if you haven't already):
  2. Navigate to the directory:
  3. Run the ng add command for Clarity:

If you are using the Angular CLI with multiple projects, you can specify which project to add Clarity to by using the --project PROJECTNAME flag.

Angular Option 2: Manually adding Clarity to an Angular project

You can build an Angular app, then install Clarity onto your project.

Step 1: Build an Angular App

Create a new Angular application, if you need a quickstart use the 5 Min Quickstart.

Step 2: Install Clarity packages

Clarity is published as three separate packages on NPM, as well as one dependency.

Install them all by running the following command with NPM.

Step 3: Adding scripts and styles

If you are using the Angular CLI, you need to add the angular.json file.

Find the scripts and styles arrays and add the following:

If you are not using the CLI, you'll need to add the files listed above to your build tooling or you could also put them in the head of the index.html file like:

Step 4: Add Clarity to Angular application

Import the ClarityModule into your Angular application's module. Some features also depend upon the BrowserAnimationsModule, so you should add it as well. Your application's main module might look like this:

Step 5: Run Your App

Step 6: Update Clarity

In order to keep up with Clarity, you can use ng update to automatically update Clarity to the latest version in your Angular project. This will also run any migration schematics, which can update code for you or warn you about changes in Clarity that affect your application. It usually helps to update Angular first, then Clarity.

If you want to update to a prerelease version, you can do so by running:

Device and Browser Support

Device and Browser Support

* - Note that Clarity only supports the latest two versions of the listed browsers, with the exception of Internet Explorer.

Contributing to Clarity

The Clarity team welcomes contributions from the community. See our contribution guidelines on GitHub.

Reporting an Issue

Ongoing work and feature requests are tracked using GitHub Issues. Please feel free to file an issue.

When submitting issues please provide a minimal app that demonstrates the issue by forking one of the Clarity Stackblitz projects. Since it depends on your issue starting with the correct Clarity version and theme will help us deliver support. You can find all of the StackBlitz templates here.

StackOverflow

Ask questions on StackOverflow with the vmware-clarity tag to get the community's attention faster. You can also view FAQs by filtering on the vmware-clarity tag on StackOverflow.

Attributions

See the legal attributions for third party software included in Clarity.

This is a spacer to force sidenav highlighting on scroll