UI Design

The UI Design screen lets you customise the visual appearance of your Airgentic chat widget by editing its stylesheet and icon files.

The File List

The Design screen lists all the files available to edit for your service:

Click any row or its pencil icon to open the file editor.

For Site Search, Airgentic also emits stable air-* classes plus common search and Bootstrap-style classes such as search-results, search-facet, nav-tabs, nav-item, card, pagination, and page-link. See Styling Site Search for search-specific selectors and examples.

If you need custom widget behaviour rather than visual styling, approved accounts can use External Script URLs. Review the security and support notes in that guide before adding JavaScript.

The Editor

Each file opens in a syntax-highlighted code editor with line numbers.

• CSS files — edited with CSS syntax highlighting. The style.css editor uses a split-screen layout: the code editor on the left and a live preview pinned on the right, so the preview stays in view as you scroll the code. Drag the divider between them to resize. As you type, unsaved CSS is applied to the preview only.
• SVG files — edited with XML syntax highlighting. A live preview of the SVG renders above the editor and updates as you type, so you can see your changes immediately without saving.

Inspect CSS variables in the preview

For style.css, turn on Inspect CSS variables above the preview, then hover a UI region. The tooltip shows the supported CSS variables for that part of the UI, the selector scope to paste them under, and a copyable starter snippet.

The inspector is a guide to the supported theme variables. It does not show every computed CSS property, and some artwork such as uploaded SVG icons may still need to be edited as files. For one-off changes that do not have a variable, use a scoped CSS selector in style.css.

Saving Changes

When you make a change, a red save bar appears at the bottom of the screen. Click Save Style to save (you will be asked to confirm before the file is written), or Cancel to discard your changes.

After saving, allow a few minutes for changes to propagate and appear on the live website.

Quick Start

If you only need brand colours on every surface, start here:

#air-widget {
  --air-brand: #0c4a6e;
  --air-header-background: #0c4a6e;
  --air-header-text: #ffffff;
  --air-chip-text: #0c4a6e;
}

That updates headers, welcome chips, and related accents across Service Hub, Hover Widget, and Inline Search in one place.

To style a single component everywhere:

.air-assistant-message {
  border-radius: 18px;
}

To style a component on one surface only (for example, the floating hover panel):

#air-widget[data-context="hover"] .air-assistant-message {
  width: min(92%, 520px);
}

Three rules to remember:

1. Use semantic class names like .air-assistant-message — not old suffixes like -hw or -sh.
2. Use #air-widget[data-context="..."] when you need surface-specific styling.
3. Put overrides in style.css — it loads last, so simple selectors usually win without !important.

How Styling Works

Airgentic loads styles in a predictable order. Your style.css is always the last customer-controlled layer, so simple overrides in the Design screen usually win without needing !important.

Styling layers

For the Hover Widget and Service Hub, Airgentic injects your style.css after the built-in widget CSS.

For Site Search, the load order is:

1. Built-in Airgentic search CSS
2. External search stylesheet, if configured in Search Configuration > Superuser
3. Your style.css (loaded last)

That means a rule like .hit-card { border-radius: 14px; } in style.css overrides both the built-in theme and an external migration stylesheet.

Where style.css applies

The same style.css file is shared across every surface for a service:

• Service Hub — embedded chat on a dedicated page
• Hover Widget — floating chat/search panel on your website
• Inline Site Search — full search page or per-slot search regions

When you need different styling on search vs hover, use #air-widget[data-context="..."] (see Styling by surface).

Why your overrides usually work

