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.

UX Guidelines: Using Clarity Design Resources

Jumpstart your project with one of our Sketch-based design resources. Start by downloading the Metropolis fonts . Then download your resource of choice.

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.

npm install @clr/ui --save

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.

<!-- Load the latest version -->
<link rel="stylesheet" href="https://unpkg.com/@clr/ui/clr-ui.min.css" />
<!-- Or load a specific version -->
<link rel="stylesheet" href="https://unpkg.com/@clr/ui@0.12.5/clr-ui.min.css" />

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):
    ng new my-app
  2. Navigate to the directory:
    cd my-app
  3. Run the ng add command for Clarity:
    ng add @clr/angular

If you are using the Angular CLI with multiple projects, you can specify which project to add Clarity to by using the --project PROJETNAME 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

  1. Look at the Angular documentation, starting with the 5 Min Quickstart.
  2. Save and modify the example structure and build, or use one of the Angular seeds:

Step 2: Install Clarity packages

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

  • @clr/icons. The library that provides the custom element icons.
  • @clr/ui. Contains the static styles for building HTML components.
  • @clr/angular. Contains the Angular components. This package depends on @clr/ui for styles.
  • @webcomponents/custom-elements. A polyfill for webcomponents for older browsers, which Clarity depends upon.

Install them all by running the following command with NPM.

npm install @clr/icons @clr/angular @clr/ui @webcomponents/custom-elements@1.0.0 --save

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:

"styles": [
      "../node_modules/@clr/icons/clr-icons.min.css",
      "../node_modules/@clr/ui/clr-ui.min.css",
      ... any other styles
],
"scripts": [
  ... any existing scripts
  "../node_modules/@webcomponents/custom-elements/custom-elements.min.js",
  "../node_modules/@clr/icons/clr-icons.min.js"
]

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:

<link rel="stylesheet" href="path/to/node_modules/@clr/ui/clr-ui.min.css">
<link rel="stylesheet" href="path/to/node_modules/@clr/icons/clr-icons.min.css">
<script src="path/to/node_modules/@webcomponents/custom-elements/custom-elements.min.js"></script>
<script src="path/to/node_modules/@clr/icons/clr-icons.min.js"></script>

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:

import { NgModule } from "@angular/core";
import { BrowserModule } from "@angular/platform-browser";
import { BrowserAnimationsModule } from "@angular/platform-browser/animations";
import { ClarityModule } from "@clr/angular";
import { AppComponent } from "./app.component";

@NgModule({
    imports: [
        BrowserModule,
        BrowserAnimationsModule,
        ClarityModule,
        ...
     ],
     declarations: [ AppComponent ],
     bootstrap: [ AppComponent ]
})
export class AppModule { }

Step 5: Run Your App

npm start

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.

ng update @angular/core
ng update @clr/angular

Device and Browser Support

Device and Browser Support

  • Internet Explorer 10 & 11
  • MS Edge
  • Latest versions of Chrome, Safari, and Firefox

* - 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:

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