> ## 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: Widget Editor Guide

> Detailed guide to building and iterating on widgets

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

The Widget Editor is your workspace for creating and refining widgets. This guide covers all the tools and techniques you need to build production-ready widgets efficiently.

## Widget Editor Overview

The Widget Editor has three main tabs plus additional tools for previewing and publishing:

<Tabs>
  <Tab title="Main Tabs">
    * **Assistant** - Chat with AI to generate and modify your widget
    * **Code** - View and copy the MDX code for your widget
    * **Data** - See the data structure your tool provides
  </Tab>

  <Tab title="Additional Tools">
    * **Examples** - Browse and copy prompts from example widgets
    * **Preview** - See your widget on desktop/mobile, light/dark modes
    * **Design System** - Apply your brand colors
    * **Publish** - Review checklist and publish when ready
  </Tab>
</Tabs>

## Assistant Tab: Building with AI

### How the Widget Editor Agent Works

The Agent generates MDX code based on your natural language descriptions. You don't need to know how to code - just describe what you want.

**What Happens When You Send a Message:**

<Steps>
  <Step title="Type and send">
    You type your request and hit send
  </Step>

  <Step title="Processing status">
    Status shows "Sending request..."
  </Step>

  <Step title="Widget updates">
    Widget updates automatically in the preview
  </Step>

  <Step title="Changes appear">
    No reply message appears - changes just show up
  </Step>
</Steps>

<Note>
  We're adding conversational responses soon. For now, just check the preview to see if your changes worked.
</Note>

### Writing Effective Prompts

The key to great results is being specific about what you want.

**Good prompt structure:**\
\[Action] + \[Component] + \[Visual details] + \[Interaction behavior]

**Examples:**

<Tabs>
  <Tab title="Be Descriptive">
    **Good:**\
    "Create a quiz widget with one question displayed at a time, four multiple choice buttons in a 2x2 grid, and a submit button at the bottom"

    **Not as good:**\
    "Make a quiz"
  </Tab>

  <Tab title="Include Visual Details">
    **Good:**\
    "Add a progress bar at the top showing question 3 of 10, make it blue to match our brand"

    **Not as good:**\
    "Add progress"
  </Tab>

  <Tab title="Specify Interactions">
    **Good:**\
    "When the user clicks an answer, highlight it in green and disable the other options"

    **Not as good:**\
    "Make it interactive"
  </Tab>
</Tabs>

### Using the Examples Library

The fastest way to build is starting with an example.

**To Access:**

1. Click the **Examples** button in the Editor
2. Browse by category or search by keyword
3. Click on any example to see details

**Categories Include:**

<AccordionGroup>
  <Accordion title="Data Visualization">
    Charts, graphs, dashboards
  </Accordion>

  <Accordion title="Feedback & Communication">
    Forms, surveys, notifications
  </Accordion>

  <Accordion title="Data Display">
    Lists, cards, tables
  </Accordion>

  <Accordion title="User Input">
    Forms, selectors, pickers
  </Accordion>

  <Accordion title="Navigation & Controls">
    Menus, tabs, buttons
  </Accordion>

  <Accordion title="Scheduling">
    Calendars, timelines
  </Accordion>

  <Accordion title="Surveys and Assessments">
    Quizzes, polls
  </Accordion>

  <Accordion title="Text & Documents">
    Readers, previews
  </Accordion>
</AccordionGroup>

**To Use an Example:**

<Steps>
  <Step title="Find an example">
    Find an example close to what you want
  </Step>

  <Step title="Copy Prompt">
    Click Copy Prompt
  </Step>

  <Step title="Return to Assistant">
    Return to Assistant tab
  </Step>

  <Step title="Paste the prompt">
    Paste the prompt
  </Step>

  <Step title="Send it">
    Send it
  </Step>

  <Step title="Modify from there">
    Modify from there
  </Step>
</Steps>

<Tip>
  Even if an example isn't perfect, it's often faster to start with something close and modify it than to start from scratch.
