1# Widget UI Guidelines
2 
3Build widgets that adapt to themes, look professional, and provide great user experience.
4 
5**Key topics:** Theme support, light/dark mode, responsive layouts, accessibility, CSS best practices
6 
7---
8 
9## Theme Support with useWidgetTheme()
10 
11Widgets should adapt to the user's theme (light/dark mode):
12 
13```tsx
14import { McpUseProvider, useWidget, useWidgetTheme, type WidgetMetadata } from "mcp-use/react";
15import { z } from "zod";
16 
17export const widgetMetadata: WidgetMetadata = {
18  description: "Theme-aware widget",
19  props: z.object({
20    message: z.string()
21  }),
22  exposeAsTool: false
23};
24 
25export default function ThemedWidget() {
26  const { props, isPending } = useWidget();
27  const theme = useWidgetTheme();
28 
29  if (isPending) {
30    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
31  }
32 
33  return (
34    <McpUseProvider autoSize>
35      <div style={{
36        padding: 20,
37        backgroundColor: theme === "dark" ? "#1e1e1e" : "#ffffff",
38        color: theme === "dark" ? "#ffffff" : "#000000"
39      }}>
40        <p>{props.message}</p>
41      </div>
42    </McpUseProvider>
43  );
44}
45```
46 
47**useWidgetTheme() returns:** `"light"` or `"dark"`
48 
49---
50 
51## Theme-Aware Colors
52 
53Define color palettes for both themes:
54 
55```tsx
56const theme = useWidgetTheme();
57 
58const colors = {
59  background: theme === "dark" ? "#1e1e1e" : "#ffffff",
60  text: theme === "dark" ? "#e0e0e0" : "#1a1a1a",
61  border: theme === "dark" ? "#404040" : "#e0e0e0",
62  primary: theme === "dark" ? "#4a9eff" : "#0066cc",
63  secondary: theme === "dark" ? "#6c757d" : "#6c757d",
64  hover: theme === "dark" ? "#2a2a2a" : "#f5f5f5",
65  error: theme === "dark" ? "#ff6b6b" : "#dc3545",
66  success: theme === "dark" ? "#51cf66" : "#28a745"
67};
68 
69return (
70  <McpUseProvider autoSize>
71    <div style={{
72      backgroundColor: colors.background,
73      color: colors.text,
74      border: `1px solid ${colors.border}`
75    }}>
76      {/* Your content */}
77    </div>
78  </McpUseProvider>
79);
80```
81 
82Or extract to a hook:
83 
84```tsx
85function useColors() {
86  const theme = useWidgetTheme();
87 
88  return {
89    background: theme === "dark" ? "#1e1e1e" : "#ffffff",
90    text: theme === "dark" ? "#e0e0e0" : "#1a1a1a",
91    border: theme === "dark" ? "#404040" : "#e0e0e0",
92    primary: theme === "dark" ? "#4a9eff" : "#0066cc",
93    hover: theme === "dark" ? "#2a2a2a" : "#f5f5f5",
94    error: theme === "dark" ? "#ff6b6b" : "#dc3545"
95  };
96}
97 
98export default function ThemedWidget() {
99  const colors = useColors();
100  // ... rest of component
101}
102```
103 
104---
105 
106## Responsive Layouts
107 
108### Grid Layout
109 
110```tsx
111<div style={{
112  display: "grid",
113  gridTemplateColumns: "repeat(auto-fill, minmax(200px, 1fr))",
114  gap: 16,
115  padding: 20
116}}>
117  {props.items.map(item => (
118    <div key={item.id} style={{
119      padding: 12,
120      border: `1px solid ${colors.border}`,
121      borderRadius: 8
122    }}>
123      {item.name}
124    </div>
125  ))}
126</div>
127```
128 
129### Flexbox Layout
130 
131```tsx
132<div style={{
133  display: "flex",
134  gap: 16,
135  padding: 20,
136  flexWrap: "wrap"
137}}>
138  {props.items.map(item => (
139    <div key={item.id} style={{
140      flex: "1 1 200px",
141      padding: 12,
142      border: `1px solid ${colors.border}`
143    }}>
144      {item.name}
145    </div>
146  ))}
147</div>
148```
149 
150### Two-Column Layout
151 
152```tsx
153<div style={{
154  display: "flex",
155  gap: 16,
156  padding: 20
157}}>
158  {/* Sidebar */}
159  <div style={{ flex: "0 0 250px" }}>
160    {/* Navigation or filters */}
161  </div>
162 
163  {/* Main content */}
164  <div style={{ flex: 1 }}>
165    {/* Primary content */}
166  </div>
167</div>
168```
169 
170---
171 
172## Button Styles
173 
174Theme-aware buttons:
175 
176```tsx
177const theme = useWidgetTheme();
178 
179const buttonStyle: React.CSSProperties = {
180  padding: "8px 16px",
181  border: "none",
182  borderRadius: 4,
183  cursor: "pointer",
184  fontSize: 14,
185  fontWeight: 500,
186  backgroundColor: theme === "dark" ? "#4a9eff" : "#0066cc",
187  color: "#ffffff"
188};
189 
190const secondaryButtonStyle: React.CSSProperties = {
191  ...buttonStyle,
192  backgroundColor: "transparent",
193  border: `1px solid ${theme === "dark" ? "#404040" : "#e0e0e0"}`,
194  color: theme === "dark" ? "#e0e0e0" : "#1a1a1a"
195};
196 
197return (
198  <McpUseProvider autoSize>
199    <div>
200      <button style={buttonStyle}>Primary Action</button>
201      <button style={secondaryButtonStyle}>Secondary</button>
202    </div>
203  </McpUseProvider>
204);
205```
206 
207### Button States
208 
209```tsx
210const [hovered, setHovered] = useState(false);
211 
212<button
213  style={{
214    padding: "8px 16px",
215    backgroundColor: hovered ? (theme === "dark" ? "#5aa8ff" : "#0052a3") : (theme === "dark" ? "#4a9eff" : "#0066cc"),
216    color: "#ffffff",
217    border: "none",
218    borderRadius: 4,
219    cursor: "pointer",
220    transition: "background-color 0.2s"
221  }}
222  onMouseEnter={() => setHovered(true)}
223  onMouseLeave={() => setHovered(false)}
224>
225  Hover Me
226</button>
227```
228 
229---
230 
231## Card Components
232 
233```tsx
234const theme = useWidgetTheme();
235 
236const cardStyle: React.CSSProperties = {
237  padding: 16,
238  border: `1px solid ${theme === "dark" ? "#404040" : "#e0e0e0"}`,
239  borderRadius: 8,
240  backgroundColor: theme === "dark" ? "#1e1e1e" : "#ffffff",
241  color: theme === "dark" ? "#e0e0e0" : "#1a1a1a"
242};
243 
244return (
245  <McpUseProvider autoSize>
246    <div style={{ padding: 20 }}>
247      {props.items.map(item => (
248        <div key={item.id} style={{
249          ...cardStyle,
250          marginBottom: 12
251        }}>
252          <h3 style={{ margin: "0 0 8px 0" }}>{item.title}</h3>
253          <p style={{ margin: 0, color: theme === "dark" ? "#b0b0b0" : "#666" }}>
254            {item.description}
255          </p>
256        </div>
257      ))}
258    </div>
259  </McpUseProvider>
260);
261```
262 
263---
264 
265## Typography
266 
267```tsx
268const theme = useWidgetTheme();
269 
270<div style={{ padding: 20 }}>
271  {/* Heading */}
272  <h1 style={{
273    fontSize: 24,
274    fontWeight: 600,
275    margin: "0 0 16px 0",
276    color: theme === "dark" ? "#ffffff" : "#1a1a1a"
277  }}>
278    Title
279  </h1>
280 
281  {/* Subheading */}
282  <h2 style={{
283    fontSize: 18,
284    fontWeight: 500,
285    margin: "0 0 12px 0",
286    color: theme === "dark" ? "#e0e0e0" : "#333"
287  }}>
288    Subtitle
289  </h2>
290 
291  {/* Body text */}
292  <p style={{
293    fontSize: 14,
294    lineHeight: 1.5,
295    margin: "0 0 12px 0",
296    color: theme === "dark" ? "#b0b0b0" : "#666"
297  }}>
298    Body content here
299  </p>
300 
301  {/* Small text */}
302  <span style={{
303    fontSize: 12,
304    color: theme === "dark" ? "#808080" : "#999"
305  }}>
306    Small text or metadata
307  </span>
308</div>
309```
310 
311---
312 
313## Form Inputs
314 
315```tsx
316const theme = useWidgetTheme();
317 
318const inputStyle: React.CSSProperties = {
319  padding: 8,
320  fontSize: 14,
321  border: `1px solid ${theme === "dark" ? "#404040" : "#d0d0d0"}`,
322  borderRadius: 4,
323  backgroundColor: theme === "dark" ? "#2a2a2a" : "#ffffff",
324  color: theme === "dark" ? "#e0e0e0" : "#1a1a1a",
325  outline: "none"
326};
327 
328<form style={{ padding: 20 }}>
329  <label style={{
330    display: "block",
331    marginBottom: 4,
332    fontSize: 14,
333    fontWeight: 500,
334    color: theme === "dark" ? "#e0e0e0" : "#333"
335  }}>
336    Name
337  </label>
338  <input
339    type="text"
340    style={inputStyle}
341    placeholder="Enter name..."
342  />
343 
344  <label style={{ display: "block", marginTop: 12, marginBottom: 4 }}>
345    Description
346  </label>
347  <textarea
348    style={{
349      ...inputStyle,
350      width: "100%",
351      minHeight: 80,
352      resize: "vertical"
353    }}
354    placeholder="Enter description..."
355  />
356</form>
357```
358 
359---
360 
361## Lists
362 
363```tsx
364const theme = useWidgetTheme();
365 
366<ul style={{
367  listStyle: "none",
368  padding: 0,
369  margin: 0
370}}>
371  {props.items.map(item => (
372    <li
373      key={item.id}
374      style={{
375        padding: 12,
376        borderBottom: `1px solid ${theme === "dark" ? "#2a2a2a" : "#f0f0f0"}`,
377        cursor: "pointer",
378        transition: "background-color 0.15s"
379      }}
380      onMouseEnter={(e) => {
381        e.currentTarget.style.backgroundColor = theme === "dark" ? "#2a2a2a" : "#f5f5f5";
382      }}
383      onMouseLeave={(e) => {
384        e.currentTarget.style.backgroundColor = "transparent";
385      }}
386    >
387      {item.name}
388    </li>
389  ))}
390</ul>
391```
392 
393---
394 
395## Badges and Tags
396 
397```tsx
398const theme = useWidgetTheme();
399 
400const badgeStyle: React.CSSProperties = {
401  display: "inline-block",
402  padding: "4px 8px",
403  fontSize: 12,
404  fontWeight: 500,
405  borderRadius: 12,
406  backgroundColor: theme === "dark" ? "#2a4a6a" : "#e3f2fd",
407  color: theme === "dark" ? "#4a9eff" : "#0066cc"
408};
409 
410<div>
411  <span style={badgeStyle}>New</span>
412  <span style={{ ...badgeStyle, marginLeft: 8 }}>Featured</span>
413</div>
414```
415 
416---
417 
418## Loading States
419 
420```tsx
421const theme = useWidgetTheme();
422 
423if (isPending) {
424  return (
425    <McpUseProvider autoSize>
426      <div style={{
427        padding: 40,
428        textAlign: "center",
429        color: theme === "dark" ? "#808080" : "#999"
430      }}>
431        <div style={{
432          width: 40,
433          height: 40,
434          border: `4px solid ${theme === "dark" ? "#404040" : "#e0e0e0"}`,
435          borderTop: `4px solid ${theme === "dark" ? "#4a9eff" : "#0066cc"}`,
436          borderRadius: "50%",
437          margin: "0 auto 16px",
438          animation: "spin 1s linear infinite"
439        }} />
440        <p>Loading...</p>
441      </div>
442    </McpUseProvider>
443  );
444}
445```
446 
447Add spin animation:
448 
449```tsx
450<style>
451  {`
452    @keyframes spin {
453      0% { transform: rotate(0deg); }
454      100% { transform: rotate(360deg); }
455    }
456  `}
457</style>
458```
459 
460---
461 
462## Empty States
463 
464```tsx
465const theme = useWidgetTheme();
466 
467{props.items.length === 0 && (
468  <div style={{
469    padding: 40,
470    textAlign: "center",
471    color: theme === "dark" ? "#808080" : "#999"
472  }}>
473    <div style={{
474      fontSize: 48,
475      marginBottom: 16,
476      opacity: 0.5
477    }}>
478      📭
479    </div>
480    <h3 style={{
481      fontSize: 18,
482      fontWeight: 500,
483      margin: "0 0 8px 0",
484      color: theme === "dark" ? "#b0b0b0" : "#666"
485    }}>
486      No items yet
487    </h3>
488    <p style={{
489      fontSize: 14,
490      margin: 0,
491      color: theme === "dark" ? "#808080" : "#999"
492    }}>
493      Get started by creating your first item
494    </p>
495  </div>
496)}
497```
498 
499---
500 
501## Error States
502 
503```tsx
504const theme = useWidgetTheme();
505 
506{error && (
507  <div style={{
508    padding: 12,
509    marginBottom: 16,
510    backgroundColor: theme === "dark" ? "#3d1f1f" : "#ffebee",
511    color: theme === "dark" ? "#ff6b6b" : "#c62828",
512    border: `1px solid ${theme === "dark" ? "#6b2a2a" : "#ffcdd2"}`,
513    borderRadius: 4
514  }}>
515    <strong>Error:</strong> {error}
516  </div>
517)}
518```
519 
520---
521 
522## Icons
523 
524Use Unicode emojis or SVG icons:
525 
526```tsx
527// Emojis
528<span style={{ fontSize: 24, marginRight: 8 }}>⚙️</span>
529<span style={{ fontSize: 20 }}>✓</span>
530<span>❌</span>
531 
532// SVG icon
533<svg width="20" height="20" viewBox="0 0 20 20" fill="currentColor">
534  <path d="M10 15l-5.878 3.09 1.123-6.545L.489 6.91l6.572-.955L10 0l2.939 5.955 6.572.955-4.756 4.635 1.123 6.545z"/>
535</svg>
536```
537 
538---
539 
540## Spacing Guidelines
541 
542```tsx
543// Consistent spacing units
544const spacing = {
545  xs: 4,
546  sm: 8,
547  md: 12,
548  lg: 16,
549  xl: 20,
550  xxl: 24
551};
552 
553<div style={{
554  padding: spacing.lg,
555  gap: spacing.md
556}}>
557  {/* Content */}
558</div>
559```
560 
561---
562 
563## Accessibility
564 
565### Labels for Inputs
566```tsx
567<label htmlFor="email-input">Email</label>
568<input id="email-input" type="email" />
569```
570 
571### Alt Text for Images
572```tsx
573<img src={item.image} alt={item.name} />
574```
575 
576### Button Labels
577```tsx
578<button aria-label="Delete item">🗑️</button>
579```
580 
581### Keyboard Navigation
582```tsx
583<div
584  tabIndex={0}
585  onKeyDown={(e) => {
586    if (e.key === "Enter" || e.key === " ") {
587      handleClick();
588    }
589  }}
590>
591  Clickable item
592</div>
593```
594 
595---
596 
597## Auto-Size Best Practices
598 
599`<McpUseProvider autoSize>` automatically resizes iframe to content.
600 
601**Tips:**
602- Use `autoSize` for dynamic content
603- Avoid fixed heights unless necessary
604- Widget resizes when content changes
605- Test with varying content sizes
606 
607```tsx
608// ✅ Good - autoSize handles height
609<McpUseProvider autoSize>
610  <div style={{ padding: 20 }}>
611    {/* Dynamic content */}
612  </div>
613</McpUseProvider>
614 
615// ❌ Bad - Fixed height defeats autoSize
616<McpUseProvider autoSize>
617  <div style={{ height: 400, overflow: "auto" }}>
618    {/* Content */}
619  </div>
620</McpUseProvider>
621```
622 
623---
624 
625## Complete Themed Widget
626 
627```tsx
628import { useState } from "react";
629import { McpUseProvider, useWidget, useWidgetTheme, type WidgetMetadata } from "mcp-use/react";
630import { z } from "zod";
631 
632function useColors() {
633  const theme = useWidgetTheme();
634 
635  return {
636    background: theme === "dark" ? "#1e1e1e" : "#ffffff",
637    text: theme === "dark" ? "#e0e0e0" : "#1a1a1a",
638    textSecondary: theme === "dark" ? "#b0b0b0" : "#666",
639    border: theme === "dark" ? "#404040" : "#e0e0e0",
640    hover: theme === "dark" ? "#2a2a2a" : "#f5f5f5",
641    primary: theme === "dark" ? "#4a9eff" : "#0066cc"
642  };
643}
644 
645export const widgetMetadata: WidgetMetadata = {
646  description: "Fully themed product list",
647  props: z.object({
648    products: z.array(z.object({
649      id: z.string(),
650      name: z.string(),
651      price: z.number(),
652      category: z.string()
653    }))
654  }),
655  exposeAsTool: false
656};
657 
658export default function ThemedProductList() {
659  const { props, isPending } = useWidget();
660  const colors = useColors();
661  const [selectedCategory, setSelectedCategory] = useState("all");
662 
663  if (isPending) {
664    return (
665      <McpUseProvider autoSize>
666        <div style={{
667          padding: 40,
668          textAlign: "center",
669          color: colors.textSecondary
670        }}>
671          Loading...
672        </div>
673      </McpUseProvider>
674    );
675  }
676 
677  const categories = ["all", ...new Set(props.products.map(p => p.category))];
678  const filtered = selectedCategory === "all"
679    ? props.products
680    : props.products.filter(p => p.category === selectedCategory);
681 
682  return (
683    <McpUseProvider autoSize>
684      <div style={{
685        padding: 20,
686        backgroundColor: colors.background,
687        color: colors.text
688      }}>
689        <h2 style={{ margin: "0 0 16px 0" }}>Products</h2>
690 
691        {/* Category filters */}
692        <div style={{ marginBottom: 16, display: "flex", gap: 8 }}>
693          {categories.map(cat => (
694            <button
695              key={cat}
696              onClick={() => setSelectedCategory(cat)}
697              style={{
698                padding: "8px 16px",
699                borderRadius: 4,
700                cursor: "pointer",
701                backgroundColor: selectedCategory === cat ? colors.primary : "transparent",
702                color: selectedCategory === cat ? "#fff" : colors.text,
703                border: `1px solid ${selectedCategory === cat ? colors.primary : colors.border}`
704              }}
705            >
706              {cat}
707            </button>
708          ))}
709        </div>
710 
711        {/* Product grid */}
712        <div style={{
713          display: "grid",
714          gridTemplateColumns: "repeat(auto-fill, minmax(200px, 1fr))",
715          gap: 12
716        }}>
717          {filtered.map(product => (
718            <div
719              key={product.id}
720              style={{
721                padding: 12,
722                border: `1px solid ${colors.border}`,
723                borderRadius: 8,
724                backgroundColor: colors.background
725              }}
726            >
727              <h3 style={{ margin: "0 0 4px 0", fontSize: 16 }}>
728                {product.name}
729              </h3>
730              <p style={{ margin: "0 0 8px 0", fontSize: 12, color: colors.textSecondary }}>
731                {product.category}
732              </p>
733              <p style={{ margin: 0, fontSize: 18, fontWeight: "bold", color: colors.primary }}>
734                ${product.price}
735              </p>
736            </div>
737          ))}
738        </div>
739 
740        {filtered.length === 0 && (
741          <div style={{
742            padding: 40,
743            textAlign: "center",
744            color: colors.textSecondary
745          }}>
746            No products in this category
747          </div>
748        )}
749      </div>
750    </McpUseProvider>
751  );
752}
753```
754 
755---
756 
757## Next Steps
758 
759- **Advanced patterns** → [advanced.md](advanced.md)
760- **See examples** → [../patterns/common-patterns.md](../patterns/common-patterns.md)
761