Agent UI Color Themes - Mindset AI Documentation

Overview

Agent UI Color Themes let you customize your embedded agent’s colors to match your brand. You can choose between two approaches: Quick theming — Set just 3 parameters (brightness, seedColor, dynamicSchemeVariant) to generate a harmonious color palette automatically Precise control — Customize individual color tokens for complete control over every UI element Both approaches use Material 3’s color system to ensure accessible, harmonious color combinations throughout the agent interface.

Quick Start: Using Color Themes

The fastest way to match your brand is to use the theme system. Specify three parameters, and the SDK automatically generates a complete color palette.

Basic Theme Configuration

const lightTheme = {
    brightness: "light",
    seedColor: '#8E004E',
    dynamicSchemeVariant: 'vibrant'
};

mindset.init({
    theme: lightTheme
});

That’s it. Your agent now uses a harmonious color palette based on your seed color.

Theme Parameters

brightness

Values: "light" or "dark" Sets the overall brightness of the theme. This determines whether the agent uses light backgrounds with dark text or dark backgrounds with light text.

brightness: "light"  // Light mode
brightness: "dark"   // Dark mode

seedColor

Format: Hex color string (e.g., '#8E004E') The primary color of your brand. The theme system uses this color to generate a complete, harmonious palette that includes primary, secondary, tertiary, surface, and error colors.

seedColor: '#8E004E'  // Your brand's primary color

dynamicSchemeVariant

Default: 'tonalSpot' Controls how the color generation algorithm interprets your seed color. Different variants produce different aesthetic styles while maintaining color harmony.

dynamicSchemeVariant: 'vibrant'

See Dynamic Scheme Variants below for all available options.

Examples: Seed Color Palettes

Here’s how different brightness settings affect the same seed color:

Light Theme with #C42A73

Light theme example with seed color #C42A73

Dark Theme with #C42A73

Dark theme example with seed color #C42A73

The same seed color produces different but harmonious palettes in light and dark modes, ensuring proper contrast and readability in both.

Dynamic Scheme Variants

The dynamicSchemeVariant parameter gives you control over the color generation algorithm’s aesthetic interpretation.

Variant	Description	Best For
`tonalSpot`	Default Material theme style. Builds pastel palettes with low chroma.	General use, subtle branding
`fidelity`	Palettes match seed color closely, even for bright colors (high chroma).	Strong brand color matching
`monochrome`	All colors are grayscale, no chroma.	Minimal, professional designs
`neutral`	Close to grayscale with a hint of chroma.	Understated, elegant designs
`expressive`	Pastel colors with medium chroma. Primary palette’s hue differs from seed for variety.	Playful, diverse color schemes
`content`	Almost identical to fidelity. `primaryContainer` is the seed color. Tertiary is analogous to seed.	Content-focused applications
`rainbow`	Playful theme where seed color’s hue doesn’t appear in generated colors. Broader spectrum.	Creative, colorful designs
`fruitSalad`	Similar to rainbow. Seed color’s hue typically doesn’t appear in the theme.	Vibrant, energetic designs

Example: Comparing Variants

// Subtle, pastel palette
const tonalTheme = {
    brightness: "light",
    seedColor: '#8E004E',
    dynamicSchemeVariant: 'tonalSpot'
};

// Strong brand color matching
const fidelityTheme = {
    brightness: "light",
    seedColor: '#8E004E',
    dynamicSchemeVariant: 'fidelity'
};

// Playful, varied colors
const expressiveTheme = {
    brightness: "light",
    seedColor: '#8E004E',
    dynamicSchemeVariant: 'expressive'
};

Advanced: Customizing Individual Color Tokens

For precise control, you can customize individual color tokens while still using the generation algorithm for others.

Partial Customization

Specify key colors like primary, secondary, and surface, and let the algorithm generate the rest:

const customTheme = {
    brightness: 'light',
    seedColor: '#8E004E',
    primary: "#8F4C38",
    secondary: "#77574E",
    surface: "#FFFFFF",
    dynamicSchemeVariant: 'fidelity'
};

