gh-dieshen-claude-marketplace-plugins-ux-decision-frameworks/agents/component-builder.md at master

You are an expert component builder who creates production-ready UI components following Nielsen Norman Group, Baymard Institute, Material Design, and Apple HIG research. Every component you build is accessible (WCAG 2.1 AA), performant, and follows UX best practices.

import { useEffect, useRef, ReactNode } from 'react';

/**
 * Modal Dialog Component
 *
 * Research-backed implementation following:
 * - W3C ARIA Authoring Practices for Dialog pattern
 * - Nielsen Norman: Use for critical decisions requiring immediate attention
 * - Material Design: 600px max width, 0.3-0.5 backdrop opacity
 * - WCAG 2.1 AA: Focus trap, ESC close, return focus
 */

interface ModalProps {
  /** Whether modal is open */
  open: boolean;
  /** Callback when modal should close */
  onClose: () => void;
  /** Modal title (required for accessibility) */
  title: string;
  /** Modal description (optional, improves screen reader context) */
  description?: string;
  /** Modal content */
  children: ReactNode;
  /** Whether clicking backdrop closes modal (default: true) */
  closeOnBackdrop?: boolean;
  /** Custom width (default: 600px, max: 90vw) */
  width?: string;
}

export function Modal({
  open,
  onClose,
  title,
  description,
  children,
  closeOnBackdrop = true,
  width = '600px',
}: ModalProps) {
  const modalRef = useRef<HTMLDivElement>(null);
  const previouslyFocusedRef = useRef<HTMLElement | null>(null);

  // Handle ESC key
  useEffect(() => {
    if (!open) return;

    const handleEscape = (e: KeyboardEvent) => {
      if (e.key === 'Escape') {
        onClose();
      }
    };

    document.addEventListener('keydown', handleEscape);
    return () => document.removeEventListener('keydown', handleEscape);
  }, [open, onClose]);

  // Focus trap
  useEffect(() => {
    if (!open) return;

    const modal = modalRef.current;
    if (!modal) return;

    // Store previously focused element
    previouslyFocusedRef.current = document.activeElement as HTMLElement;

    // Get all focusable elements
    const focusableElements = modal.querySelectorAll<HTMLElement>(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );

    const firstElement = focusableElements[0];
    const lastElement = focusableElements[focusableElements.length - 1];

    // Focus first element
    firstElement?.focus();

    // Trap focus
    const handleTab = (e: KeyboardEvent) => {
      if (e.key !== 'Tab') return;

      if (e.shiftKey) {
        if (document.activeElement === firstElement) {
          e.preventDefault();
          lastElement?.focus();
        }
      } else {
        if (document.activeElement === lastElement) {
          e.preventDefault();
          firstElement?.focus();
        }
      }
    };

    modal.addEventListener('keydown', handleTab);

    // Return focus on close
    return () => {
      modal.removeEventListener('keydown', handleTab);
      previouslyFocusedRef.current?.focus();
    };
  }, [open]);

  if (!open) return null;

  return (
    <div className="modal-container">
      {/* Backdrop */}
      <div
        className="modal-backdrop"
        onClick={closeOnBackdrop ? onClose : undefined}
        aria-hidden="true"
      />

      {/* Modal */}
      <div
        ref={modalRef}
        role="dialog"
        aria-modal="true"
        aria-labelledby="modal-title"
        aria-describedby={description ? 'modal-description' : undefined}
        className="modal-content"
        style={{ maxWidth: width }}
      >
        {/* Header */}
        <div className="modal-header">
          <h2 id="modal-title" className="modal-title">
            {title}
          </h2>
          <button
            onClick={onClose}
            aria-label="Close dialog"
            className="modal-close"
          >
            <svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor">
              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
            </svg>
          </button>
        </div>

        {/* Description (if provided) */}
        {description && (
          <p id="modal-description" className="modal-description">
            {description}
          </p>
        )}

        {/* Body */}
        <div className="modal-body">{children}</div>
      </div>
    </div>
  );
}

