widget-design

name	widget-design
description	Best practices for designing UI widgets in xmcp. Use when creating interactive widgets for GPT Apps or MCP Apps, choosing between React components and template literals, designing widget layouts, handling state and data fetching, or troubleshooting widget rendering issues.

Widget Design Best Practices

Decision Framework

Platform Selection

Choose based on target client:

• GPT Apps: Target is ChatGPT. Requires _meta.openai with widgetAccessible: true.
• MCP Apps: Target is any ext-apps client. Minimal config, works automatically.

Handler Type Selection

Scenario	Handler	Reason
User interaction needed (buttons, inputs)	React (.tsx)	State management with hooks
Display external widget library	Template literal	Just load scripts/styles
Dynamic content from tool params	React	Props flow naturally
Static HTML with no state	Template literal	Simpler, less overhead

Rule of thumb: If unsure, start with React. Converting later is harder than starting simple.

Widget Design Principles

1. Widgets Are Not Web Apps

Widgets render inline in conversations. Design constraints:

• No navigation: Single-screen experience only
• Limited width: ~600-700px max in most clients
• Sandboxed: External resources need CSP declarations
• : May be re-rendered, don't rely on persistence