Merge synced main and observability rollout

.codex/skills/interface-design/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: mini-apps-ui-kit-react
+description: >-
+  A comprehensive React UI component library for building mini-apps with form controls,
+  buttons, feedback components, overlays, layout components, and utilities. Built with
+  TypeScript, Tailwind CSS, Radix UI primitives, and Vaul for drawers.
+license: MIT
+compatibility: React 18+, TypeScript, Tailwind CSS, SSR-friendly, RTL support
+metadata:
+  author: Worldcoin
+  version: '1.0.0'
+---
+
+# Mini Apps UI Kit - Component Skills Reference
+
+This document provides a comprehensive reference for all components in the `@worldcoin/mini-apps-ui-kit-react` package. Each component is documented with its purpose, props, usage examples, variants, and edge cases to help AI agents effectively use these components.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Building UI components with the Mini Apps UI Kit
+- Implementing forms, buttons, or interactive elements
+- Creating layouts, navigation, or feedback components
+- Reviewing code for UI/UX best practices
+- Ensuring accessibility and mobile-first design
+
+## Component Categories
+
+### Form Controls
+
+- `rules/form-input.md` - Input component with adornments and validation
+- `rules/form-phonefield.md` - Phone number input with country selection
+- `rules/form-passwordfield.md` - Password input with visibility toggle
+- `rules/form-searchfield.md` - Search input with paste button
+- `rules/form-textarea.md` - Multi-line text input
+- `rules/form-select.md` - Dropdown select component
+- `rules/form-checkbox.md` - Checkbox component
+- `rules/form-switch.md` - Toggle switch component
+- `rules/form-radiogroup.md` - Radio group component
+- `rules/form-otpfield.md` - One-time password input
+- `rules/form-walletaddressfield.md` - Wallet address input
+
+### Buttons & Actions
+
+- `rules/button.md` - Versatile button component
+- `rules/chip.md` - Chip component with variants
+- `rules/pill.md` - Pill-shaped toggle component
+- `rules/token.md` - Token symbol display
+
+### Feedback & Display
+
+- `rules/toast.md` - Toast notification system
+- `rules/livefeedback.md` - Async operation feedback wrapper
+- `rules/progress.md` - Progress indicator
+- `rules/skeleton.md` - Loading skeleton placeholders
+- `rules/typography.md` - Typography system
+- `rules/flag.md` - Country flag component
+- `rules/marble.md` - Circular image component
+- `rules/verificationbadge.md` - Verification status badge
+
+### Overlays & Dialogs
+
+- `rules/drawer.md` - Bottom drawer component
+- `rules/alertdialog.md` - Alert dialog modal
+- `rules/countrydrawer.md` - Country selection drawer
+
+### Layout & Navigation
+
+- `rules/topbar.md` - Top navigation bar
+- `rules/bottombar.md` - Bottom action bar
+- `rules/tabs.md` - Tab navigation
+- `rules/safeareaview.md` - Safe area wrapper
+
+### Interactive Elements
+
+- `rules/numberpad.md` - Numeric keypad
+- `rules/colorpicker.md` - Color picker component
+- `rules/togglegroup.md` - Toggle group component
+- `rules/listitem.md` - List item component
+
+### Utilities
+
+- `rules/haptic.md` - Haptic feedback wrapper
+- `rules/form-utilities.md` - Form validation utilities
+- `rules/bulletlist.md` - Bullet list component
+- `rules/circularicon.md` - Circular icon container
+- `rules/circularstate.md` - Circular state indicator
+- `rules/i18n.md` - Internationalization support
+
+## Best Practices
+
+- `rules/best-practices-typography.md` - Typography & content guidelines
+- `rules/best-practices-forms.md` - Forms & inputs guidelines
+- `rules/best-practices-components.md` - Component usage guidelines
+- `rules/best-practices-accessibility.md` - Accessibility requirements
+- `rules/best-practices-mobile.md` - Mobile & touch guidelines
+- `rules/best-practices-state.md` - State & navigation guidelines
+- `rules/best-practices-i18n.md` - Internationalization guidelines
+- `rules/best-practices-validation.md` - Error handling & validation
+- `rules/best-practices-performance.md` - Performance & loading
+
+## Quick Reference
+
+### Form Controls
+
+All form controls integrate with the `Form` component for validation:
+
+```tsx
+<Form.Root>
+  <Form.Field name="email" className="has-error">
+    <Form.Control asChild>
+      <Input error label="Enter your email" />
+    </Form.Control>
+    <Form.Message error>Please enter a valid email</Form.Message>
+  </Form.Field>
+</Form.Root>
+```
+
+### Typography
+
+Always use `Typography` component instead of raw HTML elements:
+
+```tsx
+<Typography variant="heading" level={1} as="h1">
+  Main Page Title
+</Typography>
+```
+
+### Buttons
+
+Use appropriate variants and sizes:
+
+```tsx
+<Button variant="primary" size="lg">Click Me</Button>
+<Button variant="secondary">Cancel</Button>
+<Button variant="tertiary" size="icon">
+  <Star />
+</Button>
+```
+
+## How to Use
+
+Read individual rule files for detailed component documentation:
+
+```
+rules/form-input.md
+rules/button.md
+rules/best-practices-typography.md
+```
+
+Each rule file contains:
+
+- Component purpose and use cases
+- Key props and their types
+- Usage examples with code
+- Edge cases and gotchas
+- Storybook references
+
+## See Also
+
+- **Form Controls**: All integrate with Form component for validation
+- **Overlays**: Drawer and AlertDialog use Vaul and Radix UI Dialog
+- **Feedback**: Toast, LiveFeedback, and Progress provide user feedback
+- **Layout**: TopBar and BottomBar commonly used together in mobile layouts
+- **Icons**: Many components accept icon props - see icon exports from the package
+- **Typography**: Use Typography component for all text content
+- **Validation**: Form component provides validation patterns
+
+---
+
+_Last updated: Based on Storybook stories in `stories/` directory_