This gives you control over critical brand colors while maintaining a harmonious palette.

The Surface Token

The surface token controls the agent’s background color. Many web pages use white backgrounds, so setting surface to white ensures the agent blends seamlessly.

const whiteBackgroundTheme = {
    brightness: 'light',
    seedColor: '#8E004E',
    surface: "#FFFFFF",  // Matches typical web page backgrounds
    dynamicSchemeVariant: 'fidelity'
};

When generating the palette, the agent background receives a subtle tint by default. Setting surface explicitly overrides this behavior.

Complete Token Customization

For maximum control, you can specify every color token individually. This is best when you have an existing design system or need exact color matching.

Full Theme Object

const fullyCustomTheme = {
    brightness: "light",
    primary: "#8F4C38",
    surfaceTint: "#8F4C38",
    onPrimary: "#FFFFFF",
    primaryContainer: "#FFDBD1",
    onPrimaryContainer: "#723523",
    secondary: "#77574E",
    onSecondary: "#FFFFFF",
    secondaryContainer: "#FFDBD1",
    onSecondaryContainer: "#5D4037",
    tertiary: "#6C5D2F",
    onTertiary: "#FFFFFF",
    tertiaryContainer: "#F5E1A7",
    onTertiaryContainer: "#534619",
    error: "#BA1A1A",
    onError: "#FFFFFF",
    errorContainer: "#FFDAD6",
    onErrorContainer: "#93000A",
    background: "#FFF8F6",
    onBackground: "#231917",
    surface: "#FFF8F6",
    onSurface: "#231917",
    surfaceVariant: "#F5DED8",
    onSurfaceVariant: "#53433F",
    outline: "#85736E",
    outlineVariant: "#D8C2BC",
    shadow: "#000000",
    scrim: "#000000",
    inverseSurface: "#392E2B",
    inverseOnSurface: "#FFEDE8",
    inversePrimary: "#FFB5A0",
    primaryFixed: "#FFDBD1",
    onPrimaryFixed: "#3A0B01",
    primaryFixedDim: "#FFB5A0",
    onPrimaryFixedVariant: "#723523",
    secondaryFixed: "#FFDBD1",
    onSecondaryFixed: "#2C150F",
    secondaryFixedDim: "#E7BDB2",
    onSecondaryFixedVariant: "#5D4037",
    tertiaryFixed: "#F5E1A7",
    onTertiaryFixed: "#231B00",
    tertiaryFixedDim: "#D8C58D",
    onTertiaryFixedVariant: "#534619",
    surfaceDim: "#E8D6D2",
    surfaceBright: "#FFF8F6",
    surfaceContainerLowest: "#FFFFFF",
    surfaceContainerLow: "#FFF1ED",
    surfaceContainer: "#FCEAE5",
    surfaceContainerHigh: "#F7E4E0",
    surfaceContainerHighest: "#F1DFDA"
};

mindset.init({
    theme: fullyCustomTheme
});

When you manually set color tokens, they override the generated values regardless of brightness setting. For example, if you set surface: "#FFFFFF", it will be white in both light and dark modes unless you provide different theme objects.

Color Token Reference

Core Color Tokens

brightness

Indicates whether the theme is "light" or "dark". This influences how colors are used and perceived. Manually set color values will override the defaults created for light and dark modes.

dynamicSchemeVariant

Specifies the algorithm used to generate the color scheme from the seedColor. See Dynamic Scheme Variants for all available options.

seedColor

The main color of the theme, used to generate the complete color palette. This should be your brand’s primary color.

primary

The main color used throughout the UI for key interactive elements. Used for the main agent text bubble, primary buttons, thread list, and capability chooser.

surfaceTint

A color overlay applied to surfaces to indicate elevation.

onPrimary

The color used for text and icons displayed on top of the primary color.

primaryContainer

A slightly lighter or darker variant of the primary color used for container backgrounds.

onPrimaryContainer

The color used for text and icons displayed on top of the primaryContainer color.

