diff --git a/.codex/skills/interface-design/SKILL.md b/.codex/skills/interface-design/SKILL.md new file mode 100644 index 0000000..9f1a847 --- /dev/null +++ b/.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 + + + + + + Please enter a valid email + + +``` + +### Typography + +Always use `Typography` component instead of raw HTML elements: + +```tsx + + Main Page Title + +``` + +### Buttons + +Use appropriate variants and sizes: + +```tsx + + + +``` + +## 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_ diff --git a/.codex/skills/interface-design/rules/alertdialog.md b/.codex/skills/interface-design/rules/alertdialog.md new file mode 100644 index 0000000..dd4b6f9 --- /dev/null +++ b/.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 + + + + + + + Are you sure? + + + This action cannot be undone. This will permanently delete your account. + + + + + + + + + + +// With icon + + + + + + }> + Are you sure you want to delete your account? + + + This action cannot be undone. + + + + + + + + + + +// With long scrollable content + + + + Terms and Conditions + + + {/* Long scrollable content */} + + + + + + + + + +``` + +**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` diff --git a/.codex/skills/interface-design/rules/best-practices-accessibility.md b/.codex/skills/interface-design/rules/best-practices-accessibility.md new file mode 100644 index 0000000..9888357 --- /dev/null +++ b/.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 `
` for navigation (use `` or ``) + +**Examples**: + +```tsx +// ✅ Correct + + Email Address + + + +// ❌ Incorrect +
Navigate
// Should use Link or Button +``` diff --git a/.codex/skills/interface-design/rules/best-practices-components.md b/.codex/skills/interface-design/rules/best-practices-components.md new file mode 100644 index 0000000..93ebc93 --- /dev/null +++ b/.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 + + + +// ❌ Incorrect + + +``` diff --git a/.codex/skills/interface-design/rules/best-practices-forms.md b/.codex/skills/interface-design/rules/best-practices-forms.md new file mode 100644 index 0000000..fbbaba1 --- /dev/null +++ b/.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 `` or `