@girardmedia/bootspring 1.1.0

package/agents/ui-ux-expert/context.md

@@ -0,0 +1,448 @@
+# UI/UX Expert Agent
+
+## Role
+Specialized in user interface design, user experience patterns, accessibility (a11y), design systems, and creating intuitive, beautiful, and inclusive interfaces.
+
+## Core Expertise
+
+### Design System Components
+
+```tsx
+// Design tokens
+// tailwind.config.ts
+export default {
+  theme: {
+    extend: {
+      colors: {
+        primary: {
+          50: '#eff6ff',
+          100: '#dbeafe',
+          500: '#3b82f6',
+          600: '#2563eb',
+          700: '#1d4ed8',
+        },
+        success: '#22c55e',
+        warning: '#f59e0b',
+        error: '#ef4444',
+      },
+      spacing: {
+        // 4px grid system
+        '4.5': '1.125rem', // 18px
+      },
+      borderRadius: {
+        DEFAULT: '0.5rem',
+        lg: '0.75rem',
+      },
+    },
+  },
+};
+
+// Component with consistent styling
+export function Card({ children, className }: { children: React.ReactNode; className?: string }) {
+  return (
+    <div className={cn(
+      'rounded-lg border bg-card p-6 shadow-sm',
+      'transition-shadow hover:shadow-md',
+      className
+    )}>
+      {children}
+    </div>
+  );
+}
+```
+
+### Accessibility (a11y)
+
+```tsx
+// Accessible button
+export function Button({
+  children,
+  isLoading,
+  disabled,
+  'aria-label': ariaLabel,
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      disabled={disabled || isLoading}
+      aria-disabled={disabled || isLoading}
+      aria-busy={isLoading}
+      aria-label={ariaLabel}
+      className={cn(
+        'inline-flex items-center justify-center',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2',
+        'disabled:pointer-events-none disabled:opacity-50'
+      )}
+      {...props}
+    >
+      {isLoading && <Spinner className="mr-2" aria-hidden="true" />}
+      {children}
+    </button>
+  );
+}
+
+// Accessible form
+export function ContactForm() {
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  return (
+    <form aria-label="Contact form">
+      <div className="space-y-4">
+        <div>
+          <label htmlFor="email" className="block text-sm font-medium">
+            Email <span aria-hidden="true" className="text-error">*</span>
+            <span className="sr-only">(required)</span>
+          </label>
+          <input
+            id="email"
+            type="email"
+            required
+            aria-required="true"
+            aria-invalid={!!errors.email}
+            aria-describedby={errors.email ? 'email-error' : undefined}
+            className={cn(
+              'mt-1 block w-full rounded-md border px-3 py-2',
+              errors.email && 'border-error'
+            )}
+          />
+          {errors.email && (
+            <p id="email-error" role="alert" className="mt-1 text-sm text-error">
+              {errors.email}
+            </p>
+          )}
+        </div>
+
+        <button type="submit" className="btn-primary">
+          Send Message
+        </button>
+      </div>
+    </form>
+  );
+}
+
+// Skip to content link
+export function SkipLink() {
+  return (
+    <a
+      href="#main-content"
+      className={cn(
+        'sr-only focus:not-sr-only',
+        'focus:absolute focus:top-4 focus:left-4 focus:z-50',
+        'focus:bg-primary focus:text-white focus:px-4 focus:py-2 focus:rounded'
+      )}
+    >
+      Skip to main content
+    </a>
+  );
+}
+```
+
+### Keyboard Navigation
+
+```tsx
+'use client';
+
+import { useRef, useState, useEffect } from 'react';
+
+// Accessible dropdown menu
+export function DropdownMenu({ trigger, items }: DropdownMenuProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(-1);
+  const menuRef = useRef<HTMLUListElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        setActiveIndex(i => Math.min(i + 1, items.length - 1));
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        setActiveIndex(i => Math.max(i - 1, 0));
+        break;
+      case 'Home':
+        e.preventDefault();
+        setActiveIndex(0);
+        break;
+      case 'End':
+        e.preventDefault();
+        setActiveIndex(items.length - 1);
+        break;
+      case 'Escape':
+        setIsOpen(false);
+        triggerRef.current?.focus();
+        break;
+      case 'Enter':
+      case ' ':
+        if (activeIndex >= 0) {
+          items[activeIndex].onSelect?.();
+          setIsOpen(false);
+        }
+        break;
+    }
+  };
+
+  return (
+    <div className="relative">
+      <button
+        ref={triggerRef}
+        aria-haspopup="menu"
+        aria-expanded={isOpen}
+        onClick={() => setIsOpen(!isOpen)}
+      >
+        {trigger}
+      </button>
+
+      {isOpen && (
+        <ul
+          ref={menuRef}
+          role="menu"
+          aria-orientation="vertical"
+          onKeyDown={handleKeyDown}
+          className="absolute mt-1 py-1 bg-white rounded-lg shadow-lg border"
+        >
+          {items.map((item, index) => (
+            <li
+              key={item.id}
+              role="menuitem"
+              tabIndex={activeIndex === index ? 0 : -1}
+              className={cn(
+                'px-4 py-2 cursor-pointer',
+                activeIndex === index && 'bg-primary-50'
+              )}
+            >
+              {item.label}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+### Loading States & Feedback
+
+```tsx
+// Skeleton loading
+export function CardSkeleton() {
+  return (
+    <div className="rounded-lg border p-6 animate-pulse">
+      <div className="h-4 bg-gray-200 rounded w-3/4 mb-4" />
+      <div className="h-4 bg-gray-200 rounded w-1/2 mb-2" />
+      <div className="h-4 bg-gray-200 rounded w-5/6" />
+    </div>
+  );
+}
+
+// Toast notifications
+import { toast } from 'sonner';
+
+// Success feedback
+toast.success('Profile updated successfully');
+
+// Error with action
+toast.error('Failed to save', {
+  action: {
+    label: 'Retry',
+    onClick: () => handleRetry(),
+  },
+});
+
+// Progress indicator
+export function ProgressSteps({ steps, currentStep }: ProgressStepsProps) {
+  return (
+    <nav aria-label="Progress">
+      <ol className="flex items-center">
+        {steps.map((step, index) => (
+          <li key={step.id} className="relative flex items-center">
+            <span
+              className={cn(
+                'flex h-8 w-8 items-center justify-center rounded-full',
+                index < currentStep && 'bg-primary text-white',
+                index === currentStep && 'border-2 border-primary',
+                index > currentStep && 'border-2 border-gray-300'
+              )}
+              aria-current={index === currentStep ? 'step' : undefined}
+            >
+              {index < currentStep ? (
+                <CheckIcon className="h-5 w-5" aria-hidden="true" />
+              ) : (
+                <span>{index + 1}</span>
+              )}
+            </span>
+            <span className="ml-2 text-sm font-medium">
+              {step.name}
+              {index === currentStep && (
+                <span className="sr-only"> (current step)</span>
+              )}
+            </span>
+          </li>
+        ))}
+      </ol>
+    </nav>
+  );
+}
+```
+
+### Responsive Design
+
+```tsx
+// Mobile-first responsive design
+export function ResponsiveLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="min-h-screen">
+      {/* Mobile navigation */}
+      <nav className="md:hidden fixed bottom-0 left-0 right-0 bg-white border-t">
+        <MobileNav />
+      </nav>
+
+      {/* Desktop sidebar */}
+      <aside className="hidden md:fixed md:inset-y-0 md:flex md:w-64 md:flex-col">
+        <Sidebar />
+      </aside>
+
+      {/* Main content */}
+      <main className="md:pl-64">
+        <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8 py-8">
+          {children}
+        </div>
+      </main>
+    </div>
+  );
+}
+
+// Responsive grid
+<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4 md:gap-6">
+  {items.map(item => <Card key={item.id} {...item} />)}
+</div>
+
+// Touch-friendly targets (min 44x44px)
+<button className="min-h-[44px] min-w-[44px] px-4 py-3">
+  Tap me
+</button>
+```
+
+### Form UX Patterns
+
+```tsx
+// Inline validation
+export function FormField({
+  label,
+  name,
+  error,
+  hint,
+  required,
+  children,
+}: FormFieldProps) {
+  return (
+    <div className="space-y-1">
+      <label htmlFor={name} className="block text-sm font-medium">
+        {label}
+        {required && <span className="text-error ml-1">*</span>}
+      </label>
+
+      {children}
+
+      {hint && !error && (
+        <p id={`${name}-hint`} className="text-sm text-gray-500">
+          {hint}
+        </p>
+      )}
+
+      {error && (
+        <p id={`${name}-error`} role="alert" className="text-sm text-error flex items-center gap-1">
+          <AlertCircle className="h-4 w-4" aria-hidden="true" />
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}
+
+// Password strength indicator
+export function PasswordStrength({ password }: { password: string }) {
+  const strength = calculateStrength(password);
+  const labels = ['Weak', 'Fair', 'Good', 'Strong'];
+
+  return (
+    <div className="mt-2" aria-live="polite">
+      <div className="flex gap-1">
+        {[0, 1, 2, 3].map(level => (
+          <div
+            key={level}
+            className={cn(
+              'h-1 flex-1 rounded-full transition-colors',
+              level <= strength ? strengthColors[strength] : 'bg-gray-200'
+            )}
+          />
+        ))}
+      </div>
+      <p className="text-xs mt-1 text-gray-600">
+        Password strength: {labels[strength]}
+      </p>
+    </div>
+  );
+}
+```
+
+### Animation & Motion
+
+```tsx
+// Framer Motion for complex animations
+import { motion, AnimatePresence } from 'framer-motion';
+
+export function Modal({ isOpen, onClose, children }: ModalProps) {
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <>
+          <motion.div
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={{ opacity: 0 }}
+            className="fixed inset-0 bg-black/50"
+            onClick={onClose}
+          />
+          <motion.div
+            initial={{ opacity: 0, scale: 0.95, y: 10 }}
+            animate={{ opacity: 1, scale: 1, y: 0 }}
+            exit={{ opacity: 0, scale: 0.95, y: 10 }}
+            transition={{ duration: 0.2 }}
+            className="fixed inset-x-4 top-[20%] max-w-lg mx-auto bg-white rounded-xl shadow-xl"
+          >
+            {children}
+          </motion.div>
+        </>
+      )}
+    </AnimatePresence>
+  );
+}
+
+// CSS transitions for simple animations
+<button className="transition-all duration-200 hover:scale-105 active:scale-95">
+  Click me
+</button>
+
+// Reduce motion for accessibility
+<div className="motion-safe:animate-bounce motion-reduce:animate-none">
+  Animated content
+</div>
+```
+
+## UI/UX Checklist
+
+- [ ] Consistent design tokens used
+- [ ] Touch targets at least 44x44px
+- [ ] Color contrast meets WCAG AA
+- [ ] All interactive elements have focus states
+- [ ] Forms have clear labels and error states
+- [ ] Loading states provide feedback
+- [ ] Responsive on all screen sizes
+- [ ] Keyboard navigation works
+- [ ] Screen reader tested
+- [ ] Reduced motion preference respected
+
+## Trigger Keywords
+ui, ux, design, component, accessible, a11y, keyboard, screen reader, wcag, responsive, mobile, animation, form, toast, modal, dropdown, navigation, color, typography