ima-claude 2.9.0

package/plugins/ima-claude/skills/ima-brand/references/visual-system.md

@@ -0,0 +1,173 @@
+# IMA Visual System
+
+Source: IMA Brand Book v4.0, pages 11-25 and 27.
+
+For SCSS implementation (variables, mixins, classes), see the `ima-bootstrap` skill.
+
+---
+
+## Color Palette
+
+### Primary Colors
+
+| Name | Hex | CMYK | RGB | Usage |
+|------|-----|------|-----|-------|
+| Trustworthy Indigo | `#00066F` | 100/98/20/25 | 0, 6, 111 | Primary brand color — headers, titles, trust elements |
+| Aquatic Pulse | `#00B8B8` | 78/0/22/26 | 0, 184, 184 | Interactive elements — buttons, CTAs, links |
+| Guidance Sky | `#A2CFF0` | 33/12/0/4 | 162, 207, 240 | Light backgrounds, soft accents |
+
+### Secondary Colors
+
+| Name | Hex | CMYK | RGB | Usage |
+|------|-----|------|-----|-------|
+| Vital Gold | `#FFCC00` | 0/17/100/0 | 255, 204, 0 | Warnings, attention, prescriber tags |
+| Red Ribbon | `#DD153B` | 0/87/62/11 | 221, 21, 59 | Urgency, errors, critical alerts |
+| Plum Velvet | `#7B024D` | 30/92/18/22 | 123, 2, 77 | Accent, distinction, premium feel |
+
+### Grayscale
+
+| Name | Hex | Usage |
+|------|-----|-------|
+| Calm Stone | `#919396` | Form labels, secondary text, muted elements |
+| Clarity Wash | `#F2F3F5` | Backgrounds, cards, light sections |
+| Slate Neutral | `#8A93A5` | Alternative gray, subtle borders |
+| Gravel | `#494949` | Dark gray, body text alternative |
+| White | `#FFFFFF` | Clean backgrounds, inverse text |
+| Black | `#000000` | Maximum contrast text |
+
+### Special
+
+| Name | Value | Usage |
+|------|-------|-------|
+| Accessible Teal | `#007BB4` | High-contrast alternative for WCAG compliance |
+| Brand Gradient | `150deg, #00066F → #00B8B8` | Hero sections, overlays, premium elements |
+
+### Color Application Rules
+
+- **Primary brand color (Indigo)**: Use for headings, titles, and trust-building elements. Conveys authority.
+- **Interactive elements (Aquatic Pulse)**: Buttons, links, CTAs. Users learn to associate teal with action.
+- **Never use red/gold for decorative purposes**: Red = urgency/error, Gold = warning/attention. These carry semantic meaning.
+- **Print vs Digital**: CMYK values for print, hex/RGB for digital. Always use the exact values — don't approximate.
+- **Gradient usage**: Hero banners, footer backgrounds, overlay on dark photography. Not for small elements or text backgrounds.
+
+---
+
+## Typography
+
+### Font Families
+
+| Font | Role | Weights | Fallback |
+|------|------|---------|----------|
+| **Lato** | Headings, buttons, labels | Bold (700), Black (900), Semi Bold (600) | sans-serif |
+| **Proxima Nova** | Body text, forms (preferred) | Regular (400), Bold (700) | Open Sans, sans-serif |
+| **Open Sans** | Body text, forms (free alternative) | Regular (400), Bold (700) | sans-serif |
+
+### Type Hierarchy
+
+| Element | Font | Weight | Size | Style |
+|---------|------|--------|------|-------|
+| H1 / Page header | Lato | Black (900) | 40px | Uppercase |
+| H2 / Section header | Lato | Bold (700) | 32px | — |
+| H3 / Subsection | Lato | Regular (400) | 28px | — |
+| H4 / Section header (small) | Lato | Bold (700) | 20px | — |
+| Body text | Proxima Nova / Open Sans | Regular (400) | 16px | — |
+| Button text | Lato | Bold (700) | 18px | Uppercase |
+| Form labels | Open Sans | Regular (400) | 14px | — |
+| Provider/doctor title | Lato | Semi Bold (600) | 32px | — |
+
+### Typography Rules
+
+- **Headings are always Lato** — never use Proxima Nova/Open Sans for headings
+- **Body is always Proxima Nova or Open Sans** — never use Lato for body paragraphs
+- **Uppercase**: Only for H1/page headers and button text. Don't uppercase body text or H2-H4
+- **Line height**: 1.0 for headers, 1.5 for body text
+- **Letter spacing**: Default. Don't add custom letter-spacing
+
+---
+
+## Logo System
+
+### Logo Variants
+
+| Variant | Name | Description | Primary Use |
+|---------|------|-------------|-------------|
+| Primary | Horizontal lockup | IMA logo + "Independent Medical Alliance" side by side | Website header, documents, letterhead |
+| Secondary | Vertical/stacked lockup | IMA logo above "Independent Medical Alliance" | Social media profiles, square spaces |
+| Tertiary | IMA lettermark | Just the "IMA" letters in brand styling | Favicons, small spaces, app icons |
+
+### Lockup Color Variants
+
+| Lockup | Background | Usage |
+|--------|-----------|-------|
+| Hero | Brand gradient | Hero sections, premium placements |
+| Blue | White/light | Standard usage on light backgrounds |
+| Black | White/light | Monochrome/formal contexts |
+| Black Text | White/light | Logo mark colored + black text |
+| Inverse | Dark/gradient | Dark backgrounds, footer, overlay on photos |
+
+### Logo Rules
+
+**Clear space**: Maintain minimum clear space around the logo equal to the height of the "I" in IMA. No text, images, or other elements may intrude into this space.
+
+**Minimum size**: 200px width for primary and secondary lockups. Below 200px, use the IMA lettermark (tertiary) instead.
+
+**Brand family logos**: IMA Journal and IMA Action have their own lockups that follow the same system.
+
+### Proper Logo Usage
+
+| Background | Logo Variant | Notes |
+|-----------|-------------|-------|
+| White / light solid | Blue or Black lockup | Standard usage |
+| Dark solid | Inverse lockup | White text on dark |
+| Brand gradient | Hero lockup | Designed specifically for gradient |
+| Photo overlay | Inverse lockup | Ensure sufficient contrast with overlay/scrim |
+| Colored solid (brand colors) | Inverse lockup | Only on brand colors, not arbitrary colors |
+
+### Improper Logo Usage (Never Do)
+
+- **Stretch or distort** — Always maintain original aspect ratio
+- **Recolor** — Only use approved lockup color variants
+- **Place on busy/patterned backgrounds** — Logo must be clearly readable
+- **Rotate or skew** — Logo must always be level/horizontal
+- **Add shadows or effects** — No drop shadows, glows, outlines, or 3D effects
+- **Display below minimum size** — Use lettermark for small applications
+- **Crop or obscure** — Full logo must be visible
+- **Place too close to other elements** — Respect the clear space rules
+
+---
+
+## Imagery Guidelines
+
+### Photography Style
+
+- **Authentic**: Real people, not overly staged stock photography
+- **Professional**: Well-lit, high quality, properly composed
+- **Healthcare-appropriate**: Clinical settings should feel welcoming, not sterile
+- **Diverse**: Represent the diversity of IMA's global community
+- **Warm lighting**: Natural light preferred, warm tones over cold/clinical
+
+### Photography by Content Type
+
+| Content Type | Image Style | Notes |
+|-------------|------------|-------|
+| Patient stories | Warm, personal, relatable | Real patients when possible (with consent) |
+| Medical content | Professional, clinical-but-approachable | Healthcare settings, doctors, labs |
+| Community / events | Candid, energetic, inclusive | Group shots, event photography |
+| Research / science | Clean, precise, data-oriented | Lab settings, infographics, data viz |
+| Fundraising | Emotional, hopeful, impact-focused | People helped, community impact |
+
+### Image Treatment
+
+- **Color overlay**: Brand gradient overlay for hero images (opacity: 60-80%)
+- **Duotone**: Indigo + Teal for stylized feature images
+- **Never**: Over-saturate, use filters that alter skin tones, or use low-resolution images
+
+---
+
+## Iconography
+
+- **Style**: Clean, simple line icons or flat icons
+- **Color**: Brand colors only — Indigo, Teal, or White (on dark backgrounds)
+- **Weight**: Consistent stroke weight within a set (2px recommended)
+- **Usage**: Supporting content, navigation, feature highlights — not decorative filler
+- **Avoid**: Overly detailed icons, 3D icons, clipart, emoji as icons in formal content