Built-in Airgentic theme rules use CSS :where(...) so they contribute zero extra specificity. Your style.css loads after the built-in CSS. Together, that means a plain rule like .air-widget-title { background: #0c4a6e; } normally overrides the default theme without !important.

The Styling Contract

Airgentic uses a small, stable set of hooks for customer CSS. Think of it as two axes:

Optional modifiers on the same root element:

Widget root markup

Every surface shares the same root pattern. The widget is always #air-widget with class air-widget and a data-context attribute:

Inline Search:

<div id="air-widget" class="air-widget air-inline-search" data-context="search">
  …
</div>

Hover Widget:

<div id="air-widget" class="air-widget" data-context="hover">
  …
</div>

Service Hub:

<div id="air-widget" class="air-widget" data-context="service-hub">
  …
</div>

Overlay search (fullscreen panel opened from the Hover Widget):

<div id="air-widget" class="air-widget overlay" data-context="hover">
  …
</div>

Context values

Always scope context selectors to #air-widget so you do not accidentally match unrelated elements on the host page:

/* Good */
#air-widget[data-context="hover"] .air-messages { … }

/* Avoid on customer sites — too broad */
[data-context="hover"] .air-messages { … }

Class Reference

Component classes use semantic names — the same class name on every surface. You no longer need (and should not use) old suffixes such as -hw (hover widget) or -sh (service hub).

Chat and widget shell

Search-specific (Hover overlay and Inline Search)

Practical rule: use .air-assistant-message (or theme variables on #air-widget) for shared chat styling. Add #air-widget[data-context="..."] when a surface needs different styling.

Migrating Old CSS

If your style.css still uses legacy suffixed class names, update them to the new contract.

Class name changes

Example migration

Before (legacy):

.air-assistant-message-hw {
  background-color: #f0f4f8;
}

.air-widget-title-sh {
  background: #0c4a6e;
}

After (current):

/* Shared styling — applies everywhere */
.air-assistant-message {
  background-color: #f0f4f8;
}

/* Service Hub header only */
#air-widget[data-context="service-hub"] .air-widget-title {
  background: #0c4a6e;
}

Before (hover-only with suffix on every class):

.air-widget-hw .air-messages-hw {
  font-family: 'Open Sans', sans-serif;
}

After:

#air-widget[data-context="hover"].air-widget {
  font-family: 'Open Sans', sans-serif;
}

Contact Airgentic support if you have a large legacy stylesheet — we can help batch-convert customer CSS.

UI Themes

Existing services keep the legacy widget design unless a newer UI theme is explicitly enabled in service.conf.

New services use the April 2026 UI theme by default:

"ui_theme": "202604"

When this theme is active, #air-widget also has the class .air-design-202604.

The older key is still supported as a legacy alias:

"service_hub.design_version": "202604"

Future themes will use the same YYYYMM format, such as .air-design-202607.

The style.css editor includes a Preview theme selector so you can see how your CSS looks against a theme before saving. This selector is for preview only; the live service theme is controlled by service.conf.

You usually do not need .air-design-202604 in your selectors

Modern built-in theme rules are wrapped in CSS :where(...). That keeps theme styling intact but gives your style.css equal footing with simple selectors.

Works — no theme class required:

.air-assistant-message {
  width: min(85%, 650px);
}

.air-widget-title {
  background: #0c4a6e;
}

Also works — pin an override to one theme version:

.air-design-202604 .air-assistant-message {
  width: min(85%, 650px);
}

Use the theme class when you want a rule to apply only while 202604 is active and to stay unchanged if Airgentic ships a newer default theme later.

Legacy services without ui_theme do not get .air-design-202604. Target stable classes like .air-assistant-message.

Styling by Surface

Use #air-widget[data-context="..."] when you want a rule on one surface only.

Same rule everywhere

.air-assistant-message {
  border-radius: 18px;
}

One surface only

/* Inline search — wider messages */
#air-widget[data-context="search"] .air-assistant-message {
  width: min(90%, 720px);
}

/* Hover panel — compact messages */
#air-widget[data-context="hover"] .air-assistant-message {
  width: min(92%, 520px);
}

/* Service Hub — full-width header gradient */
#air-widget[data-context="service-hub"] .air-widget-title {
  background: linear-gradient(135deg, #0c4a6e, #0369a1);
}

Combine context with component selectors

/* Welcome chips on search only */
#air-widget[data-context="search"] .air-entity {
  color: #0c4a6e;
}

/* Active Search tab underline on hover overlay */
#air-widget[data-context="hover"] .air-search-shell-tab.active {
  border-bottom-color: #0c4a6e;
}

/* Hide example questions on Service Hub only */
#air-widget[data-context="service-hub"] .air-example-questions {
  display: none;
}

