Styles

Styles help you create and scale user-facing screens while adhering to your brand's guidelines. You can add your brand's logo, colors, and other design elements in a central location in the Descope UI. Any screens you create with the Screen Builder will take on the brand elements from Styles.

If your brand goes through updates, Styles also makes it easy to propagate those updates to all your user-facing screens.

In Descope, we offer the option to customize your user experience through the styles page. Those options consist of varying properties as the logo of your company, the fonts that the components will inherit, and much more. Those options are selections we predefine, and some are limited. Some Descopers want to take a step further and customize their user experience to a new extent, such as custom fonts and self-defined CSS stylings. This article will show you the basics of how to use Descope's gui/code mode on the styling page.

Creating A Style

Within a Descope Project, you can create as many styles as you want. Styles are applied to specific flows, via a parameter that's passed in via our web component and SDKs. In addition to this, Descoper will have an option to choose the styles in the flow runner and screen builder component of their flows.

This can also be controlled at an application level if using the Auth Hosting Application. Read more about this

There are many use cases for having multiple styles. One can be that users have different portals for the same application. Each of these portals require different styling and branding. Another could be in wanting to use the same flow across multiple OIDC/SAML Applications with custom application-specific styling.

For example, Portal A needs to just use primary colors vs Portal B which uses secondary colors. In such scenarios, Descoper can create multiple style definitions in a single project.

To create multiple styles, navigate to Styles in your console. A default style setting is chosen automatically. To create a new styles file, click on the drop down and select + New styles file.

Create a new file with a unique style name. This will auto-populate the style ID. Click on Add to create a new style file in your project.

You can now change/brand this new file based on your requirement by changing all/any component you'd like. More on how these components can be set is provided under the GUI and Code Mode section of the document. Based on the choice of Primary and Secondary colors, Descope creates rest of the palette for you.

You also have the option to delete certain styles if its no longer needed.

Styles Per Application

If you're using Descope as a federated IdP across multiple SSO applications, and wish to re-use the same flow with multiple different application-specific styles, you can do so by appending the style parameter to your Flow Hosting URL under your Application Configuration page.

If you're not using our Auth Hosting page, you'll need to extract this URL parameter manually and feed it into the web component like this.

GUI Mode

Descope has Styles divided into two tabs. Theme tab provides global styling option that affect the overall screens and individual components. With the Components tab, you can configure each component in detail.

Styling Themes

Under the Theme tab, we have three sections that we can customize according to our brand. Each of these sections are available for both Light and Dark themes.

Logo

You can upload your company's logo under this field with a simple drag and drop. Same goes for the dark theme option as well.

Colors

In this section, you can select your brand colors to match brand consistency. You have options of designing Primary, Secondary, Greys, Success and Error.

When you select a primary color for example, Descope will create the rest of the palette for you.

Typography

In this section, you can choose font families for all the text related components. You have a list of fonts available from the dropdown. Additionally, all the way at the top of the dropdown, Descope provides an option to add a custom font.

Each of the different sections like Headings, Subtitles, Body can be customized with different font, size and weight.

Custom Font

Each font family allows one custom font setting. To configure a custom font, click the + Add Font from the font dropdown, then provide a family name and a url to the hosted font file. Descope also allows editing the custom font after its been initially set.

Styling Components

Under the Components tab, you can set the buttons according to your branding in more detail. Every button/component has an editable action provided on the right side.

You can configure options for Font Family, Border Radius, Border Width, Text/Background color etc for your primary or secondary buttons. It also gives you a choice to add custom configurations.

For OAuth buttons, you can customize each button by provider name. Example: Here for provider Apple, you can customize the button accordingly or just leave it to default.

Once all the changes are made, you can click Apply and view your changes in preview mode by clicking the Preview button.

Code Mode

Enable code mode editor with a toggle button. Clicking the button will switch the styles page to code mode:

The styles page should look like this:

Note

Styles between light and dark theme will not persist, meaning each theme holds different values.

Best Practices

Most of the fields inside code mode are self explained by name, and can be tested right away in the flow builder. Some best practices and odd features are documented here:

Components

Badge: Is the styling of the component of the options you get inside a multi-select field:

