Skip to main content

​
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 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.
SDK 3 Required: Design System is available exclusively in SDK 3.

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

​
Creating a Design System

1

Navigate to Design Systems

Open Design Systems in Agent Management Studio
2

Create new Design System

Click New Design System and give it a descriptive name
3

Select seed color

Choose your primary brand color. Material Design 3 automatically generates a complete color palette from this single color.
4

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
5

Set typography

Configure font family, sizes, weights, and spacing
6

Choose mode

Select Light or Dark mode
7

Preview

See how your Design System looks across different components
8

Save

Save your Design System

​
Implementing Design Systems in Your SDK

Critical: Your SDK does NOT automatically use your Default Design System. You must manually implement it.

​
Implementation Steps

1

Customize Design System

Customize your Design System in Agent Management Studio
2

Copy the code

Go to the Code tab in your Design System and copy the entire code block
3

Paste into SDK initialization

Paste the code into your SDK initialization:
mindset.init({
  // Your Design System code here
  theme: {
    brightness: 'light',
    primary: '#6750A4',
    secondary: '#625B71',
    // ... rest of your Design System configuration
  }
});
4

Deploy your SDK

Deploy your SDK with the new configuration
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:
LocationUpdates Automatically?Action Required
Agent Management Studio✅ YesChanges apply immediately to preview, dashboard, demo pages
Live SDK❌ NoYou must copy the new code, update SDK implementation, and redeploy
Always test Design System changes in Agent Management Studio before updating your production SDK.

​
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
This is ONLY for preview. The widget will use whatever Design System your SDK provides in production.

​
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

// ❌ Uses whatever primary color the SDK defines
color: var(--md-sys-color-primary)

// ✅ Always this exact color
color: #FF5733
This is advanced customization. Contact [email protected] if you need help.

​
Creating Multiple Design Systems

You can create multiple Design Systems for different purposes.

​
Common Use Cases

Preview Options

Preview different color schemes before deciding on your final brand

Multi-Tenant Branding

Different Design System per client or tenant

Environments

Separate Design Systems for development vs. production

Accessibility Testing

Test different contrast levels and readability

​
Using Multiple Design Systems

1

Create multiple systems

Create as many Design Systems as needed in Agent Management Studio
2

Preview and compare

Switch between them in Agent Management Studio to preview
3

Select for production

Copy the code from whichever one you want to use in production
4

Implement in SDK

Paste that code into your SDK implementation
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.

​
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

1

Access Widget Guidelines

Open Widget Guidelines in Agent Management Studio
2

Define your rules

Write clear instructions about how widgets should be structured and behave
3

Add specific requirements

Include accessibility needs, data visualization preferences, and interaction patterns
4

Save and apply

Save your guidelines to make them active

​
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

Widget Studio

Build widgets that automatically use your Design System