Overlay search (fullscreen hover panel)

A small number of services open search in a fullscreen overlay on top of the page. The root has both data-context="hover" and class overlay:

/* Assistant messages in overlay search mode */
#air-widget[data-context="hover"].overlay .air-assistant-message {
  max-width: 720px;
}

/* Overlay search tab styling */
#air-widget.overlay .air-search-shell-tab.active {
  border-bottom-color: #60a5fa;
}

Inline search page

Inline search adds air-inline-search on the root. You usually only need data-context="search", but both can be combined for extra precision:

#air-widget[data-context="search"].air-inline-search .ais-SearchBox-input {
  border-radius: 999px;
  border-color: #cbd5e1;
}

Modern Theme Variables

For modern themes, the easiest way to customise common colours and surfaces is to set CSS variables on #air-widget in style.css. Variables cascade to headers, messages, chips, inputs, and shadows inside the widget.

Brand palette on every surface

#air-widget {
  --air-header-background: #0d68bb;
  --air-header-text: #ffffff;
  --air-brand: #0d68bb;
  --air-brand-deep: #0a4f8f;
  --air-chip-text: #0d68bb;
  --air-chip-border: rgba(13, 104, 187, 0.3);
  --air-assistant-background: #ffffff;
  --air-assistant-border: rgba(13, 104, 187, 0.15);
  --air-user-background: linear-gradient(135deg, #0d68bb, #0a4f8f);
  --air-user-text: #ffffff;
}

Different palette on search only

#air-widget[data-context="search"] {
  --air-brand: #0c4a6e;
  --air-header-background: #0c4a6e;
  --air-chip-text: #0c4a6e;
}

Variable reference

• Shell: --air-widget-background, --air-widget-text, --air-widget-muted-text, --air-widget-border, --air-widget-shadow, --air-widget-radius
• Brand: --air-brand, --air-brand-deep, --air-brand-soft
• Header: --air-header-background, --air-header-text, --air-header-icon-background, --air-header-icon-border, --air-header-decoration-primary, --air-header-decoration-secondary
• Messages: --air-assistant-background, --air-assistant-text, --air-assistant-border, --air-assistant-shadow, --air-user-background, --air-user-text
• Welcome chips: --air-chip-text, --air-chip-background, --air-chip-border, --air-chip-shadow, --air-chip-hover-background, --air-chip-hover-border, --air-chip-hover-shadow
• Input: --air-input-background, --air-input-text, --air-input-placeholder, --air-input-border, --air-input-focus-border, --air-input-shadow, --air-input-focus-shadow
• Footer: --air-footer-background, --air-footer-text

Inline Search variables

Inline Search uses a separate --air-search-* token set. Put these on #air-widget.air-inline-search so they apply only to the search page and override the built-in light/dark/auto/transparent presets configured in Search settings.

Common starting points:

#air-widget.air-inline-search {
  --air-search-canvas-bg: #252a2c;  /* search page background behind the UI */
  --air-search-card-bg: #353b3e;     /* search input, results panel, result cards */
  --air-search-soft-bg: #2f3538;     /* filters panel, scope-tabs container */
  --air-search-answer-bg: #2f3538;   /* AI summary box */
  --air-search-hover-bg: rgba(255, 255, 255, 0.06);
  --air-search-selected-bg: rgba(255, 255, 255, 0.10);
  --air-search-accent: #2563eb;
}

You do not need to target html or body inside the search iframe. Set --air-search-canvas-bg on #air-widget.air-inline-search and the widget applies it to the search canvas for you.

If the area around the embedded search on your website (outside the widget) should match, style that separately in your page HTML/CSS (for example body or .search-card on search_inline.html). That outer page is not controlled by variables on #air-widget.

Customer style.css is loaded after bundled search CSS, so these variables apply without !important in normal use.

Theme variables are the recommended starting point for brand colours because they update many related elements at once and are less brittle than overriding individual components.

The live preview in the Design screen updates immediately as you edit variables.

Inline Search background guide

Use these variables depending on which background you want to change:

