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: UX, UX and UI, and Angular.

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.

Starting With a Clarity Seed Project (Recommended)

For a new project, the best approach is to clone the Clarity seed project and modify it to fit your needs. The seed project is integrated with @clr/ui and @clr/angular, so you don’t need to install Clarity separately.

1. Clone the seed app:

   git clone https://github.com/vmware/clarity-seed.git

2. Install the dependencies:

   npm install

3. Run the seed app:

   npm start

Using an Angular Seed 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:
   • https://github.com/angular/angular-cli
   • https://github.com/mgechev/angular2-seed
   • https://github.com/angular/angular2-seed
   • https://github.com/AngularClass/angular2-webpack-starter

Step 2: Install Clarity

Clarity is published as three separate packages on NPM:

• @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.

Step 2a: Install Clarity Icons

1. Install the Clarity Icons library through npm:

   npm install @clr/icons --save

2. Install the polyfill for Custom Elements:

   npm install @webcomponents/custom-elements@1.0.0 --save

3. Load the library in your app by including clr-icons.min.css and clr-icons.min.js. Also, make sure to include custom-elements.min.js, the Custom Elements polyfill before clr-icons.min.js:

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

   Visit the Clarity Icons section for more installation information.

Step 2b: Install Clarity UI

1. Install Clarity UI package through npm:

   npm install @clr/ui --save

2. Include clr-ui.min.css in your HTML file:

   <link rel="stylesheet" href="path/to/node_modules/@clr/ui/clr-ui.min.css">

   If your site is built with angular-cli you can achieve the above by adding the file to the styles array in angular-cli.json:

   "styles": [
         ...
         "../node_modules/@clr/ui/clr-ui.min.css",
         ...
     ]

3. Write your HTML with the Clarity CSS class names and markup.

Step 2c: Install Clarity Angular

1. If you haven't already, complete steps 1 and 2 for installing Clarity UI in the preceding section.
2. Install the @clr/angular package through npm:

   npm install @clr/angular --save

3. Import the ClarityModule into your Angular application's module. Your application's main module might look like this:

   import { NgModule } from "@angular/core";
   import { BrowserModule } from "@angular/platform-browser";
   import { ClarityModule } from "@clr/angular";
   import { AppComponent } from "./app.component";
   
   @NgModule({
       imports: [
           BrowserModule,
           ClarityModule,
           ...
        ],
        declarations: [ AppComponent ],
        bootstrap: [ AppComponent ]
   })
   export class AppModule {    }

Step 3: Run Your App

npm start

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:

• Clarity v11: Dark Theme
• Clarity v11: Light Theme
• Clarity v10: Dark Theme
• Clarity v10: Light Theme

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.