+```
+
+## Event Handling Pattern
+
+### Standard onError Handler
+
+```tsx
+const onError = (widgetName: string, error: Error) => {
+ console.error(`${widgetName} error:`, error);
+ // Optional: Show toast notification
+ setToast({type: 'error'});
+};
+```
+
+**EVERY widget MUST have onError callback.**
+
+### Widget-Specific Events
+
+```tsx
+// IncomingTask
+const onIncomingTaskCB = ({task}) => {
+ console.log('Incoming task:', task);
+ setIncomingTasks((prev) => [...prev, task]);
+ playNotificationSound(); // Custom logic
+};
+
+// UserState
+const onAgentStateChangedCB = (newState: AgentState, oldState: AgentState) => {
+ console.log('State changed from', oldState, 'to', newState);
+ setSelectedState(newState);
+};
+
+// CallControl
+const onRecordingToggleCB = ({isRecording, task}) => {
+ console.log('Recording:', isRecording, 'for task:', task.data.interactionId);
+};
+```
+
+## Theme Integration
+
+Theme is controlled by `@momentum-ui`'s `ThemeProvider`:
+
+```tsx
+import {ThemeProvider} from '@momentum-design/components/dist/react';
+
+
+ {/* Your widgets */}
+;
+```
+
+- **Theme provider**: `@momentum-ui` library manages the theme through `ThemeProvider`
+- **Theme storage**: `store.currentTheme` stores the theme as a string ('LIGHT' or 'DARK')
+- **Theme classes**: Theme class names (`mds-theme-stable-lightWebex` / `mds-theme-stable-darkWebex`) are passed to ThemeProvider
+- **Automatic updates**: All widgets automatically respond to theme changes through the ThemeProvider context
+
+**User can toggle theme via UI checkbox** - widgets update automatically through the provider.
+
+## State Management
+
+### When to Use store Directly
+
+```tsx
+// Access store for global state
+import {store} from '@webex/cc-widgets';
+
+// Examples:
+store.currentTask; // Current active task
+store.taskList; // All tasks
+store.incomingTask; // Incoming task
+store.agentState; // Current agent state
+```
+
+### When to Use Local State
+
+```tsx
+// UI-only state (no widget dependency)
+const [showPopup, setShowPopup] = useState(false);
+const [selectedOption, setSelectedOption] = useState('');
+```
+
+## Complete Example: Adding a New Widget
+
+```tsx
+// 1. Import
+import {NewAwesomeWidget} from '@webex/cc-widgets';
+
+// 2. Add to defaultWidgets
+const defaultWidgets = {
+ // ... existing
+ newAwesomeWidget: false,
+};
+
+// 3. Checkbox in widget selector
+
+ New Awesome Widget
+;
+
+// 4. Setup callback handler (if needed)
+const handleCallback = (data) => {
+ console.log('Callback:', data);
+};
+
+// 5. Render with standard layout
+{
+ selectedWidgets.newAwesomeWidget && (
+
+
+
+
+
+ );
+}
+```
+
+## Common Mistakes to AVOID
+
+### ❌ Breaking CSS class structure
+
+```tsx
+// WRONG
+
+
+
+```
+
+### ✅ Correct
+
+```tsx
+
+
+
+```
+
+### ❌ Forgetting defaultWidgets entry
+
+```tsx
+// WRONG - Widget renders immediately, user can't disable
+{
+ selectedWidgets.newWidget &&
;
+}
+// But newWidget not in defaultWidgets!
+```
+
+### ✅ Correct
+
+```tsx
+// In defaultWidgets
+const defaultWidgets = {
+ newWidget: false, // ← MUST ADD HERE
+};
+
+// Then render
+{
+ selectedWidgets.newWidget &&
;
+}
+```
+
+### ❌ Missing error handler
+
+```tsx
+// WRONG
+
+```
+
+### ✅ Correct
+
+```tsx
+
onError('NewWidget', error)} />
+```
+
+### ❌ Hardcoding colors
+
+```tsx
+// WRONG
+
+```
+
+### ✅ Correct
+
+```tsx
+
+```
+
+## Testing Checklist
+
+After adding a new widget:
+
+- [ ] Widget imports without errors
+- [ ] Appears in widget selector checkbox list
+- [ ] Can be enabled/disabled via checkbox
+- [ ] Selection persists in localStorage
+- [ ] Renders with correct layout (box > section-box > fieldset)
+- [ ] Has legend/title
+- [ ] Uses Momentum CSS variables (no hardcoded colors)
+- [ ] Callbacks are handled correctly
+- [ ] onError handler present and logs errors
+- [ ] Works in both light and dark themes
+- [ ] No console errors when enabled/disabled
+- [ ] No visual/layout breaking when rendered alongside other widgets
+
+## File Locations
+
+- **Main App:** `src/App.tsx`
+- **Styles:** `src/App.scss`
+
+## Additional Resources
+
+- [MobX Store Package](../../packages/contact-center/store/ai-docs/agent.md)
+- [cc-widgets Package](../../packages/contact-center/cc-widgets/ai-docs/agent.md)