</Tip>

### Iterating on Your Widget

**Making Changes:**

Just chat naturally with the Agent:

* "Make the buttons larger"
* "Change the color scheme to use our brand purple"
* "Add icons next to each option"
* "Move the submit button to the right side"
* "Add a congratulations message when the quiz is complete"

**Each Message Creates a New Version:**

* Your edit history is saved as versions
* You can always revert to a previous version
* See the Versions tab for full history

<Warning>
  **Current Limitation:** If you switch to another tab (Code, Data, etc.) and come back, your message history will be gone. We're fixing this soon. For now: Keep notes externally if you switch tabs, or try to complete edits in one session.
</Warning>

### Working with Tool Data

Your widget displays data from your tool. The Data tab shows you what information your tool provides.

**To Reference Tool Data in Your Prompts:**

"Show the course title, description, and rating from the tool data"

"Display the quiz questions as a list with the question text and four answer options"

"Create a card for each result that shows the thumbnail image, title, and price"

The Agent understands your tool's data structure and will map it correctly.

## Code Tab: Viewing and Copying MDX

### What's in the Code Tab

The Code tab shows the MDX (Markdown + JSX) code that powers your widget. You don't need to understand this code to use Widget Studio, but it's here if you want to:

* Copy the code to use elsewhere
* Share it with developers
* Keep a backup

### Copying Your Code

<Steps>
  <Step title="Go to the Code tab">
    Navigate to the Code tab
  </Step>

  <Step title="Click the Copy button">
    Click the Copy button
  </Step>

  <Step title="Code is copied">
    Your MDX code is now on your clipboard
  </Step>
</Steps>

You can paste this into:

* External code editors
* Other AI tools for further refinement
* Documentation for your team

### Import Function (Coming Soon)

You'll see an **Import** button in the Code tab. This doesn't work yet - we're enabling it soon.

<Tip>
  **For Now:** If you have MDX code you want to use, paste it directly into the Agent chat and it should process it.
</Tip>

## Data Tab: Understanding Tool Output

### What the Data Tab Shows

The Data tab displays the structure of data your tool returns. This helps you understand what information you have available to display in your widget.

**Example Data Structure:**

```json theme={null}
{
  "courses": [
    {
      "title": "Introduction to Python",
      "description": "Learn Python basics",
      "rating": 4.5,
      "thumbnail": "https://...",
      "duration": "6 weeks"
    }
  ]
}
```

### Using Data in Your Widget

When you describe your widget to the Agent, reference the data fields you see:

"Show each course as a card with the thumbnail image, title, rating, and duration. Add an 'Enroll Now' button for each."

The Agent maps your description to the actual data structure automatically.

## Preview: Testing Your Widget

### Preview Modes

<Tabs>
  <Tab title="Device Preview">
    * **Desktop** - How your widget looks in the full-width agent chat
    * **Mobile** - How it appears on mobile devices
  </Tab>

  <Tab title="Theme Preview">
    * **Light Mode** - Default light theme
    * **Dark Mode** - Dark theme appearance
  </Tab>
</Tabs>

**Why Preview Matters:**

* Text that's readable on desktop might be too small on mobile
* Colors that work in light mode might not contrast well in dark mode
* Interactive elements need to be touch-friendly on mobile

### What to Check

<AccordionGroup>
  <Accordion title="On Desktop">
    * Does the layout use space effectively?
    * Are buttons and interactive elements easy to click?
    * Is text easily readable?
  </Accordion>

  <Accordion title="On Mobile">
    * Does content fit without horizontal scrolling?
    * Are touch targets large enough (buttons, links)?
    * Is text still readable at smaller sizes?
  </Accordion>

  <Accordion title="In Light Mode">
    * Is contrast sufficient for readability?
    * Do colors align with your brand?
  </Accordion>

  <Accordion title="In Dark Mode">
    * Does text remain readable?
    * Do colors still look good?
    * Are borders and dividers visible?
  </Accordion>
</AccordionGroup>

