> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindset.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent UI Color Themes

> Customize agent colors to match your brand using themes or individual color tokens

## 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

```javascript theme={null}
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.

```javascript theme={null}
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.

```javascript theme={null}
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.

```javascript theme={null}
dynamicSchemeVariant: 'vibrant'
```

See [Dynamic Scheme Variants](#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

<img src="https://mintlify.s3.us-west-1.amazonaws.com/mindsetai/images/color-theme-light-example.png" alt="Light theme example with seed color #C42A73" />

### Dark Theme with #C42A73

<img src="https://mintlify.s3.us-west-1.amazonaws.com/mindsetai/images/color-theme-dark-example.png" alt="Dark theme example with seed color #C42A73" />

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

## 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

```javascript theme={null}
// 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:

```javascript theme={null}
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.

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

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

## 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

```javascript theme={null}
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
});
```

<Warning>
  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.
</Warning>

## Color Token Reference

### Core Color Tokens

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="dynamicSchemeVariant">
    Specifies the algorithm used to generate the color scheme from the `seedColor`. See [Dynamic Scheme Variants](#dynamic-scheme-variants) for all available options.
  </Accordion>

  <Accordion title="seedColor">
    The main color of the theme, used to generate the complete color palette. This should be your brand's primary color.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="surfaceTint">
    A color overlay applied to surfaces to indicate elevation.
  </Accordion>

  <Accordion title="onPrimary">
    The color used for text and icons displayed on top of the `primary` color.
  </Accordion>

  <Accordion title="primaryContainer">
    A slightly lighter or darker variant of the primary color used for container backgrounds.
  </Accordion>

  <Accordion title="onPrimaryContainer">
    The color used for text and icons displayed on top of the `primaryContainer` color.
  </Accordion>
</AccordionGroup>

### Secondary & Tertiary Colors

<AccordionGroup>
  <Accordion title="secondary">
    A color used to provide visual balance and distinguish elements from primary ones.
  </Accordion>

  <Accordion title="onSecondary">
    The color used for text and icons displayed on top of the `secondary` color.
  </Accordion>

  <Accordion title="secondaryContainer">
    A variant of the secondary color used for container backgrounds.
  </Accordion>

  <Accordion title="onSecondaryContainer">
    The color used for text and icons displayed on top of the `secondaryContainer` color.
  </Accordion>

  <Accordion title="tertiary">
    An optional color used to provide more visual variety and accent elements.
  </Accordion>

  <Accordion title="onTertiary">
    The color used for text and icons displayed on top of the `tertiary` color.
  </Accordion>

  <Accordion title="tertiaryContainer">
    A variant of the tertiary color used for container backgrounds.
  </Accordion>

  <Accordion title="onTertiaryContainer">
    The color used for text and icons displayed on top of the `tertiaryContainer` color.
  </Accordion>
</AccordionGroup>

### Error Colors

<AccordionGroup>
  <Accordion title="error">
    The color used for error messages and warnings.
  </Accordion>

  <Accordion title="onError">
    The color used for text and icons displayed on top of the `error` color.
  </Accordion>

  <Accordion title="errorContainer">
    A variant of the error color used for error message containers.
  </Accordion>

  <Accordion title="onErrorContainer">
    The color used for text and icons displayed on top of the `errorContainer` color.
  </Accordion>
</AccordionGroup>

### Surface Colors

<AccordionGroup>
  <Accordion title="surface">
    The background color of most of the app's UI.
  </Accordion>

  <Accordion title="onSurface">
    The color used for text and icons displayed on top of the `surface` color.
  </Accordion>

  <Accordion title="surfaceVariant">
    A slightly different variant of the surface color.
  </Accordion>

  <Accordion title="surfaceContainerHighest">
    The highest elevation surface container color.
  </Accordion>

  <Accordion title="surfaceDim, surfaceBright, surfaceContainerLowest, surfaceContainerLow, surfaceContainer, surfaceContainerHigh">
    Various surface container colors with different elevation and brightness levels.
  </Accordion>
</AccordionGroup>

### Additional Tokens

<AccordionGroup>
  <Accordion title="outlineVariant">
    A variant of the outline color.
  </Accordion>

  <Accordion title="shadow">
    The color used for shadows.
  </Accordion>

  <Accordion title="scrim">
    The color used for scrims (semi-transparent overlays).
  </Accordion>

  <Accordion title="inverseSurface">
    An alternate surface color, often used in specific UI sections.
  </Accordion>

  <Accordion title="onInverseSurface">
    The color used for text and icons displayed on top of the `inverseSurface` color.
  </Accordion>

  <Accordion title="inversePrimary">
    An alternate primary color, typically used with the `inverseSurface`.
  </Accordion>

  <Accordion title="Fixed Color Roles">
    `primaryFixed`, `onPrimaryFixed`, `primaryFixedDim`, `onPrimaryFixedVariant`, `secondaryFixed`, `onSecondaryFixed`, `secondaryFixedDim`, `onSecondaryFixedVariant`, `tertiaryFixed`, `onTertiaryFixed`, `tertiaryFixedDim`, `onTertiaryFixedVariant`

    Fixed color roles used in components like navigation bars or tabs that maintain their color even when scrolling.
  </Accordion>
</AccordionGroup>

## 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

<Steps>
  <Step title="Open Material Theme Builder">
    Visit [Material Theme Builder](https://material-foundation.github.io/material-theme-builder/)
  </Step>

  <Step title="Choose core colors">
    Select the primary, secondary, and tertiary colors that represent your brand
  </Step>

  <Step title="Export theme">
    Export the theme in **Material Theme (JSON)** format
  </Step>

  <Step title="Open the JSON file">
    Open the downloaded `material-theme.json` file
  </Step>

  <Step title="Copy theme objects">
    Copy the light and dark theme objects from the JSON file
  </Step>

  <Step title="Convert to JavaScript">
    Convert the JSON format to JavaScript (remove quotes from property names):

    **From JSON:**

    ```json theme={null}
    {
      "primary": "#8F4C38",
      "surfaceTint": "#8F4C38"
    }
    ```

    **To JavaScript:**

    ```javascript theme={null}
    {
      primary: "#8F4C38",
      surfaceTint: "#8F4C38"
    }
    ```

    You can use any LLM or text editor to make this conversion quickly.
  </Step>

  <Step title="Use in your code">
    Paste the converted theme object into your code and pass it to `mindset.init()`
  </Step>
</Steps>

### 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.