Secondary & Tertiary Colors

secondary

A color used to provide visual balance and distinguish elements from primary ones.

onSecondary

The color used for text and icons displayed on top of the secondary color.

secondaryContainer

A variant of the secondary color used for container backgrounds.

onSecondaryContainer

The color used for text and icons displayed on top of the secondaryContainer color.

tertiary

An optional color used to provide more visual variety and accent elements.

onTertiary

The color used for text and icons displayed on top of the tertiary color.

tertiaryContainer

A variant of the tertiary color used for container backgrounds.

onTertiaryContainer

The color used for text and icons displayed on top of the tertiaryContainer color.

Error Colors

error

The color used for error messages and warnings.

onError

The color used for text and icons displayed on top of the error color.

errorContainer

A variant of the error color used for error message containers.

onErrorContainer

The color used for text and icons displayed on top of the errorContainer color.

Surface Colors

surface

The background color of most of the app’s UI.

onSurface

The color used for text and icons displayed on top of the surface color.

surfaceVariant

A slightly different variant of the surface color.

surfaceContainerHighest

The highest elevation surface container color.

surfaceDim, surfaceBright, surfaceContainerLowest, surfaceContainerLow, surfaceContainer, surfaceContainerHigh

Various surface container colors with different elevation and brightness levels.

Additional Tokens

outlineVariant

A variant of the outline color.

shadow

The color used for shadows.

scrim

The color used for scrims (semi-transparent overlays).

inverseSurface

An alternate surface color, often used in specific UI sections.

onInverseSurface

The color used for text and icons displayed on top of the inverseSurface color.

inversePrimary

An alternate primary color, typically used with the inverseSurface.

Fixed Color Roles

primaryFixed, onPrimaryFixed, primaryFixedDim, onPrimaryFixedVariant, secondaryFixed, onSecondaryFixed, secondaryFixedDim, onSecondaryFixedVariant, tertiaryFixed, onTertiaryFixed, tertiaryFixedDim, onTertiaryFixedVariantFixed color roles used in components like navigation bars or tabs that maintain their color even when scrolling.

Generate Palettes with Material Theme Builder

To ensure your agent matches your brand, use Google’s Material 3 Theme Builder to generate complete, harmonious color palettes.

Using the Web Tool

Open Material Theme Builder

Visit Material Theme Builder

Choose core colors

Select the primary, secondary, and tertiary colors that represent your brand

Export theme

Export the theme in Material Theme (JSON) format

Open the JSON file

Open the downloaded material-theme.json file

Copy theme objects

Copy the light and dark theme objects from the JSON file

Convert to JavaScript

Convert the JSON format to JavaScript (remove quotes from property names):From JSON:

{
  "primary": "#8F4C38",
  "surfaceTint": "#8F4C38"
}

To JavaScript:

{
  primary: "#8F4C38",
  surfaceTint: "#8F4C38"
}

You can use any LLM or text editor to make this conversion quickly.

Use in your code

Paste the converted theme object into your code and pass it to mindset.init()

Using the Figma Plugin

The Material Theme Builder plugin for Figma offers additional flexibility for designers who want to make manual adjustments to each color in the generated palette. This allows fine-tuning to perfectly align with your brand’s aesthetic while maintaining color harmony and accessibility.

Best Practices

Quick Theming

Start with seed color and variant. Most brands can achieve excellent results by just setting seedColor and dynamicSchemeVariant without touching individual tokens. Use fidelity for strong brand matching. If your brand has a specific primary color that must be preserved exactly, use dynamicSchemeVariant: 'fidelity'. Set surface to white for seamless integration. If your website uses white backgrounds, explicitly set surface: "#FFFFFF" so the agent blends naturally. Test both light and dark modes. Create separate theme objects for light and dark modes and test both thoroughly.

Complete Customization

Use Material Theme Builder. Don’t manually create color palettes—use the builder to ensure proper contrast ratios and color harmony. Maintain accessibility. Ensure sufficient contrast between text and background colors (WCAG AA minimum: 4.5:1 for body text, 3:1 for large text). Create separate light/dark themes. Don’t use the same color values for both modes—each needs its own optimized palette. Document your tokens. Keep a reference of which tokens you’ve customized and why, especially if multiple team members work on the design.