<Tip>
  Preview your widget in all modes before publishing. What looks great on desktop in light mode might be unreadable on mobile in dark mode.
</Tip>

## Design System: Applying Your Brand

### What Design Systems Do

Design systems automatically apply your brand colors throughout your widget. When you select a design system, colors propagate to:

* Buttons
* Backgrounds
* Text highlights
* Borders
* Interactive elements

### Changing Design Systems

<Steps>
  <Step title="Click the Design System dropdown">
    Click the Design System dropdown
  </Step>

  <Step title="Select from your configured design systems">
    Select from your configured design systems
  </Step>

  <Step title="Preview updates immediately">
    Preview updates immediately
  </Step>

  <Step title="Switch between systems">
    Switch between systems to see which looks best
  </Step>
</Steps>

<Note>
  Design systems are configured at the platform level. To learn more about Design System set up see here \[doc link coming soon]
</Note>

## Versions: Managing Widget History

### How Versioning Works

Every time you edit your widget and the Agent generates new code, a new version is created automatically.

**Version Information:**

* Version number (0.1, 0.2, 0.3, etc.)
* Timestamp of creation
* Status (Published, Unpublished, Latest)

### Viewing Version History

<Steps>
  <Step title="Go to the Versions tab">
    Go to the Versions tab
  </Step>

  <Step title="See all versions">
    See all versions listed with timestamps
  </Step>

  <Step title="Click on any version">
    Click on any version to view its code
  </Step>
</Steps>

### Reverting to a Previous Version

To go back to an earlier version:

<Steps>
  <Step title="Unpublish your current widget">
    Unpublish your current widget
  </Step>

  <Step title="Go to Versions tab">
    Go to Versions tab
  </Step>

  <Step title="Find the version you want">
    Find the version you want
  </Step>

  <Step title="Click Promote to Latest">
    Click Promote to Latest
  </Step>

  <Step title="Go to Publish tab">
    Go to Publish tab
  </Step>

  <Step title="Click Publish">
    Click Publish
  </Step>
</Steps>

<Warning>
  Only the latest version can be published. To publish an older version, you must first promote it to latest.
</Warning>

## Publishing: Making Your Widget Live

### Publishing Checklist

Before you can publish, certain requirements must be met:

* ✓ Widget Name - Must have a name
* ✓ Widget Description - Must have a description
* ✓ Widget Mode - Display or Standalone selected
* ✓ Initial Version - At least version 0.1 created
* ✓ Widget Code - MDX code generated
* ✓ Widget Compiles - Code compiles successfully

Most of these are automatically checked as you build. If something's missing, you'll see what needs attention.

### Publishing Your Widget

<Steps>
  <Step title="Go to the Publish tab">
    Go to the Publish tab
  </Step>

  <Step title="Review the checklist">
    Review the checklist - all items should be checked
  </Step>

  <Step title="Click Publish">
    Click Publish
  </Step>

  <Step title="Your widget is now live!">
    Your widget is now live!
  </Step>
</Steps>

**What Happens When Published:**

* Widget becomes active in your agent
* When the agent calls your tool, the widget displays automatically
* End users see your widget in the agent chat

### Unpublishing

To take a widget offline:

<Steps>
  <Step title="Open the widget">
    Open the widget
  </Step>

  <Step title="Go to Publish tab">
    Go to Publish tab
  </Step>

  <Step title="Click Unpublish">
    Click Unpublish
  </Step>

  <Step title="Tool continues to work">
    Tool continues to work, but widget won't display
  </Step>
</Steps>

**When to Unpublish:**

* Making major edits
* Widget isn't working as expected
* Testing changes before republishing

## Practical Examples

### Example 1: Building a Quiz Widget