Most common full-background change — one flat colour across the search UI:

#air-widget.air-inline-search {
  --air-search-canvas-bg: #191e20;
  --air-search-card-bg: #191e20;
  --air-search-soft-bg: #191e20;
  --air-search-answer-bg: #191e20;
}

Examples for common themes:

/* Dark theme */
#air-widget.air-inline-search {
  --air-search-canvas-bg: #191e20;
  --air-search-card-bg: #191e20;
  --air-search-soft-bg: #191e20;
  --air-search-answer-bg: #191e20;
  --air-search-hover-bg: #2b3032;
  --air-search-selected-bg: #252a2c;
}

/* Light theme */
#air-widget.air-inline-search {
  --air-search-canvas-bg: #f4f6f8;
  --air-search-card-bg: #ffffff;
  --air-search-soft-bg: #f4f6f8;
  --air-search-answer-bg: #eef6ff;
  --air-search-hover-bg: #eef2f7;
  --air-search-selected-bg: #dbeafe;
}

/* Transparent theme over a branded page */
#air-widget.air-inline-search {
  --air-search-canvas-bg: transparent;
  --air-search-card-bg: rgba(255, 255, 255, 0.92);
  --air-search-soft-bg: rgba(255, 255, 255, 0.78);
  --air-search-answer-bg: rgba(255, 255, 255, 0.92);
}

Cookbook — Copy-Paste Examples

Work through these examples in order. Each builds on the same patterns: variables first, then component classes, then surface scoping.

1. Brand header on every surface

#air-widget {
  --air-header-background: #0c4a6e;
  --air-header-text: #ffffff;
}

.air-widget-title {
  background: #0c4a6e;
}

.air-widget-title-text {
  color: #ffffff;
}

2. Custom font on Hover Widget and Service Hub

#air-widget[data-context="hover"].air-widget,
#air-widget[data-context="service-hub"].air-widget {
  font-family: 'Open Sans', sans-serif;
}

3. Assistant message width (all surfaces)

The built-in 202604 theme sets assistant messages to width: min(85%, 620px). Override with one rule:

.air-assistant-message {
  width: min(85%, 650px);
}

4. Styled assistant bubbles with a brand gradient border

:root {
  --brand-green: #309b42;
  --bubble-bg: #f8f6f6;
}

.air-assistant-message {
  background-image:
    linear-gradient(var(--bubble-bg), var(--bubble-bg)),
    linear-gradient(90deg, var(--brand-green) 0%, #9abb91 100%);
}

.air-user-message {
  border: 1px solid var(--brand-green);
}

5. Welcome suggestion chips

.air-entity {
  color: #0c4a6e;
}

#air-widget {
  --air-chip-text: #0c4a6e;
  --air-chip-border: rgba(12, 74, 110, 0.25);
  --air-chip-hover-background: rgba(12, 74, 110, 0.08);
}

5b. Images in answers

When Images in Answers is enabled in service configuration, the agent may embed representative photos in answers. Override default sizing and spacing with:

#air-widget .air-inline-image {
  max-width: 100%;
  width: min(100%, 420px);
  border-radius: 8px;
  margin: 0.75rem 0;
}

6. Hide example questions

.air-example-questions {
  display: none;
}

Or on one surface only:

#air-widget[data-context="service-hub"] .air-example-questions {
  display: none;
}

7. Loading indicator colour

.air-loading-dots span {
  background-color: #0c4a6e;
}

8. Input area styling

#air-widget {
  --air-input-border: rgba(12, 74, 110, 0.35);
  --air-input-focus-border: #0c4a6e;
  --air-input-focus-shadow: 0 0 0 3px rgba(12, 74, 110, 0.15);
}

.air-text-input::placeholder {
  color: #94a3b8;
}

9. Inline search — pill-shaped search box

#air-widget[data-context="search"] .ais-SearchBox-input {
  border-radius: 999px;
  min-height: 52px;
  font-size: 17px;
}

#air-widget[data-context="search"] .ais-SearchBox-input:focus {
  border-color: #0c4a6e;
  box-shadow: 0 0 0 4px rgba(12, 74, 110, 0.12);
}

