Themes help you customize the look and feel of your application.

Establish your brand with Clarity

Color Theming
Match a company or client’s unique brand identity with color theming at many different levels of granularity allowing for customization at an application or component level.
Clarity Icons API
Font customization and the Clarity Icons API offer the power to reinforce identity at the most fundamental levels of user experience.
Theme information density
Depending on users’ expectations, different applications may require different degrees of information density. Clarity themes can be adjusted to make an application as sparse or compact as it needs to be.

Default Themes

Clarity offers two default themes — light and dark. These themes can be used without modification to optimize user experience or they can be used as a guideline for creating custom themes in Clarity.

Light Theme
Light Theme
Light theme is Clarity’s default. It is best suited to content-rich applications where users will be working with the application in well-lit conditions for brief periods of time throughout the day. Light theme can help prevent eye strain in applications where a user is expected to read a large amount of content — like documentation or a blog.
Dark Theme
Dark Theme
Dark theme is best suited for applications that are content-sparse, yet highly interactive. A dark theme can help with eye strain if a user works with an application over a long span of time but in a way that requires focus but not a great amount of reading.

Theme Guidelines

Themes offer a great deal of flexibility — which can be both a good and bad thing. The Clarity team has put continued effort towards accessibility and the intentional use of color so that our end users can add great value to their products with minimal investment.

But theming can put some of those benefits at risk. Please review the following guidelines before building a custom theme.

Use color responsibly

Use colors that reinforce your brand but in a way that is pleasing.

Save saturated or bright colors in your palette for highlights. And use them sparingly to highlight actions or content.

Harsh colors can cause eye strain for users over time. Avoid using too many bright, neon colors and avoid using highly saturated/bold colors as backgrounds over large areas of content.

Do use brand colors in a pleasing manner
Do

Use brand colors in a pleasing manner, saving bold or saturated colors for highlights or calls to action.

Communicate with color

Consider using color to communicate meaning to users. Using colors like red for warning or danger and green for success or preferred actions reinforces your user experience.

Don't use brand colors irrespective of what the color communicates to users.
Don't

Use brand colors irrespective of what the color communicates to users.

Create visual hierarchy

Darker colors recede while lighter and brighter colors push forward. Be mindful of this when working with brand colors to create a custom theme.

Use light and dark colors to reinforce visual hierarchy and draw users’ 
                                focus.
Do

Use light and dark colors to reinforce visual hierarchy and draw users’ focus.

Don't draw attention to the wrong items with the use of color.
Don't

Draw attention to the wrong items with the use of color. In this example, the content of the cards and datagrid recede into the background while the sidenav and header unnecessarily draw the user’s attention.

Avoid extreme color combinations

Avoid extreme light-on-dark and dark-on-light color combinations that could contribute to eye strain.

Don't Use color combinations that may cause eye-strain.
Don't

Use color combinations that may cause eye-strain.

Be Accessible

Clarity’s color palette is WCAG AA compliant, meaning all color combinations of text-on-background meet the standard for color accessiblity for our users. Use the WebAIM Color Contrast Checker tool to test text and background colors when deciding how a brand’s color palette will be used in an application.

All of the text/background combinations on the Clarity Color Palette page are tested for WCAG AA compliance.

Code & Examples

Clarity UI ships with two css files, clr-ui.min.css for the light theme and clr-ui-dark.min.css for the dark theme. You can consume either one of these files and have a fully light or dark-themed Clarity application as part of typical build process. If you already use clr-ui in your project there is nothing to do. If you want to switch over to the dark theme use one of the examples below to modify your build process and consume the clr-ui-dark.min.css code.

Angular CLI Builds

Consume the dark theme code in clr-ui-dark.min.css by adding it to your styles array in the .angular-cli.json file.

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

Webpack Builds

Modify your webpack.config.js entry styles to consume the new clr-ui-dark.min.css

"entry": {
    "main": [
      "./src/main.ts"
    ],
    "styles": [
      "./node_modules/@clr/icons/clr-icons.min.css",
      "./node_modules/@clr/ui/clr-ui-dark.min.css",
      "./src/styles.css"
    ]
  },

Custom Themes

If you need to customize components for you application we suggest starting with either the light theme or the dark theme and override variables from there to suite your customizations.

In order to customize the Clarity light theme you will need to build with the Clarity SCSS and overwrite the SCSS variables that set the look-n-feel for each component you need to customize. You will need to build your applications CSS output with Clarity's SCSS.

Remove Clarity CSS from your build configuration

First, since we are going to be creating custom component styles the first step is to remove all of the Clarity css from your build process.

"styles": [
      ...
      "./node_modules/@clr/icons/clr-icons.min.css",
      ...
  ]
Add (or modify) your applications main.scss file

Next, we need to include the Clarity dependencies and component styles. This example shows one way of adding the Clarity dependencies and component styles based on standard npm installation into a node_modules directory of the project. In this example the styles.scss file lives at the top of a standard angular-cli application src folder.

// Clarity Dependency SCSS
@import "../node_modules/@clr/ui/src/utils/dependencies.clarity"; // Includes light theme

// Clarity Component SCSS
@import "../node_modules/@clr/ui/src/utils/components.clarity";
Add a custom theme file

Finally, sandwich your custom theme file between the Clarity dependency SCSS and the Clarity component SCSS. It will hold the values you choose to overwrite as you customize your theme. In this example the styles.scss file lives at the top of a standard angular-cli application src folder.

// Clarity Dependency SCSS
@import "../node_modules/@clr/ui/src/utils/dependencies.clarity"; // Includes light theme

// Your Application Theme File
@import "./theme.scss";

// Clarity Component SCSS
@import "../node_modules/@clr/ui/src/utils/components.clarity";