.codex/skills/interface-design/rules/alertdialog.md

@@ -0,0 +1,100 @@
+---
+title: AlertDialog Component
+category: overlays-dialogs
+tags: dialog, modal, alert, confirmation, vaul
+---
+
+## AlertDialog
+
+A modal dialog that interrupts the user with important content and expects a response. Built on top of Vaul and Radix UI Dialog. Use for confirmations, warnings, or critical information.
+
+**Key Components**:
+
+- `AlertDialog`: Root component
+- `AlertDialogTrigger`: Button/element that opens the dialog
+- `AlertDialogContent`: Main content container
+- `AlertDialogHeader`: Header section (supports icon prop)
+- `AlertDialogTitle`: Title text
+- `AlertDialogDescription`: Description/body text
+- `AlertDialogFooter`: Footer with action buttons
+- `AlertDialogClose`: Element that closes dialog
+- `AlertDialogPortal`: Portal for rendering (optional)
+
+**Key Props**:
+
+- `dismissible` (boolean): Whether the dialog can be dismissed (default: true)
+
+**Examples**:
+
+```tsx
+// Basic alert dialog
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="secondary" size="sm">
+      Open Alert Dialog
+    </Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+    </AlertDialogHeader>
+    <AlertDialogDescription>
+      This action cannot be undone. This will permanently delete your account.
+    </AlertDialogDescription>
+    <AlertDialogFooter>
+      <AlertDialogClose asChild>
+        <Button variant="secondary">Cancel</Button>
+      </AlertDialogClose>
+      <Button>Continue</Button>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+
+// With icon
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button>Delete Account</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader icon={<CircleSpark />}>
+      <AlertDialogTitle>Are you sure you want to delete your account?</AlertDialogTitle>
+    </AlertDialogHeader>
+    <AlertDialogDescription>
+      This action cannot be undone.
+    </AlertDialogDescription>
+    <AlertDialogFooter>
+      <AlertDialogClose asChild>
+        <Button variant="secondary">Cancel</Button>
+      </AlertDialogClose>
+      <Button>Delete</Button>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+
+// With long scrollable content
+<AlertDialog>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Terms and Conditions</AlertDialogTitle>
+    </AlertDialogHeader>
+    <AlertDialogDescription>
+      {/* Long scrollable content */}
+    </AlertDialogDescription>
+    <AlertDialogFooter>
+      <AlertDialogClose asChild>
+        <Button variant="secondary">Decline</Button>
+      </AlertDialogClose>
+      <Button>Accept</Button>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+**Edge Cases**:
+
+- Use `asChild` on trigger and close elements
+- Header supports icon prop for custom styling
+- Description area is scrollable for long content
+- Footer typically contains action buttons
+
+**Storybook Reference**: `stories/AlertDialog.stories.tsx`

.codex/skills/interface-design/rules/best-practices-accessibility.md

@@ -0,0 +1,32 @@
+---
+title: Accessibility Best Practices
+category: best-practices
+tags: accessibility, a11y, keyboard, screen-reader, aria
+---
+
+## Accessibility
+
+Concise rules for building accessible interfaces with the Mini Apps UI Kit. Use MUST/SHOULD/NEVER to guide decisions.
+
+- MUST: Components built on Radix UI include proper ARIA attributes automatically
+- MUST: Full keyboard support per [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/patterns/)
+- MUST: Visible focus rings (handled by components; use `:focus-visible` for custom elements)
+- MUST: Manage focus (trap, move, return) in modals and drawers
+- MUST: Use semantic HTML tags via `as` prop for screen readers
+- MUST: Associate form labels with inputs using `htmlFor` and `id`
+- SHOULD: Test with keyboard navigation and screen readers
+- NEVER: Remove focus styles without providing visible replacement
+- NEVER: Use `<div onClick>` for navigation (use `<a>` or `<Link>`)
+
+**Examples**:
+
+```tsx
+// ✅ Correct
+<Typography variant="label" level={1} as="label" htmlFor="email">
+  Email Address
+</Typography>
+<Input id="email" label="Email" />
+
+// ❌ Incorrect
+<div onClick={handleClick}>Navigate</div> // Should use Link or Button
+```

.codex/skills/interface-design/rules/best-practices-components.md

@@ -0,0 +1,30 @@
+---
+title: Component Usage Best Practices
+category: best-practices
+tags: components, ui-kit, structure, usage
+---
+
+## Components & Structure
+
+Concise rules for using UI Kit components effectively. Use MUST/SHOULD/NEVER to guide decisions.
+
+- MUST: Use UI Kit components instead of building custom equivalents
+- MUST: Check corresponding `.stories.tsx` file for component usage examples
+- MUST: Use `Toaster` component in app root when using Toast notifications
+- MUST: Wrap form controls with `Form.Control` using `asChild` prop
+- SHOULD: Use consistent icon sizes (typically 20x20px) when providing custom icons
+- SHOULD: Use `fullWidth` prop on buttons in `BottomBar` for consistent sizing
+- NEVER: Create custom components that duplicate UI Kit functionality
+- NEVER: Use raw HTML elements when UI Kit components exist
+
+**Examples**:
+
+```tsx
+// ✅ Correct
+<Button variant="primary" size="lg">Click Me</Button>
+<Input label="Email" id="email" />
+
+// ❌ Incorrect
+<button className="custom-button">Click Me</button>
+<input type="text" placeholder="Email" />
+```

.codex/skills/interface-design/rules/best-practices-forms.md

@@ -0,0 +1,43 @@
+---
+title: Forms & Inputs Best Practices
+category: best-practices
+tags: forms, inputs, validation, error-handling
+---
+
+## Forms & Inputs
+
+Concise rules for building accessible, fast, delightful forms with the Mini Apps UI Kit. Use MUST/SHOULD/NEVER to guide decisions.
+
+- MUST: Use `Form.Root`, `Form.Field`, and `Form.Control` for validation and error display
+- MUST: Add `has-error` className to `Form.Field` when showing error states
+- MUST: Use controlled state for all form inputs (`value` + `onChange`)
+- MUST: Display errors inline next to fields using `Form.Message`
+- MUST: Focus first error field on form submission
+- MUST: Use appropriate `autocomplete` and `name` attributes for password managers
+- MUST: Allow paste in all input fields (never block paste)
+- MUST: Accept free text input, validate after—don't block typing
+- MUST: Allow incomplete form submission to surface validation errors
+- MUST: Keep submit button enabled until request starts, then disable with spinner
+- MUST: Use `LiveFeedback` wrapper for async form submissions
+- SHOULD: Disable spellcheck for emails, codes, and usernames
+- SHOULD: Use placeholders that end with `…` and show example patterns
+- NEVER: Block paste in `<input>` or `<textarea>` fields
+- NEVER: Disable submit button before validation completes
+- NEVER: Use uncontrolled form inputs when controlled state is available
+
+**Examples**:
+
+```tsx
+// ✅ Correct
+<Form.Root>
+  <Form.Field name="email" className="has-error">
+    <Form.Control asChild>
+      <Input error label="Enter your email" />
+    </Form.Control>
+    <Form.Message error>Please enter a valid email</Form.Message>
+  </Form.Field>
+</Form.Root>
+
+// ❌ Incorrect
+<Input label="Email" /> // No Form wrapper, no error handling
+```