package/plugins/ima-claude/skills/ima-forms-expert/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: ima-forms-expert
+description: |
+  WordPress form component library with Bootstrap 5 integration, validators-at-registration
+  architecture (v1.4.0+), and security-first patterns. Use when: building custom forms
+  with IMA Forms components (ima_forms_* functions), implementing form validation,
+  adding field types (text, email, phone, select, checkbox, repeater, consent agreement),
+  creating dynamic repeater fields, handling AJAX form submissions, or integrating forms
+  with ACF/custom post types. Key features: validators built as closures at field registration
+  (single source of truth), enhanced email validation with disposable domain blocking,
+  template-driven validation where "template IS the definition".
+---
+
+# IMA Forms Expert
+
+WordPress form component library with Bootstrap 5 + functional programming patterns.
+
+## When to Use This Skill
+
+- Building custom forms using IMA Forms component library
+- Implementing template-driven validation (v1.3.0+)
+- Understanding validators-at-registration architecture (v1.4.0+)
+- Adding field types or container components
+- Creating repeater/dynamic field patterns
+- Integrating forms with WordPress (ACF, custom post types, AJAX)
+- Debugging form submission issues
+
+## Core Principles
+
+- **Template IS the definition**: Field rendering auto-registers validation specs + validators
+- **Validators at registration**: Field functions build closures at registration time (v1.4.0)
+- **Security by default**: Nonce verification, sanitization, escaping
+- **Component-based**: Reusable field and container components
+- **Bootstrap 5 native**: Uses Bootstrap utilities and components
+
+## Architecture (v1.4.0 - Unified Validator Registry)
+
+```
+ima-forms/
+├── ima-forms.php                      # Plugin initialization
+├── includes/
+│   ├── functions-core.php             # Security chokepoint, higher-order functions
+│   ├── functions-registry.php         # Field spec registry (stores validators)
+│   ├── functions-validation-engine.php # Runs validators, sanitizes data
+│   ├── functions-fields.php           # Field rendering + validator building
+│   ├── functions-containers.php       # Container/layout components
+│   ├── functions-validators.php       # Pure validation functions
+│   ├── functions-sanitizers.php       # Context-appropriate sanitization
+│   ├── functions-form.php             # Form factory (v1.2.0)
+│   └── forms/                         # Form implementations
+├── templates/
+│   ├── fields/                        # Field templates
+│   ├── containers/                    # Container templates
+│   └── forms/                         # Complete form templates
+└── assets/js/                         # Vanilla JS (repeater, consent, AJAX)
+```
+
+### Validators-at-Registration Pattern (v1.4.0)
+
+**Key change from v1.3.0**: Validators are now built as closures at field registration time, not rebuilt by the engine via type-switching.
+
+```php
+// Inside ima_forms_email_field_register():
+$validators = [];
+
+if ($required) {
+    $validators[] = fn($v) => ima_forms_validate_required($v, $label);
+}
+
+$validators[] = function($v) use ($label, $enhanced) {
+    if (empty($v)) return null;
+    return ima_forms_validate_email_enhanced((string) $v, $label, $enhanced);
+};
+
+ima_forms_register_field_spec($name, [
+    'type' => 'email',
+    'label' => $label,
+    'required' => $required,
+    'validators' => $validators,  // Closures stored at registration!
+]);
+```
+
+**Benefits**:
+- Single source of truth: field function defines validation once
+- No type switching: validators are closures, just iterate and run
+- Testable: validators are pure functions captured at registration time
+
+## Key Patterns
+
+### Template-Driven Validation
+
+Field functions auto-register specs + validators. Validate entire form in one call:
+
+```php
+$result = ima_forms_validate_form('templates/forms/my-form', $_POST, 'my-form');
+
+if (!$result['valid']) {
+    wp_send_json_error(['errors' => $result['errors']], 400);
+}
+
+$sanitized = $result['sanitized'];  // Ready to use
+```
+
+→ **Details**: See [references/validation-engine.md](references/validation-engine.md)
+
+### Enhanced Email Validation
+
+Blocks disposable domains, detects typos:
+
+```php
+ima_forms_email_field([
+    'name' => 'email',
+    'enhanced_validation' => true,  // gmial.com → suggests gmail.com
+]);
+```
+
+## Quick Start Example
+
+```php
+// Template: templates/forms/contact.php
+ima_forms_form(['id' => 'contact', 'action' => 'contact_submit'], function() use ($data, $errors) {
+    ima_forms_text_field(['name' => 'name', 'label' => 'Name', 'required' => true, ...]);
+    ima_forms_email_field(['name' => 'email', 'required' => true, 'enhanced_validation' => true, ...]);
+    ima_forms_textarea_field(['name' => 'message', 'required' => true, ...]);
+    ima_forms_submit_button(['text' => 'Send']);
+});
+
+// AJAX Handler
+function contact_submit_handler() {
+    if (!wp_verify_nonce($_POST['nonce'], 'ima_forms_ajax')) {
+        wp_send_json_error(['message' => 'Security check failed.'], 403);
+    }
+
+    $result = ima_forms_validate_form('templates/forms/contact', $_POST, 'contact');
+
+    if (!$result['valid']) {
+        wp_send_json_error(['errors' => $result['errors']], 400);
+    }
+
+    // Process $result['sanitized']...
+    wp_send_json_success(['message' => 'Sent!']);
+}
+add_action('wp_ajax_contact_submit', 'contact_submit_handler');
+add_action('wp_ajax_nopriv_contact_submit', 'contact_submit_handler');
+```
+
+## Reference Files
+
+| File | Read When |
+|------|-----------|
+| [validation-engine.md](references/validation-engine.md) | Using `ima_forms_validate_form()`, understanding validator registry, custom validators |
+| [field-components.md](references/field-components.md) | Adding specific field types, customizing field behavior, repeaters |
+| [container-components.md](references/container-components.md) | Using cards, sections, column layouts, fieldsets |
+| [examples.md](references/examples.md) | Implementing complete new forms, testing patterns, anti-patterns |
+| [quick-reference.md](references/quick-reference.md) | Function signatures, version features, filters |
+
+## Common Tasks
+
+| Task | Approach |
+|------|----------|
+| Add a simple form | Use `ima_forms_form()` + field components + `ima_forms_validate_form()` |
+| Add custom validation | Filter: `add_filter('ima_forms_validate_{form-id}', ...)` |
+| Block spam emails | Set `enhanced_validation => true` on email fields |
+| Add repeater rows | Use `ima_forms_repeater()` with row callback |
+| Create multi-column layout | Use `ima_forms_column_layout(['columns' => 3, ...])` |
+| Debug validation | Use `ima_forms_debug_field_specs()` or `ima_forms_debug_validation_summary($specs)` |
+
+## Success Indicators
+
+- ✅ Template-driven validation (no manual field maps)
+- ✅ Enhanced email validation on user-facing forms
+- ✅ Standardized form wrappers (`ima_forms_form()`)
+- ✅ Nonce verification in all AJAX handlers
+- ✅ Sanitized data used for processing (never raw `$_POST`)
+- ✅ Validators built at registration, not in engine