10. Search results on inline search pages

Result cards, tabs, and filters use search-specific classes. These apply on the search page regardless of data-context:

.hit-card {
  border-radius: 14px;
  border-color: rgba(12, 74, 110, 0.15);
}

.hit-title a {
  color: #0c4a6e;
}

.type-tab.active,
.nav-link.active {
  border-bottom-color: #0c4a6e;
}

More search selectors are in Styling Site Search.

11. Ask tab vs Search tab (inline search)

The Ask scope tab uses three colour tokens: --air-search-ask-gradient (idle), --air-search-ask-gradient-active (selected), and --air-search-ask-gradient-hover (pointer hover only). Set them on #air-widget.air-inline-search (iframe search). For per-slot layouts where scope tabs render on the host page, also set the same tokens on :root.

:root,
#air-widget.air-inline-search {
  --air-search-ask-gradient: #2563eb;
  --air-search-ask-gradient-active: #1d4ed8;
  --air-search-ask-gradient-hover: #1e40af;
  --air-search-ask-text: #ffffff;
}

The Ask panel reuses chat message classes. Style the tab chrome separately:

#air-widget[data-context="search"] .air-search-shell-tab.active {
  color: #0c4a6e;
  border-bottom-color: #0c4a6e;
}

#air-widget[data-context="search"] #air-widget-chat.search-ask-panel .air-assistant-message {
  max-width: 720px;
}

.air-search-ask-tab,
.search-ask-tab {
  font-weight: 700;
}

12. Overlay search — tab and message styling

#air-widget.overlay .air-search-shell-tab.active {
  border-bottom-color: #60a5fa;
}

#air-widget[data-context="hover"].overlay .air-assistant-message {
  background-color: rgba(0, 0, 0, 0.75);
  color: #ffffff;
}

Selector Cheat Sheet

When to Use !important

Prefer normal cascade order first:

1. Airgentic loads your style.css last.
2. Built-in theme selectors use :where(), so your simple selectors usually win.
3. Theme variables on #air-widget update many elements without fighting individual rules.

Reserve !important for:

• Conflicts with your own website CSS on inline search pages (elements render on the host page, not inside an iframe).
• Overriding a third-party search stylesheet you do not control.
• Rare cases where host-page CSS targets the same classes with very high specificity.

If a rule is not applying, check in the browser developer tools which stylesheet is winning before reaching for !important. Often the fix is a more specific selector (for example, adding #air-widget[data-context="hover"]) rather than !important.

Site Search and External Stylesheets

If your organisation already has a hosted search stylesheet, Airgentic support can add that URL to Search Configuration > Superuser. External stylesheets load before your Airgentic-managed style.css, so the Design screen remains the final override layer.

For search-specific selector examples, result-card vs CSS guidance, and per-slot layout notes, see Styling Site Search.

Troubleshooting

My CSS change does not appear

1. Click Submit in UI Design and wait a few minutes for propagation.
2. Hard-refresh the page (or clear cache) — widget JavaScript and CSS are cached.
3. Confirm you are editing the correct account / service in UI Design.
4. Use browser developer tools to inspect the element and verify your selector matches the live DOM.

My override works in preview but not on the live site

The Design screen preview shows Service Hub styling. Hover Widget, overlay search, and inline search may need surface-specific selectors. Test on the real page for each surface you care about.

I used to target -hw / -sh classes

Remove the suffix and use semantic class names. Add #air-widget[data-context="hover"] or "service-hub" when you need surface-specific rules. See Migrating Old CSS.

Styles differ between Hover Widget and Service Hub

That is expected if built-in defaults differ slightly per surface. Use #air-widget[data-context="..."] to align them, or set shared theme variables on #air-widget for consistent brand colours.

Inline search picks up my website CSS

Inline search renders on your page (not always in an iframe). Host-page rules can affect search elements. Scope your website CSS away from air-* classes, or scope Airgentic overrides to #air-widget / [data-airgentic="..."].

Cancelling

Click Cancel to go back to the file list. If you have unsaved changes, you will be prompted to confirm before leaving — changes will be lost if you proceed.