Testing

Test with real content. View your theme with actual agent conversations, not just empty states. Check all UI states. Verify colors work for hover states, disabled states, error states, and loading states. Test on different devices. Colors appear differently on various screens—test on mobile, tablet, and desktop. Verify in different lighting. What looks good on a bright screen might not work in dim lighting, and vice versa.

Troubleshooting

Colors don’t match my brand

Possible causes:

Using wrong dynamicSchemeVariant
Seed color is too different from desired final color
Not setting key tokens manually

Solution: Try dynamicSchemeVariant: 'fidelity' for closer seed color matching. Or manually set primary, secondary, and surface tokens.

Agent doesn’t blend with my website

Possible causes:

surface token doesn’t match website background
Theme brightness doesn’t match website theme
Border colors or shadows stand out

Solution: Explicitly set surface to match your website’s background color. Ensure brightness matches your site’s theme. Adjust outline and shadow tokens if needed.

Text is hard to read

Possible causes:

Insufficient contrast between text and background
Wrong onPrimary, onSurface, or similar tokens

Solution: Use Material Theme Builder to generate accessible color combinations. Check WCAG contrast ratios. Verify onPrimary, onSurface, and other “on” tokens provide sufficient contrast.

Theme looks different in dark mode

Possible causes:

Using same color values for light and dark modes
Manual token values override brightness setting

Solution: Create separate theme objects for light and dark modes. Remove manual token overrides and let the algorithm handle mode-specific adjustments.

Colors are too muted or too vibrant

Possible causes:

Wrong dynamicSchemeVariant for desired aesthetic
Seed color doesn’t support desired vibrancy

Solution: Experiment with different variants: tonalSpot for muted, fidelity or vibrant for more saturated, expressive or rainbow for variety.

Overview

Integrate Agent Chat SDK 3

Integrate Agent Chat SDK 2

MCP Server Integration

AMS SDK Integration

API Overview

API playground

Webhooks

​Overview

​Quick Start: Using Color Themes

​Basic Theme Configuration

​Theme Parameters

​brightness

​seedColor

​dynamicSchemeVariant

​Examples: Seed Color Palettes

​Light Theme with #C42A73

​Dark Theme with #C42A73

​Dynamic Scheme Variants

​Example: Comparing Variants

​Advanced: Customizing Individual Color Tokens

​Partial Customization

​The Surface Token

​Complete Token Customization

​Full Theme Object

​Color Token Reference

​Core Color Tokens

​Secondary & Tertiary Colors

​Error Colors

​Surface Colors

​Additional Tokens

​Generate Palettes with Material Theme Builder

​Using the Web Tool

​Using the Figma Plugin

​Best Practices

​Quick Theming

​Complete Customization

​Testing

​Troubleshooting

​Colors don’t match my brand

​Agent doesn’t blend with my website

​Text is hard to read

​Theme looks different in dark mode

​Colors are too muted or too vibrant

Overview

Quick Start: Using Color Themes

Basic Theme Configuration

Theme Parameters

brightness

seedColor

dynamicSchemeVariant

Examples: Seed Color Palettes

Light Theme with #C42A73

Dark Theme with #C42A73

Dynamic Scheme Variants

Example: Comparing Variants

Advanced: Customizing Individual Color Tokens

Partial Customization

The Surface Token

Complete Token Customization

Full Theme Object

Color Token Reference

Core Color Tokens

Secondary & Tertiary Colors

Error Colors

Surface Colors

Additional Tokens

Generate Palettes with Material Theme Builder

Using the Web Tool

Using the Figma Plugin

Best Practices

Quick Theming

Complete Customization

Testing

Troubleshooting

Colors don’t match my brand

Agent doesn’t blend with my website

Text is hard to read

Theme looks different in dark mode

Colors are too muted or too vibrant