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

# Widget Studio Quickstart Guide

> Build your widget with Mindset AI's Widget Studio

<Info>
  **Beta Feature** - Widget Studio is currently in beta. Widget Studio is only available for SDK 3.0 customers.
</Info>

This guide walks you through creating and publishing your first widget in about 15 minutes. You'll build a course recommendation widget that displays course information with images, ratings, and enrollment buttons.

## Before You Start

**Prerequisites:**

<Steps>
  <Step title="External MCP Connected">
    You need at least one external MCP configured in your Mindset platform. If you don't have one set up yet, follow our MCP Setup Guide.
  </Step>

  <Step title="Tool Tested">
    The tool you want to create a widget for must be tested at least once. When you try to create a widget, you'll be prompted to test the tool if it hasn't been tested yet.
  </Step>

  <Step title="Access to Widget Studio">
    Widget Studio is available in your AMS (Agent Management Studio).
  </Step>
</Steps>

<Tip>
  If your tool isn't tested yet, don't worry—Widget Studio will prompt you to test it first. Just run a quick test and you're ready to go.
</Tip>

## Step 1: Navigate to Widget Studio

1. Open your **AMS (Agent Management Studio)**
2. Click **Widget Studio** in the left navigation
3. Click the **New Widget** button

You'll see the widget configuration screen.

## Step 2: Configure Your Widget

<Tabs>
  <Tab title="Widget Mode">
    Select **Display**—this is production-ready and fully functional.

    <Note>
      Standalone mode is visible but not yet available for publishing. Focus on Display widgets for now.
    </Note>
  </Tab>

  <Tab title="Widget Name">
    Give your widget a clear, descriptive name:

    * Good: "Course Recommendation Widget"
    * Good: "Booking Calendar Widget"
    * Avoid: "Widget 1" or "Test"
  </Tab>

  <Tab title="Description">
    Add a brief description of what this widget does. This helps you remember the widget's purpose and is useful for team documentation.

    *(Optional)*
  </Tab>

  <Tab title="Select Your Tool">
    Choose the MCP tool this widget will display output for.
  </Tab>
</Tabs>

<Warning>
  Once published, when the agent calls this tool, your widget will ALWAYS display. There's no option to show the tool without the widget. To stop showing the widget, you'll need to unpublish or delete it.
</Warning>

## Step 3: Generate Your Widget with AI

This is where Widget Studio's power shows—you'll describe what you want, and the Widget Editor Agent creates it for you.

<Tabs>
  <Tab title="Option A: Use Examples Library">
    ### The fastest way to get started:

    1. Click the **Examples** button
    2. Browse widgets by category:
       * Data Visualization
       * Forms & Surveys
       * Quizzes & Assessments
       * Content Display
       * And more
    3. Find one similar to what you want
    4. Click **Copy Prompt**
    5. Paste into the Agent chat
    6. Hit send

    **Example:** If you want a course list, look for "Course Catalog" or "Product List" examples.
  </Tab>

  <Tab title="Option B: Describe From Scratch">
    ### Just tell the agent what you want in natural language:

    **Examples that work well:**

    "Create a quiz widget that shows questions one at a time with multiple choice answers. Include a progress bar at the top and show the score at the end."

    "Build a course list with images, ratings, duration, and an enroll button for each course. Display courses in a grid layout with 2 columns on desktop."

    "Make a calendar widget for booking appointments. Show available time slots and let users select one. Include a confirmation step before submitting."

    <Tip>
      Be specific—the more detail you provide, the better the result. Include visual details, layout preferences, and interaction behaviors.
    </Tip>
  </Tab>
</Tabs>

### What Happens Next