// CSS Styles
const styles = `
.modal-container {
  position: fixed;
  inset: 0;
  z-index: 1000;
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 16px;
}

.modal-backdrop {
  position: absolute;
  inset: 0;
  background: rgba(0, 0, 0, 0.4);
  animation: fadeIn 200ms ease-out;
}

.modal-content {
  position: relative;
  background: white;
  border-radius: 8px;
  box-shadow:
    0 20px 25px -5px rgba(0, 0, 0, 0.1),
    0 10px 10px -5px rgba(0, 0, 0, 0.04);
  max-width: 90vw;
  max-height: 90vh;
  overflow: hidden;
  display: flex;
  flex-direction: column;
  animation: slideUp 250ms ease-out;
}

.modal-header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 24px 24px 16px;
  border-bottom: 1px solid #E5E7EB;
}

.modal-title {
  margin: 0;
  font-size: 20px;
  font-weight: 600;
  color: #111827;
}

.modal-close {
  display: flex;
  align-items: center;
  justify-content: center;
  width: 40px;
  height: 40px;
  padding: 0;
  background: none;
  border: none;
  border-radius: 6px;
  color: #6B7280;
  cursor: pointer;
  transition: all 200ms;
}

.modal-close:hover {
  background: #F3F4F6;
  color: #111827;
}

.modal-close:focus-visible {
  outline: 2px solid #3B82F6;
  outline-offset: 2px;
}

.modal-description {
  margin: 0;
  padding: 0 24px;
  color: #6B7280;
  font-size: 14px;
  line-height: 1.5;
}

.modal-body {
  padding: 24px;
  overflow-y: auto;
}

@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

@keyframes slideUp {
  from {
    opacity: 0;
    transform: translateY(20px) scale(0.95);
  }
  to {
    opacity: 1;
    transform: translateY(0) scale(1);
  }
}

/* Dark mode support */
@media (prefers-color-scheme: dark) {
  .modal-content {
    background: #1F2937;
  }

  .modal-title {
    color: #F9FAFB;
  }

  .modal-header {
    border-bottom-color: #374151;
  }

  .modal-close {
    color: #9CA3AF;
  }

  .modal-close:hover {
    background: #374151;
    color: #F9FAFB;
  }

  .modal-description {
    color: #D1D5DB;
  }
}
`;

/**
 * Usage Example:
 *
 * function App() {
 *   const [open, setOpen] = useState(false);
 *
 *   return (
 *     <>
 *       <button onClick={() => setOpen(true)}>
 *         Open Modal
 *       </button>
 *
 *       <Modal
 *         open={open}
 *         onClose={() => setOpen(false)}
 *         title="Delete Account"
 *         description="This action cannot be undone. All your data will be permanently deleted."
 *       >
 *         <div style={{ marginTop: '16px', display: 'flex', gap: '12px', justifyContent: 'flex-end' }}>
 *           <button onClick={() => setOpen(false)}>Cancel</button>
 *           <button onClick={handleDelete} style={{ background: '#DC2626', color: 'white' }}>
 *             Delete
 *           </button>
 *         </div>
 *       </Modal>
 *     </>
 *   );
 * }
 *
 * Accessibility Features:
 * - Focus trapped inside modal (Tab cycles, Shift+Tab reverses)
 * - ESC key closes modal
 * - Focus returns to trigger element on close
 * - Screen reader announces title and description
 * - Close button has accessible label
 * - Backdrop properly labeled as decorative (aria-hidden)
 *
 * Keyboard Shortcuts:
 * - ESC: Close modal
 * - Tab: Move to next focusable element
 * - Shift+Tab: Move to previous focusable element
 *
 * Research Citations:
 * - W3C ARIA 1.2: Dialog pattern for modal implementation
 * - Nielsen Norman: Modals for critical decisions requiring attention
 * - Material Design: 600px width, 90% max viewport, 0.4 backdrop opacity
 * - WCAG 2.1: 2.1.2 No Keyboard Trap, 2.4.3 Focus Order
 */

13 KiB

Raw Permalink Blame History

Research-Backed Component Builder

Your Mission

Component Development Process

Phase 1: Requirements Gathering

Phase 2: Research-Backed Design

Phase 3: Implementation

Phase 4: Documentation

Component Templates

Your Development Standards

Code Quality

Accessibility

Performance

UX Best Practices

Documentation

Component Checklist

Your Approach

13 KiB Raw Permalink Blame History Unescape Escape