+```
+
+## Event Handling Pattern
+
+### Standard onError Handler
+
+```tsx
+const onError = (source: string, error: Error) => {
+ console.error(`${source} 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
+
+Widgets automatically use MobX store theme:
+
+```tsx
+// Theme is managed by store.currentTheme
+// Widget CSS uses CSS variables that respond to theme changes
+// No manual theme passing needed
+```
+
+**User can toggle theme via UI dropdown** - widgets update automatically.
+
+## 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. Event handler (if needed)
+const handleAwesomeEvent = (data) => {
+ console.log('Awesome event:', 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)
+- [ ] Event handlers fire 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`
+- **Widget Imports:** Line 1-28 in `App.tsx`
+- **defaultWidgets:** Line 33-42 in `App.tsx`
+- **Widget Selector:** Around line 300-400 in render method
+- **Widget Render:** Main render section grouped by category
+
+## Additional Resources
+
+- [Momentum Design System Docs](https://momentum.design/)
+- [MobX Store Package](../../packages/contact-center/store/ai-docs/agent.md)
+- [cc-widgets Package](../../packages/contact-center/cc-widgets/ai-docs/agent.md)
+