* The agent processes your request (you'll see "Sending request...")
* Your widget appears in the preview pane automatically
* No reply message comes back—changes just appear

<Note>
  The Widget Editor Agent currently processes requests silently. Check the preview to see your widget. We're adding conversational responses soon.
</Note>

## Step 4: Preview and Refine

### Preview Your Widget

Test your widget across different contexts:

<AccordionGroup>
  <Accordion title="Device Views">
    * Click **Desktop** to see full-width display
    * Click **Mobile** to see mobile appearance
  </Accordion>

  <Accordion title="Theme Views">
    * Toggle **Light Mode** (default)
    * Toggle **Dark Mode** to check contrast and readability
  </Accordion>

  <Accordion title="What to check">
    * Does the layout look good on both desktop and mobile?
    * Is text readable in both light and dark modes?
    * Are buttons and interactive elements properly sized?
    * Does it match your brand's design system?
  </Accordion>
</AccordionGroup>

### Make Changes

To refine your widget, just chat with the Agent:

**Example requests:**

"Make the buttons bigger and add more padding"

"Change the color scheme to use our brand purple"

"Add icons next to each course title"

"Move the enrollment button to the bottom right"

"Add a hover effect on the course cards"

Each change creates a new version automatically. Keep iterating until you're happy with the result.

<Warning>
  **Current limitation:** If you switch to the Code or Data tab and return, your message history will be lost. Complete your edits in one session or keep external notes. This is being fixed soon.
</Warning>

### Apply Your Design System

1. Click the **Design System** dropdown
2. Select from your configured design systems
3. Preview updates immediately
4. Switch between systems to see which looks best

Your brand colors automatically apply to buttons, backgrounds, and interactive elements.

## Step 5: Publish Your Widget

When you're satisfied with your widget:

1. Click the **Publish** tab
2. Review the publishing checklist—most items should be automatically checked:
   * Widget Name ✓
   * Widget Description ✓
   * Widget Mode selected ✓
   * Initial version created ✓
   * Widget code generated ✓
   * Widget compiles successfully ✓
3. Click **Publish**
4. Your widget is now live in your agent!

<Check>
  **Success!** Your widget is now active. Whenever the agent calls this tool, users will see your custom widget instead of plain text output.
</Check>

## Test Your Widget in Action

To see your widget in the agent:

1. Open your agent chat interface
2. Ask a question that would trigger the tool
3. The agent will call the tool and display your widget

**Example:** If you built a course recommendation widget, ask: "Show me available courses" or "What courses do you recommend?"

## What You Built

You just created a production-ready widget that:

* ✅ Displays structured tool data in a custom visual interface
* ✅ Automatically matches your brand's design system
* ✅ Works on desktop and mobile, light and dark modes
* ✅ Shows whenever the agent calls that specific tool

## Tips for Success

### Getting Better Results

**Be descriptive in your prompts:**

* ❌ "Make a quiz widget"
* ✅ "Create a quiz widget that displays one question at a time with 4 multiple choice buttons and shows the score at the end"

**Use the Examples Library:**

* Don't start from scratch if you don't have to
* Find something close and modify it
* Copy prompts from examples to get started faster

**Iterate gradually:**

* Make one change at a time
* Preview after each change
* Build up complexity step by step

### Avoiding Common Issues

<AccordionGroup>
  <Accordion title="One widget per tool">
    * Only create ONE widget for each tool
    * If you want to make changes, edit the existing widget

    <Warning>
      Currently, you can create multiple widgets on one tool, but only the most recently created widget will be active. We're implementing automatic enforcement soon. When that happens, duplicate widgets will be automatically cleaned up, keeping only the latest one. If you have important work in non-active widgets, back up the MDX code from the Code tab.
    </Warning>
  </Accordion>

  <Accordion title="Don't switch widget modes">
    * Once you start generating, don't switch between Display and Standalone
    * This causes unpredictable behavior
    * If you need to change modes, start a new widget from scratch
  </Accordion>

  <Accordion title="Keep your session active">
    * Don't switch tabs while actively editing—you'll lose message history
    * If you need to check something, finish your current edits first
  </Accordion>
</AccordionGroup>

## Managing Your Widget

<Tabs>
  <Tab title="Editing After Publishing">
    1. Go to Widget Studio
    2. Find your widget in the list
    3. Click to open it
    4. Make edits in the Editor tab
    5. Publish the new version when ready
  </Tab>

  <Tab title="Version Control">
    * Every edit creates a new version
    * View all versions in the **Versions** tab
    * To publish an older version:
      1. Unpublish the current version
      2. Go to Versions tab
      3. Click **Promote to Latest** on the version you want
      4. Return to Publish tab and publish
  </Tab>

  <Tab title="Unpublishing">
    To take a widget offline:

    1. Open the widget
    2. Go to **Publish** tab
    3. Click **Unpublish**

    The tool will still work normally, but the widget won't display until you republish.
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Widget Editor Guide" icon="book" href="widget-editor-guide">
    Learn all the features and capabilities of the Widget Editor
  </Card>

  <Card title="Widget Studio Overview" icon="star" href="/features/build/widget-studio">
    Understand what you can build with Widget Studio
  </Card>
</CardGroup>

## Common Questions

<AccordionGroup>
  <Accordion title="Can I create multiple widgets for one tool?">
    You can, but only the most recently created widget will be active. We recommend keeping one widget per tool. Automatic enforcement is coming soon.
  </Accordion>

  <Accordion title="Can I use my own custom code?">
    Not via the Import button yet (coming soon), but you can paste MDX code directly into the Agent chat and it will process it.
  </Accordion>

  <Accordion title="How do I know when my widget will display?">
    Your widget displays whenever the agent calls the tool it's attached to. You don't control when it shows—the agent's LLM decides which tool to call based on the user's request.
  </Accordion>

  <Accordion title="Can I unpublish a widget temporarily?">
    Yes. Open the widget, go to the Publish tab, and click Unpublish. The tool will continue working without displaying the widget.
  </Accordion>
</AccordionGroup>

<Info>
  **Need help?** Contact your Mindset AI account team.
</Info>