Themes
Learn how to customize the look and feel of the Agent Portal and the User Portal from the Management Portal.
Overview
The Themes page has two tabs:
| Tab | What it manages | Where it is stored |
|---|---|---|
| Agent Portal | The Agent Portal theme catalog: the default theme, the themes users may choose from, and the content of each theme. | One application/json App Configuration key per theme plus a manifest key, under FoundationaLLM:AgentPortal:Themes: |
| User Portal | User Portal branding: company name, logo, page title, footer, messages, kiosk mode, and colors. | One App Configuration key per setting, under FoundationaLLM:Branding: |
All changes are written to Azure App Configuration through the Management API (FoundationaLLM.Configuration/appConfigurations). You need write permission on app configurations to save changes.
Open the Themes Page
- Sign in to the Management Portal.
- In the sidebar, select Platform > Themes.
- Select the Agent Portal or User Portal tab.
Agent Portal Themes
The Agent Portal tab edits the structured theme catalog stored in the AgentPortal app configuration set.
Catalog settings
| Control | Description |
|---|---|
| Default theme | The theme the Agent Portal uses when a user has not chosen one. Changing it opens a Change default theme? confirmation and is saved immediately. The new default is added to the allowed themes if needed. |
| Allowed themes | Check the themes users may select in the Agent Portal. The default theme is always allowed and its checkbox is disabled. Changes to this list are saved with Apply theme. |
Edit a theme
In Theme to edit, select a theme. The section below shows Selected theme to edit: {name}.
Change the structured fields:
Field Description Name Display name of the theme Description Short description of the theme Accent Accent color (color picker) Greeting Greeting text shown on the Agent Portal home screen For everything else, expand Advanced JSON for {name} and edit the theme document directly. Each theme document contains the sections
colors,focus,homescreen,sidebar,header,chat,prompt,userControls,completionControls,completionIcon,userWidget, andfooter. For example,focus.useDottedBordercontrols the focus indicator style, and thefootersection controls whether a theme footer is shown and its text, alignment, colors, font, and padding.Select Validate changes. Validation checks the theme against the catalog rules (required sections, no unknown fields, matching theme id). You must validate after any change before you can apply or export.
Select Apply theme and confirm in the Apply theme? dialog. The changes are applied immediately.
Theme package name and Theme package version show which artifact package deployed the theme, or N/A. When a theme comes from a package, a warning explains that redeploying the package may overwrite your changes.
Other actions
| Button | Description |
|---|---|
| Reload | Reloads the catalog from App Configuration. If you have unapplied changes, a Discard theme changes? dialog asks you to confirm. |
| Validate changes | Validates the selected theme. Enabled only after you change it. |
| Export theme | Downloads the selected theme as appConfigurations.json in the platform package format, so you can include it in an artifact package. |
| Delete theme | Removes the theme from the manifest and deletes its App Configuration key. You cannot delete the default theme, the last theme in the catalog, or a theme with unapplied changes. |
| Apply theme | Saves the selected theme and catalog settings. |
Moving to another theme with unapplied changes opens a confirmation that offers Stay on theme or Discard changes.
Note
Themes can also be deployed through artifact packages on the Packages page. A package that contains Agent Portal theme keys is merged into the existing manifest rather than replacing it.
User Portal Branding
The User Portal tab lists every FoundationaLLM:Branding:* key in App Configuration. Field labels are derived from the key name (for example, LogoUrl is shown as Logo Url).
General settings
| Setting | Key | Editor |
|---|---|---|
| Company Name | CompanyName |
Text |
| Fav Icon Url | FavIconUrl |
Text |
| Footer Text | FooterText |
Rich text |
| Kiosk Mode | KioskMode |
Toggle |
| Logo Text | LogoText |
Text |
| Logo Url | LogoUrl |
Text, with a preview against the primary color |
| Page Title | PageTitle |
Text |
| Agent Icon Url | AgentIconUrl |
Text |
| No Agents Message | NoAgentsMessage |
Rich text |
| Default Agent Welcome Message | DefaultAgentWelcomeMessage |
Rich text |
Logo, favicon, and agent icon values can be an absolute URL or a path relative to the portal's public directory (for example, the default foundationallm-logo-white.svg).
Any other FoundationaLLM:Branding:* key that exists in App Configuration (for example ManagementPortalDefaultTheme) is shown below the color groups as a plain text field.
Colors
Colors are grouped in pairs of background and text color. Each group shows a TEST preview.
| Group | Background key | Text key |
|---|---|---|
| Accent | AccentColor |
AccentTextColor |
| Background | BackgroundColor |
— |
| Primary Button | PrimaryButtonBackgroundColor |
PrimaryButtonTextColor |
| Primary | PrimaryColor |
PrimaryTextColor |
| Secondary Button | SecondaryButtonBackgroundColor |
SecondaryButtonTextColor |
| Secondary | SecondaryColor |
SecondaryTextColor |
Enter colors as hex (#RRGGBB or #RGB) or rgb(R, G, B), or use the color picker.
Contrast information
Turn on Show contrast information (top right of the tab) to display, for each group that has a text color:
- The contrast ratio, for example
4.5 : 1. - AA — Pass when the ratio is at least 4.5:1.
- AAA — Pass when the ratio is at least 7:1.
Save, reset, or restore defaults
| Button | Description |
|---|---|
| Reset | Opens Reset Branding and reverts all values to the last loaded values. Enabled only when there are unsaved changes. |
| Set Default | Opens Set Default Branding and replaces the values with the FoundationaLLM defaults. Select Save afterwards to persist them. |
| Save | Writes every changed key to App Configuration. |
The default values are listed in the Branding Reference.
Troubleshooting
| Issue | Resolution |
|---|---|
| Apply theme is disabled | Validate the theme first, or make a change to the theme or the catalog settings. Hover over the button to see the reason. |
| Validation fails | Read the error message. Typical causes are a missing or extra field in a theme section, or a theme id that does not match the catalog entry. |
| Theme changes are lost after a package deployment | The theme is linked to an artifact package. Update the package, or export your theme and include it in a new package version. |
| User Portal branding changes do not appear | Confirm Save succeeded, then refresh the User Portal. Portals read branding values when they load configuration. |
| Logo is not displayed | Check the Logo Url value and the preview on the User Portal tab. |