<Tabs>
  <Tab title="Initial prompt">
    "Create a quiz widget that shows one question at a time with four multiple choice answers. Include a progress indicator and a submit button."
  </Tab>

  <Tab title="Refining the design">
    "Make the answer buttons larger with more padding. Add a blue progress bar at the top showing question number out of total."
  </Tab>

  <Tab title="Adding interactions">
    "When the user selects an answer, highlight it in green and disable the other options. Show a 'Next Question' button after they select."
  </Tab>

  <Tab title="Final polish">
    "Add a completion screen that shows their score as a percentage with a congratulations message. Include a 'Retake Quiz' button."
  </Tab>
</Tabs>

### Example 2: Building a Course Catalog

<Tabs>
  <Tab title="Initial prompt">
    "Build a course catalog that displays courses as cards in a grid. Each card should show the thumbnail, title, rating, and duration."
  </Tab>

  <Tab title="Improving the layout">
    "Change to a 3-column grid on desktop and single column on mobile. Add more spacing between cards."
  </Tab>

  <Tab title="Enhancing visuals">
    "Display the rating as yellow stars instead of numbers. Add a subtle shadow to each card and a hover effect that slightly elevates it."
  </Tab>

  <Tab title="Adding functionality">
    "Include an 'Enroll Now' button on each card. When hovering over a course, show the number of students already enrolled."
  </Tab>
</Tabs>

### Example 3: Building a Booking Calendar

<Tabs>
  <Tab title="Initial prompt">
    "Make a calendar widget for booking appointments. Show available time slots as buttons."
  </Tab>

  <Tab title="Adding structure">
    "Organize time slots by day of the week. Show morning, afternoon, and evening sections clearly labeled."
  </Tab>

  <Tab title="Improving interaction">
    "When a user clicks a time slot, highlight it and show a confirmation panel asking them to confirm or cancel. Display the selected date and time clearly."
  </Tab>

  <Tab title="Final touches">
    "Add a small calendar icon next to each time slot. Disable past time slots and show them in gray. Add a success message after booking is confirmed."
  </Tab>
</Tabs>

## Best Practices

### Building Effective Widgets

<CardGroup cols={3}>
  <Card title="Start Simple" icon="seedling">
    Get basic functionality working first. Add visual polish and complexity later. Iterate gradually.
  </Card>

  <Card title="Test Thoroughly" icon="vial">
    Preview on desktop and mobile. Check light and dark modes. Test with real tool data if possible.
  </Card>

  <Card title="Consider Your Users" icon="users">
    Make touch targets large enough for mobile. Use clear, readable text. Provide visual feedback for interactions.
  </Card>
</CardGroup>

### Managing Your Workflow

<AccordionGroup>
  <Accordion title="Keep Sessions Focused">
    * Complete related edits in one session
    * Don't switch tabs unnecessarily (message history will be lost)
    * Save/publish when you reach a good stopping point
  </Accordion>

  <Accordion title="Use Version Control">
    * Major milestones = good time to note the version
    * Can always revert if needed
    * Promotes a safety net for experimentation
  </Accordion>

  <Accordion title="Backup Important Work">
    * Copy MDX code for critical widgets
    * Keep external notes on design decisions
    * Document what prompts worked well
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Problem: Agent doesn't seem to understand my request">
    **Try:**

    * Be more specific and descriptive
    * Reference the data structure from the Data tab
    * Use an example from the library as a starting point
  </Accordion>

  <Accordion title="Problem: Widget looks good on desktop but broken on mobile">
    **Try:**

    * Ask the Agent: "Make this responsive for mobile devices"
    * Simplify the layout for smaller screens
    * Test preview on Mobile mode as you iterate
  </Accordion>

  <Accordion title="Problem: Colors don't match my brand">
    **Try:**

    * Switch Design Systems
    * Ask the Agent: "Use colors from the \[System Name] design system"
    * Contact your team if you need a new design system created
  </Accordion>

  <Accordion title="Problem: I lost my message history">
    This happens when you switch tabs. For now:

    * Keep external notes
    * Try to complete edits in one session
    * We're fixing this soon
  </Accordion>
</AccordionGroup>

<Info>
  **Questions?** Contact your Mindset AI team.
</Info>