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

# Design System

> Complete control over visual appearance and behavior patterns across SDK 3

## Overview

Design System gives you complete control over the visual appearance of your AI agents and all SDK 3 interfaces. Built on [Material Design 3](https://m3.material.io/) principles, it lets you define your brand colors, typography, and styling once—then apply them consistently across your entire SDK implementation, including chat interfaces, widgets, and all UI components.

<Note>
  **SDK 3 Required:** Design System is available exclusively in SDK 3.
</Note>

<iframe src="https://www.loom.com/embed/3e5ca7e9a5e542a5b355ae34a9e52de0" width="100%" height="450px" frameBorder="0" allowFullScreen />

## Key Features

Design System includes two powerful components:

### Design System (Visual Branding)

Control colors, typography, and visual appearance across your entire SDK 3 implementation. Built on Material Design 3 principles, it automatically generates complementary color palettes from your primary brand color and lets you preview how everything will look in both light and dark modes.

### Widget Guidelines (Generation Rules)

Define how widgets should be structured and what interaction patterns they should follow. These guidelines act as instructions for the AI when generating new widgets, ensuring consistent behavior, data visualization approaches, and user interaction patterns.

## What is a Design System?

A Design System is a theme configuration that controls the visual styling for your entire SDK 3 implementation—including chat interfaces, widgets, and all UI components.

**Key concept:** Instead of manually setting colors for every element, Design Systems use theme variables. Elements say "use primary color" and the Design System defines what that color is. Change your Design System's primary color, and everything using that variable updates automatically.

This is based on Google's [Material Design 3](https://m3.material.io/) system, which generates an entire harmonious color palette from a single seed color.

## Where Design Systems Apply

Design Systems control the visual appearance of:

### Everything in SDK 3 (when embedded)

* Chat interface (background colors, text, message bubbles)
* Widgets displayed in chat
* UI components (buttons, forms, cards)
* Typography across all elements
* All visual elements in the SDK

### Everything in Agent Management Studio (automatically)

* Agent preview
* Dashboard views
* Demo pages
* Any SDK 3 interface displayed within Agent Management Studio

## How Design Systems Work

### Your Default Design System

When you enable Design Systems, a **Default Design System** is automatically created with initial settings:

* **Seed color:** Purple
* **Palette style:** Tonal Spot
* **Typography:** Roboto font family
* **Mode:** Light mode enabled

<Note>
  **What happens automatically:** Everything you see in Agent Management Studio (previews, dashboard, demo pages) immediately uses your Default Design System. Change it, and those views update instantly.
</Note>

<Warning>
  **What does NOT happen automatically:** Your embedded SDK does not automatically use your Default Design System. The SDK doesn't know about it unless you explicitly tell it to use one.
</Warning>

## Creating a Design System

<Steps>
  <Step title="Navigate to Design Systems">
    Open **Design Systems** in Agent Management Studio
  </Step>

  <Step title="Create new Design System">
    Click **New Design System** and give it a descriptive name
  </Step>

  <Step title="Select seed color">
    Choose your primary brand color. Material Design 3 automatically generates a complete color palette from this single color.
  </Step>

  <Step title="Choose palette style">
    Select the visual style that matches your brand:

    * **Tonal Spot** - Balanced, harmonious (recommended)
    * **Vibrant** - Bold, saturated colors
    * **Expressive** - High-contrast, dynamic
    * **Neutral** - Muted, understated
  </Step>

  <Step title="Set typography">
    Configure font family, sizes, weights, and spacing
  </Step>

  <Step title="Choose mode">
    Select Light or Dark mode
  </Step>

  <Step title="Preview">
    See how your Design System looks across different components
  </Step>

  <Step title="Save">
    Save your Design System
  </Step>
</Steps>

## Implementing Design Systems in Your SDK

<Warning>
  **Critical:** Your SDK does NOT automatically use your Default Design System. You must manually implement it.
</Warning>

### Implementation Steps

<Steps>
  <Step title="Customize Design System">
    Customize your Design System in Agent Management Studio
  </Step>

  <Step title="Copy the code">
    Go to the **Code** tab in your Design System and copy the entire code block
  </Step>

  <Step title="Paste into SDK initialization">
    Paste the code into your SDK initialization:

    ```javascript theme={null}
    mindset.init({
      // Your Design System code here
      theme: {
        brightness: 'light',
        primary: '#6750A4',
        secondary: '#625B71',
        // ... rest of your Design System configuration
      }
    });
    ```
  </Step>

  <Step title="Deploy your SDK">
    Deploy your SDK with the new configuration
  </Step>
</Steps>

Now your SDK will use your Design System colors and fonts for the entire interface—chat, widgets, everything.

## Updating Your Design System

When you change your Design System:

| Location                    | Updates Automatically? | Action Required                                                     |
| --------------------------- | ---------------------- | ------------------------------------------------------------------- |
| **Agent Management Studio** | ✅ Yes                  | Changes apply immediately to preview, dashboard, demo pages         |
| **Live SDK**                | ❌ No                   | You must copy the new code, update SDK implementation, and redeploy |

<Tip>
  Always test Design System changes in Agent Management Studio before updating your production SDK.
</Tip>

## Design Systems & Widgets

Widgets automatically use whatever Design System your SDK is using.

### How It Works

**When building a widget:**

1. Widgets use theme variables like "primary color" and "background color"
2. You can switch between Design Systems in Widget Studio to preview how the widget will look
3. The widget does NOT save or remember which Design System you were viewing

**When the widget displays in production:**

1. The SDK provides the actual color values based on your Design System implementation
2. The widget renders using those values
3. If you change your SDK's Design System, the widget automatically adapts

### Example

```
1. You build a course enrollment widget while previewing Design System A (blue)
2. You implement your SDK with Design System B (green)
3. Users see the widget in green (matching Design System B)
```

**The widget follows the SDK, not the Design System you happened to be viewing when you built it.**

## Previewing Widgets with Different Design Systems

In Widget Studio:

1. Select your widget
2. Change the **Design System** dropdown
3. The preview updates to show how the widget looks with that Design System

<Note>
  This is ONLY for preview. The widget will use whatever Design System your SDK provides in production.
</Note>

## Hardcoding Widget Colors

If you need a widget to always use specific colors regardless of the SDK's Design System, you must hardcode hex values in the widget code instead of using theme variables.

**Use case:** You want your company branding on a widget to stay consistent even when customers customize their SDK colors.

### Example

```javascript theme={null}
// ❌ Uses whatever primary color the SDK defines
color: var(--md-sys-color-primary)

// ✅ Always this exact color
color: #FF5733
```

<Warning>
  This is advanced customization. Contact [support@mindset.ai](mailto:support@mindset.ai) if you need help.
</Warning>

## Creating Multiple Design Systems

You can create multiple Design Systems for different purposes.

### Common Use Cases

<CardGroup cols={2}>
  <Card title="Preview Options" icon="eye">
    Preview different color schemes before deciding on your final brand
  </Card>

  <Card title="Multi-Tenant Branding" icon="users">
    Different Design System per client or tenant
  </Card>

  <Card title="Environments" icon="server">
    Separate Design Systems for development vs. production
  </Card>

  <Card title="Accessibility Testing" icon="universal-access">
    Test different contrast levels and readability
  </Card>
</CardGroup>

### Using Multiple Design Systems

<Steps>
  <Step title="Create multiple systems">
    Create as many Design Systems as needed in Agent Management Studio
  </Step>

  <Step title="Preview and compare">
    Switch between them in Agent Management Studio to preview
  </Step>

  <Step title="Select for production">
    Copy the code from whichever one you want to use in production
  </Step>

  <Step title="Implement in SDK">
    Paste that code into your SDK implementation
  </Step>
</Steps>

<Warning>
  **Important:** Each SDK implementation uses ONE Design System at a time (whichever code you paste in). You cannot assign different Design Systems to different agents—the entire SDK uses one Design System.
</Warning>

## Widget Guidelines: Generation Rules

Widget Guidelines are separate from Design Systems and control how widgets are structured and behave.

### What Widget Guidelines Control

Widget Guidelines define rules that guide widget generation:

* Data visualization approaches (charts, tables, cards)
* Progressive disclosure patterns
* User interaction flows
* Content structure and organization
* Accessibility requirements
* Specific component preferences

### Why Widget Guidelines Matter

**Without guidelines:** Every widget generation starts from scratch. The AI might visualize data differently each time or use inconsistent interaction patterns.

**With Widget Guidelines:** You define your preferences once—like "always use progressive visualization for complex data"—and every widget respects those rules automatically.

### How Widget Guidelines Work

Widget Guidelines function as system prompts that guide the AI agent responsible for widget generation. When you generate a new widget, the AI automatically follows your established guidelines.

**Example guideline:**

```
"Use progressive visualization - start with summary views and let users drill down into details"
```

When applied, every widget the AI generates follows this pattern.

## Creating Widget Guidelines

<Steps>
  <Step title="Access Widget Guidelines">
    Open **Widget Guidelines** in Agent Management Studio
  </Step>

  <Step title="Define your rules">
    Write clear instructions about how widgets should be structured and behave
  </Step>

  <Step title="Add specific requirements">
    Include accessibility needs, data visualization preferences, and interaction patterns
  </Step>

  <Step title="Save and apply">
    Save your guidelines to make them active
  </Step>
</Steps>

### Example Widget Guidelines

**Data Visualization:**

```
Always use progressive disclosure for complex data. Start with high-level 
summaries and provide drill-down capabilities for detailed views.
```

**Accessibility:**

```
Ensure all interactive elements have minimum touch targets of 44x44 pixels. 
Maintain WCAG AA contrast ratios for all text.
```

**Component Preferences:**

```
Use card layouts for collections of related information. Include clear 
call-to-action buttons at the bottom of each card.
```

### Widget Guidelines

**Be specific and actionable.** Vague guidelines like "make it look good" don't help. Specific instructions like "use card layouts with 16px padding" produce consistent results.

**Document your decisions.** Keep notes on why you chose certain patterns. This helps when training new team members or revisiting decisions later.

**Iterate based on usage.** As you build more widgets, refine your guidelines based on what works well and what doesn't.

**Balance flexibility and consistency.** Guidelines should provide structure without being so rigid that they prevent good design solutions.

## Troubleshooting

### Design System not appearing in SDK

**Possible causes:**

* Design System code not copied to SDK initialization
* SDK not redeployed after adding Design System
* Code syntax error in SDK configuration

**Solution:** Verify the Design System code is correctly pasted in `mindset.init()`. Check browser console for errors. Redeploy your SDK.

### Widgets using wrong colors

**Possible causes:**

* Widget uses hardcoded colors instead of theme variables
* SDK using different Design System than expected
* Design System code not updated in SDK

**Solution:** Check which Design System your SDK is using. Verify the widget uses theme variables, not hardcoded colors. Update and redeploy SDK if needed.

### Changes in Agent Management Studio not reflected in production

**Possible causes:**

* Design System changes only apply to Agent Management Studio automatically
* SDK hasn't been updated with new Design System code

**Solution:** This is expected behavior. Copy the updated Design System code from the Code tab and paste it into your SDK initialization. Redeploy your SDK.

### Widget Guidelines not being followed

**Possible causes:**

* Guidelines are too vague or contradictory
* Guidelines weren't saved or applied
* Widget was generated before guidelines were created

**Solution:** Make guidelines more specific and actionable. Verify guidelines are saved and active. Regenerate the widget to apply current guidelines.

## Prerequisites

Before using Design System:

* **SDK 3.0** - Design System is only available in SDK 3
* **Agent Management Studio access** - Required to create and manage Design Systems

## Next Steps

<CardGroup cols={2}>
  <Card title="Widget Studio" icon="paintbrush" href="https://docs.mindset.ai/features/build/widget-studio">
    Build widgets that automatically use your Design System
  </Card>
</CardGroup>