API documentation

# Customer UI theming

You can customize the appearance of self-service pages to match your brand identity using CSS custom properties (variables). These cascade from brand tokens to Bootstrap components.

# Quick start

To get started with a basic brand theme, define these core variables in your custom CSS:

:root {
  /* Primary brand color */
  --iteras-primary-color: #0891b2;
  --iteras-primary-color-rgb: 8, 145, 178;
  --iteras-primary-hover-color: #0e7490;

  /* Page background */
  --iteras-page-background: #f0f9ff;

  /* Typography */
  --iteras-font-family: 'Inter', sans-serif;
  --iteras-font-family-heading: 'Sora', sans-serif;

  /* Border radius */
  --iteras-border-radius: 0;
  --iteras-border-radius-sm: 0;
  --iteras-border-radius-lg: 0;
  --iteras-border-radius-pill: 0;

  /* Icon background */
  --iteras-icon-background: rgba(8, 145, 178, 0.1);
}

# Variable reference

Here's the full list of CSS variables you can customize. You don't need to set all of them — the defaults work well for most cases. Start with the core variables and adjust others as needed.

# Core brand variables (required)

These are the essential variables that define your brand's look. You should set all of these:

Variable Description Example
--iteras-primary-color Main brand color for buttons, links, and accents #0891b2
--iteras-primary-color-rgb RGB values for use with rgba() opacity effects 8, 145, 178
--iteras-primary-hover-color Primary color hover/active state #0e7490
--iteras-page-background Page background color #f0f9ff
--iteras-font-family Body text font stack 'Inter', sans-serif
--iteras-font-family-heading Heading font stack 'Sora', sans-serif
--iteras-border-radius Default border radius for components 8px or 0
--iteras-border-radius-sm Small border radius 6px
--iteras-border-radius-lg Large border radius 12px
--iteras-border-radius-pill Pill-shaped border radius 9999px
--iteras-icon-background Icon container background (typically 10% of primary) rgba(8, 145, 178, 0.1)

# Text colors

Control the color of body text and secondary text. The defaults work well for most brands:

Variable Default Description
--iteras-body-color #212529 Body text color
--iteras-secondary-color #6c757d Muted/secondary text color

# Neutral palette

These neutral colors are used for backgrounds, borders, and UI chrome. Override them if you need a warmer or cooler gray palette:

Variable Default Description
--iteras-color-white #ffffff White color
--iteras-color-dark #171717 Near-black color for text and dark elements
--iteras-color-light #e9ecef Light gray for backgrounds
--iteras-color-light-hover #d3d6d9 Light gray hover state
--iteras-color-light-active #c4c8cc Light gray active state
--iteras-border-color #ced4da Default border color for inputs and components

Links inherit from your primary color by default. You can override these if you want links to look different from buttons:

Variable Default Description
--iteras-link-color var(--iteras-primary-color) Link text color
--iteras-link-hover-color var(--iteras-primary-hover-color) Link hover color
--iteras-link-decoration none Link underline (none or underline)

# Form input variables

Fine-tune the appearance of form inputs and labels:

Variable Default Description
--iteras-input-height 38px Default input height
--iteras-input-border-color #ced4da Input border color
--iteras-input-background #ffffff Input background color
--iteras-input-focus-border-color var(--iteras-primary-color) Input border color when focused
--iteras-label-color var(--iteras-body-color) Form label color
--iteras-label-font-weight 500 Form label font weight

# Button variables

Primary buttons use your primary color automatically. These variables control secondary buttons:

Variable Default Description
--iteras-button-secondary-bg var(--iteras-color-light) Secondary button background
--iteras-button-secondary-color #171717 Secondary button text color
--iteras-button-secondary-border #ced4da Secondary button border color

# Card variables

Cards are the main content containers. You can customize their background, borders, and headers:

Variable Default Description
--iteras-card-background #ffffff Card background color
--iteras-card-border-color rgba(0, 0, 0, 0.18) Card border color
--iteras-card-header-background #000000 Dark card header background
--iteras-card-image-background #eeeeee Placeholder background for card images
--iteras-section-border none Section divider border

# Semantic colors (shared)

These colors are the same across all brands to keep the user experience consistent. They are WCAG AA compliant (4.5:1 contrast ratio) for use on tinted alert backgrounds. Don't change these unless you have a good reason:

Variable Value Purpose
--iteras-success-color #0d7a3e Success states
--iteras-warning-color #a16207 Warning states
--iteras-danger-color #c41e1e Error/danger states
--iteras-info-color #1766a5 Info states

# Multi-brand support

If you have multiple brands (e.g., a media company with multiple publications), you can scope variables to CSS classes:

/* Brand A */
.brand-a {
  --iteras-primary-color: #059669;
  --iteras-primary-color-rgb: 5, 150, 105;
  --iteras-icon-background: rgba(5, 150, 105, 0.1);
}

/* Brand B */
.brand-b {
  --iteras-primary-color: #7c3aed;
  --iteras-primary-color-rgb: 124, 58, 237;
  --iteras-icon-background: rgba(124, 58, 237, 0.1);
}

Apply the brand class to the body element:

<body class="selfservice brand-a">
  <!-- Content inherits brand-a colors -->
</body>

# Theme examples

Here are two complete themes showing different design directions. Copy one as a starting point and adjust the colors to match your brand:

# Sharp corners (classic style) 

:root {
  --iteras-primary-color: #e07020;
  --iteras-primary-color-rgb: 224, 112, 32;
  --iteras-primary-hover-color: #c2610d;
  --iteras-page-background: #fef3e2;
  --iteras-font-family: 'Inter', sans-serif;
  --iteras-font-family-heading: 'Sora', sans-serif;
  --iteras-border-radius: 0;
  --iteras-border-radius-sm: 0;
  --iteras-border-radius-lg: 0;
  --iteras-border-radius-pill: 0;
  --iteras-icon-background: rgba(224, 112, 32, 0.1);
}

# Rounded corners (modern style) 

:root {
  --iteras-primary-color: #7c3aed;
  --iteras-primary-color-rgb: 124, 58, 237;
  --iteras-primary-hover-color: #6d28d9;
  --iteras-page-background: #f5f3ff;
  --iteras-font-family: 'Inter', sans-serif;
  --iteras-font-family-heading: 'Inter Tight', sans-serif;
  --iteras-border-radius: 12px;
  --iteras-border-radius-sm: 12px;
  --iteras-border-radius-lg: 16px;
  --iteras-border-radius-pill: 999px;
  --iteras-icon-background: rgba(124, 58, 237, 0.1);
}

# Common questions

# Why do I need both the hex color and the RGB values?

The hex color (--iteras-primary-color) is used directly for solid colors. The RGB values (--iteras-primary-color-rgb) are needed when we need to apply opacity, like for hover states or the icon background. CSS can't extract RGB values from a hex color, so you need to provide both.

# What if my brand uses multiple primary colors?

Pick one as your main primary color for buttons and interactive elements. You can use the other colors for accents by defining additional custom variables in your CSS.

# How do I load custom fonts?

Load your fonts using @font-face rules or a Google Fonts link in your CSS, then reference them in the font family variables. Make sure the fonts are loaded before the page renders to avoid flash of unstyled text.

← Paywall