Logo: Contains the values of the URL's for the company logo that will be used, including the fallback URL:

	"logo": {
      "--descope-logo-fallback-url": "url(https://imgs.descope.com/components/no-logo-placeholder.svg)",
      "--descope-logo-url": "https://static.descope.com/pages/P2XCa7FBmpm6zN1agE26uEImPpXo/v2-alpha/light/logo.png"
    }

TOTP Image: Holds the placeholder image for TOTP button

    "totpImage": {
      "--descope-totp-image-fallback-url": "url(https://imgs.descope.com/components/totp-placeholder.svg)"
    }

Required Attribute: If a component supports using the required boolean, the _required attribute will appear in code mode, stating which component will it use to indicate it:

	"_required": {
        "--descope-upload-file-required-indicator": "var(--descope-input-wrapper-required-indicator)"
	}

Notification Card: can alter the style of the notification toast you and other Descopers will get, also how different types of modes will be displayed, such as errors and success messages for actions performed in Descope:

	"mode": {
        "error": {
          "--descope-notification-card-background-color": "var(--descope-colors-error-main)",
          "--descope-notification-card-border-color": "var(--descope-colors-error-light)",
          "--descope-notification-card-text-color": "var(--descope-colors-error-contrast)"
        },
        "primary": {
          "--descope-notification-card-background-color": "var(--descope-colors-primary-main)",
          "--descope-notification-card-border-color": "var(--descope-colors-primary-light)",
          "--descope-notification-card-text-color": "var(--descope-colors-primary-contrast)"
        },
        "success": {
          "--descope-notification-card-background-color": "var(--descope-colors-success-main)",
          "--descope-notification-card-border-color": "var(--descope-colors-success-light)",
          "--descope-notification-card-text-color": "var(--descope-colors-success-contrast)"
        }
	},

Special Attributes: Some components hold styling states for states of the components. Altering the attributes listed below will change how the component will look in different states:

{
	"_checked": {
	...
	},
	"_disabled": {
	...
	},
	"_invalid": {
	...
	},
	"_readonly":{
	...
	},
	"_focused":{
	...
	},
	"_vertical":{
	...
	},
	"_fullWidth":{
 
	},
	"_loading":{
	...
	},
	"_square":{
	...
	},
	"_bordered":{
	...
	},
	"_hidden":{
	...
	},
	"_hideCursor":{
	...
	}
	// special for text component:
	"_italic":{
	...
	},
	"_lowercase":{
	...
	},
	"uppercase":{
	...
	}
}

Globals

Direction: Possible inputs: ltr / rtl - a global variable that will determine if your components will be Right To Left or Left To Right.
Fonts: You can add a url to both 'font1' and font2' to use a custom font, make sure you create a label that you will remember.

	"font1": {
        "family": [],
        "label": "Custom",
        "url": "https://MyCustomFont.Url/font"
	}

Typography: You can determine what component types will take which font.

	"body1": {
        "font": "var(--descope-fonts-font1-family)",
        "size": "14px",
        "weight": "500"
	}

npm i --save @descope/node-sdk

Import and initialize Management SDK

import DescopeClient from '@descope/node-sdk';
 
const managementKey = "xxxx"
 
try{
    //  baseUrl="<URL>" // When initializing the Descope clientyou can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__', managementKey: managementKey });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}
 
// Note that you can handle async operation failures and capture specific errors to customize errors.
//     An example can be found here: https://github.com/descope/node-sdk?tab=readme-ov-file#error-handling

Export Theme

Use the code below to export a theme:

import * as fs from 'fs';
 
// Args
//   None
 
const resp = await descopeClient.management.theme.export()
if (!resp.ok) {
  console.log(resp)
  console.log("Unable to export theme.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully exported theme.")
  console.log(resp.data)
  let data = JSON.stringify(resp.data, null, 2);
  fs.writeFile('theme.json', data, (err) => {
      if (err) throw err;
      console.log('Theme written to file');
  });
}

Import Theme

Use the code below to import a theme:

import * as fs from 'fs';
 
// Args
// theme (Theme): the theme to import. dict in the format
//    {"id": "", "cssTemplate": {} }
 
let data = fs.readFileSync('theme.json');
let jsonData = JSON.parse(data);
const theme = jsonData["theme"]
 
const resp = await descopeClient.management.theme.import(theme)
if (!resp.ok) {
  console.log(resp)
  console.log("Unable to import theme.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully imported theme.")
  console.log(resp.data)
}

Was this helpful?