Customizing the look and feel

All the style rules of the frontend are bundled in two .css files which are included in the Curity Identity Server. Try not to override any of those files as it might be harder to follow future updates. Instead you should create your own custom-theme and include it in the templates by using the settings.vm file.

How to create your custom theme

In order to create your own custom-theme, follow the steps below:

  1. Duplicate the file $INSTALLATION_HOME/misc/ui-builder/src/curity/scss/curity-theme.scss (for example to $INSTALLATION_HOME/misc/ui-builder/src/curity/scss/custom-theme.scss)
  2. Add the $INSTALLATION_HOME/misc/ui-builder/src/curity/scss/curity-theme.scss to the scss files array in $INSTALLATION_HOME/misc/ui-builder/config.js
  3. Start the previewer (see Using the UI Builder), so that the custom-theme.css file is created under $INSTALLATION_HOME/misc/ui-builder/build/curity/webroot/css
  4. Change the values of the variables defined in the copied file to ones that fit your needs

The next step would be to include the custom-theme.css file that you previously created in the templates. In order achieve that:

  1. Copy the $INSTALLATION_HOME/misc/ui-builder/src/curity/templates/core/settings.vm file under $INSTALLATION_HOME/misc/ui-builder/src/curity/templates/overrides/
  2. Uncomment the row referring to the loaded theme (search for $theme_css_path) and change curity-theme.css to custom-theme.css
  3. Restart the previewer (this will force the previewer to include the newly copied in the $INSTALLATION_HOME/misc/ui-builder/build folder)

You can now continue editing the custom-theme.scss file and the changes will be reloaded on the previewer without the need for restart. Avoid changing other .scss other than the custom-theme.scss when possible. You can add your CSS overrides at the end of the file which will take precedence over any rules in main.css

Danger

Never override csp.vm with an empty file or one that substantially reduces the policies defined by that core template. Doing so will likely result is severe security vulnerabilities.

How to work with Sass

The Curity UI Kit themes is written in Sass (.scss). Sass is a mature, stable, and powerful CSS extension language. You can quickly modify a theme using variables for colors, white space, media queries, authenticator brand colors and more.

Curity UI Kit is using Dart Sass, the primary implementation of Sass, which means it gets new features before any other implementation. It’s fast, easy to install, and it compiles to pure JavaScript which makes it easy to integrate into modern web development workflows. Find out more or help out with its development on GitHub.

Theme variables

On the top of the theme file you see different Sass variables that can be changed. For example, change the primary brand color using the $primary variable.

Media Queries

To work with responsive themes there are predefined breakpoint variables. Curity UI Kit uses a mobile first strategy using min-width media queries.

1
2
3
4
5
6
7
$breakpoint-sm: '(min-width: 40em)' !default;
$breakpoint-md: '(min-width: 52em)' !default;
$breakpoint-lg: '(min-width: 64em)' !default;
$breakpoint-xlg: '(min-width: 74em)' !default;
$breakpoint-xxlg: '(min-width: 84em)' !default;
$breakpoint-xxxlg: '(min-width: 114em)' !default;
...

Colors and Settings

There are a number of color variables that you can modify to quickly change the theme. Accent colors for states like hover, Call to Action colors, link colors and more.

1
2
3
4
$primary: #626c87 !default;
$primary-accent-color: #D859A1 !default;
$call-to-action-success: #57C75C !default;
...

You can also define custom colors for the avaliable authenticators.

1
2
3
4
$authenticator-twitter-color: #1da1f2;
$authenticator-dropbox-color: #007ee5;
$authenticator-slack-color: #6ecadc;
...

To use colored authenticator colors using #set ($single_color_authenticator_chooser = false). If set to true the $primary color variable will be used. If set to false the authenticator color variables will be used. An example below:

../../_images/authenticator-colors.jpg

Light and Dark Mode

../../_images/ui-kit-skins.jpg

There are two built in modes - dark and light. This is controlled in the template settings using the two variables #set ($body_background = 'body-light') and #set ($login_form_background = 'form-light'). The CSS supports both modes without recompilation.

You can also override the CSS classes and write your own styles. At the bottom you see some empty class definitions, modify this to fit your needs.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
// Light body background class.
.body-light {

}

// Dark body background class
.body-dark {

}

// Form background-color light.
.form-light {

}

// Form background-color transparent.
.form-transparent {

}

Note

The Curity components must be imported after the variable declarations. They are imported in the default theme using @import "curity-application";

Using External Fonts

If you want to use hosted web fonts via for example Google Fonts, Typekit or similar services you need to extend this using Content Security Policy (CSP). CSP is an added layer of security that helps to detect and mitigate certain types of attacks, including Cross Site Scripting (XSS) and data injection attacks.

Copy $INSTALLATION_HOME/misc/ui-builder/src/curity/templates/core/fragments/csp.vm to our overridden template or template area area in $INSTALLATION_HOME/misc/ui-builder/src/curity/templates/template-areas/my-company/fragments/csp.vm

Then to allow, for example, Google Fonts, change accordingly:

1
#set ($styleSrc = "style-src 'self' https://fonts.googleapis.com 'unsafe-inline' ${nonceScriptSrc};")
1
<meta http-equiv="Content-Security-Policy" content="connect-src 'self'; font-src 'self' https://fonts.gstatic.com; $childSrc">

In your custom theme ${INSTALLATION_HOME}/misc/ui-builder/src/curity/scss/custom-theme.scss:

1
2
3
4
5
@import url('https://fonts.googleapis.com/css?family=Calistoga&display=swap');

body {
  font-family: 'Calistoga', serif;
}

Compiling Sass to CSS

In package.json there are npm scripts ready to run and build the themes.

1
2
3
4
5
6
7
{
  "scripts": {
    "clean": "gulp clean",
    "start": "gulp serve",
    "build": "gulp"
  }
}
  • Use npm start to start the development server. Live reload is included and the browser will reload and instantly reflect your changes, both for Sass and html changes.
  • Use npm run build to compile Sass to CSS.
  • Use npm run clean to remove the build folder with the compiled assets.

How to work with the settings file

The settings.vm file under $INSTALLATION_HOME/misc/ui-builder/src/curity/templates/core has as a sole purpose to help developers modify the basic parameters of the templates with ease. Each possible setting contains the default value which, if needed, can be overridden.

As a first step, copy the settings.vm file from core to overrides (or your specific template-area). Then, for each of the settings you want to override, uncomment its line and change the value at will.

An overview of the possible variables and their default values can be found below:

  • main_css_path default: /assets/css/main.css
  • theme_css_path default: /assets/css/curity-theme.css
  • body_background default: body-light
  • login_form_background default: form-light
  • logo_path default: /assets/images/curity-logo.svg
  • logo_white_path default: /assets/images/curity-logo-white.svg
  • powered_by default: true
  • single_color_authenticator_chooser default: true
  • icons_only_authenticator_chooser default: false
  • show_symbol default: true
  • page_symbol_path default: /assets/images/
  • page_symbol_path_* default: /assets/images/<symbol-name>.svg

A detailed explanation of each variable can be found in the comments before its declaration.

Warning

Overriding settings.vm is safe, but altering settings-default.vm (in overides, template-area or anywhere else) is not recommended. Also, try not to remove the line #parse("settings-defaults") from settings.vm. Doing so might cause problems in future updates.