package/plugins/ima-claude/skills/ima-forms-expert/references/container-components.md

@@ -0,0 +1,154 @@
+# Container Components Reference
+
+## Contents
+
+- [Form Wrapper](#form-wrapper)
+- [Submit Button](#submit-button)
+- [Card Wrapper](#card-wrapper)
+- [Section with Heading](#section-with-heading)
+- [Column Layout](#column-layout)
+- [Fieldset](#fieldset)
+
+---
+
+## Form Wrapper
+
+Complete form container with AJAX support:
+
+```php
+ima_forms_form([
+    'id' => 'my-form',
+    'action' => 'my_ajax_action',      // AJAX action name
+    'method' => 'post',
+    'class' => 'ima-form w-100',       // Default: full width
+    'nonce_action' => 'my_form_submit',
+    'nonce_name' => 'nonce',
+    'enqueue_base' => true,            // Auto-enqueue ima-forms-base.js
+], function() {
+    // Form fields here
+});
+```
+
+**Auto-generated elements**:
+- `.ima-form-errors` - Error container (populated by JS)
+- `.ima-form-success` - Success container
+- Nonce field
+- `data-action` attribute for JS handler
+
+## Submit Button
+
+```php
+ima_forms_submit_button([
+    'text' => 'Submit Form',
+    'processing_text' => 'Submitting...',
+    'class' => 'btn btn-primary',
+    'show_spinner' => true,
+    'disabled' => false,
+    'wrapper_class' => 'mt-4',
+]);
+```
+
+**Features**:
+- Shows spinner during submission
+- Disables button during processing
+- Text changes to `processing_text` when submitting
+
+## Card Wrapper
+
+Bootstrap card with optional header:
+
+```php
+ima_forms_card([
+    'title' => 'Personal Information',
+    'description' => 'Please provide your contact details',
+    'card_class' => 'shadow-sm',
+    'wrapper_class' => 'mb-4',
+    'show_header' => true,
+], function() use ($data, $errors) {
+    ima_forms_text_field([...]);
+    ima_forms_email_field([...]);
+});
+```
+
+## Section with Heading
+
+Semantic section with heading and optional separator:
+
+```php
+ima_forms_section([
+    'heading' => 'Contact Information',
+    'description' => 'How can we reach you?',
+    'heading_tag' => 'h3',
+    'heading_class' => 'mb-3',
+    'show_separator' => true,
+    'wrapper_class' => 'mb-4',
+], function() use ($data, $errors) {
+    // Fields here
+});
+```
+
+## Column Layout
+
+Responsive multi-column layout:
+
+```php
+ima_forms_column_layout([
+    'columns' => 3,           // 1-6 columns
+    'breakpoint' => 'md',     // Collapse below: sm, md, lg, xl, xxl
+    'gap' => 3,               // Bootstrap gap (0-5)
+    'wrapper_class' => 'mb-3',
+], function() use ($data, $errors) {
+    // Fields render side-by-side (desktop) or stacked (mobile)
+    ima_forms_text_field([
+        'name' => 'city',
+        'label' => 'City',
+        'wrapper_class' => 'mb-0',  // Remove bottom margin in columns
+        ...
+    ]);
+    ima_forms_state_select_field([
+        'name' => 'state',
+        'wrapper_class' => 'mb-0',
+        ...
+    ]);
+    ima_forms_text_field([
+        'name' => 'zip',
+        'label' => 'ZIP',
+        'wrapper_class' => 'mb-0',
+        ...
+    ]);
+});
+```
+
+**Breakpoint behavior**:
+| Breakpoint | Stacks below |
+|------------|--------------|
+| `sm` | 576px |
+| `md` | 768px |
+| `lg` | 992px |
+| `xl` | 1200px |
+| `xxl` | 1400px |
+
+## Fieldset
+
+Semantic grouping with legend:
+
+```php
+ima_forms_fieldset([
+    'legend' => 'Shipping Address',
+    'description' => 'Where should we ship your order?',
+    'fieldset_class' => 'mb-4',
+    'disabled' => false,
+], function() use ($data, $errors) {
+    // Address fields
+});
+```
+
+**Use fieldset when**:
+- Grouping related fields semantically
+- Need to disable a group of fields together
+- Accessibility requirements (screen readers)
+
+**Use card when**:
+- Visual grouping with styling
+- Collapsible sections
+- Decorative separation