Get started with Clarity Design System

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

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@2.0.0/clr-ui.min.css" />

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.

• @cds/core. The library of web components and foundational pieces also used in Angular components.
• @clr/ui. Contains the static styles for building HTML components.
• @clr/angular. Contains the Angular components. This package depends on @clr/ui for styles.

Install them all by running the following command with NPM.

npm install @cds/core @clr/angular @clr/ui --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/ui/clr-ui.min.css",
      ... any other styles
]

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">

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

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.