AI Integration

PayAdvantage Component Usage Rules/Instructions for AI Assistants

This document provides concise usage guidelines for AI coding assistants. Copy the rules below to configure your IDE for optimal PayAdvantage component usage.

IDE Rules (Copy This Section)

# PayAdvantage UI Components Usage Guidelines

## Primary Rule
Always use PayAdvantage components (pa-*) over HTML elements or third-party components when available.

## Documentation Reference
For detailed component props, events, and usage examples, reference the local documentation:
- **Component Documentation**: https://uilib.payadvantage.com.au/components/
- Use this for specific prop names, event handlers, and component APIs
- Each component page includes live examples and complete prop definitions

## Component Mappings

### Form Components
- pa-input-group instead of input + label combinations (preferred)
- pa-input for standalone inputs (use sparingly)
- pa-dropdown instead of <select>
- pa-checkbox instead of <input type="checkbox">
- pa-checkbox-group for multiple checkboxes
- pa-radio instead of <input type="radio">
- pa-radio-group for multiple radio buttons
- pa-date-picker for date inputs
- pa-currency-input for monetary values
- pa-phone-number-input for phone numbers
- pa-switch for toggle switches
- pa-toggle for segmented controls
- pa-slider for range inputs
- pa-form for form containers
- pa-option-group for grouped options

### Action Components
- pa-button instead of <button>
- pa-action-button for icon + label buttons
- pa-action-button-group for grouped action buttons
- pa-action-group for action collections
- pa-nav-button for navigation items
- pa-nav-button-group for navigation button groups

### Display Components
- pa-badge for status indicators
- pa-icon instead of raw SVG or icon fonts
- pa-circle for circular containers
- pa-square for square containers
- pa-hero for page headers
- pa-hero-header for hero header sections
- pa-hero-icon for hero icons
- pa-hero-subheader for hero subheaders
- pa-hero-subheader-group for grouped hero subheaders
- pa-list-item for list elements
- pa-divider instead of <hr>

### Icon Naming Patterns
FontAwesome icons use kebab-case with style suffixes:
- Regular: icon-name-regular (e.g., "star-regular", "user-regular")
- Solid: icon-name-solid (e.g., "star-solid", "check-solid")
- Light: icon-name-light (e.g., "star-light", "check-light")
- Brand: icon-name-brand (e.g., "cc-visa-brand", "google-pay-brand")
Custom icons: descriptive names (e.g., "visa-logo", "bpay-vertical")

### Layout Components
- pa-sheet instead of generic cards/panels
- pa-page-container for page-level containers
- pa-form-container for form containers
- pa-text-container for text content containers
- pa-form-divider for form section dividers
- pa-page-divider for page section dividers
- pa-text-divider for text section dividers
- pa-content-separator for content separation
- pa-slotted-layout for complex layouts

### Feedback Components
- pa-modal instead of custom modals
- pa-notification for user notifications

## Decision Guide
1. Forms: Always use pa-input-group for labeled inputs (preferred over pa-input)
2. Buttons: Always use pa-button or action button variants (pa-action-button, pa-nav-button)
3. Icons: Always use pa-icon with FontAwesome icon names (check naming patterns above)
4. Layout: Use pa-container variants and pa-sheet for content areas
5. Navigation: Use pa-nav-button for menu/navigation items
6. Hero sections: Use pa-hero and related hero components for page headers
7. Grouping: Use pa-*-group components for related form elements
8. Feedback: Use pa-modal for overlays and pa-notification for messages

## Example Patterns
<!-- ✅ Correct -->
<pa-input-group label="Email" v-model="email" type="email" />
<pa-button variant="primary">Save</pa-button>
<pa-sheet><pa-hero title="Page Title" /></pa-sheet>
<pa-checkbox-group v-model="selected" :options="checkboxOptions" />
<pa-action-button icon="plus-solid" label="Add Item" />
<pa-icon icon="check-solid" variant="success" />
<pa-modal v-model="showModal">Modal content</pa-modal>

<!-- ❌ Avoid -->
<input type="email" placeholder="Email" />
<button class="btn">Save</button>
<div class="card"><h1>Page Title</h1></div>
<input type="checkbox" /> <label>Option</label>
<button><i class="fa fa-plus"></i> Add Item</button>
<i class="fas fa-check"></i>
<div class="modal">Modal content</div>

Setup Instructions

For Cursor:

1. Copy the "IDE Rules" section above
2. Save as .cursor/rules/pa-components-usage.mdc in your project root
3. Reference: Cursor Rules docs

For VSCode with GitHub Copilot:

1. Copy the "IDE Rules" section above
2. Save in .github/instructions/pa-components-usage.mdc folder in your project root
3. Reference: GitHub Copilot workspace instructions

Documentation Reference

• Component Library - Full component documentation
• Installation Guide - Setup instructions
• Usage Guide - Implementation patterns