// ✅ 좋은 예
<header>
  <nav aria-label="메인 네비게이션">
    <ul>
      <li><a href="/">홈</a></li>
      <li><a href="/about">소개</a></li>
    </ul>
  </nav>
</header>
 
<main>
  <article>
    <h1>제목</h1>
    <p>본문 내용</p>
  </article>
</main>
 
// ❌ 나쁜 예
<div>
  <div>
    <div>홈</div>
    <div>소개</div>
  </div>
</div>

// ✅ 좋은 예
<Image
  src="/hero.jpg"
  alt="Poteco Studio의 팀이 함께 작업하는 모습"
  width={1200}
  height={630}
/>
 
// 장식용 이미지
<Image
  src="/decoration.jpg"
  alt=""
  width={100}
  height={100}
/>
 
// ❌ 나쁜 예
<img src="/hero.jpg" />

/* ✅ 좋은 예 - 충분한 대비 */
.text-primary {
  color: #1a1a1a; /* 배경이 #ffffff일 때 대비 16.5:1 */
  background-color: #ffffff;
}
 
/* ❌ 나쁜 예 - 대비 부족 */
.text-light {
  color: #cccccc; /* 배경이 #ffffff일 때 대비 1.6:1 */
  background-color: #ffffff;
}

// ✅ 좋은 예 - 키보드 접근 가능
<button
  onClick={handleClick}
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      handleClick();
    }
  }}
>
  클릭하세요
</button>
 
// 모달에서 키보드 트랩 방지
useEffect(() => {
  const handleEscape = (e: KeyboardEvent) => {
    if (e.key === 'Escape') {
      onClose();
    }
  };
  
  document.addEventListener('keydown', handleEscape);
  return () => document.removeEventListener('keydown', handleEscape);
}, [onClose]);

// ✅ 좋은 예
<button
  aria-label="메뉴 닫기"
  onClick={closeMenu}
>
  <CloseIcon aria-hidden="true" />
</button>
 
// 폼 오류 메시지
<label htmlFor="email">이메일</label>
<input
  id="email"
  type="email"
  aria-invalid={hasError}
  aria-describedby={hasError ? "email-error" : undefined}
/>
{hasError && (
  <span id="email-error" role="alert">
    올바른 이메일 형식을 입력해주세요
  </span>
)}

// ✅ 좋은 예
<form onSubmit={handleSubmit}>
  <div>
    <label htmlFor="name">
      이름 <span aria-label="필수 항목">*</span>
    </label>
    <input
      id="name"
      type="text"
      required
      aria-required="true"
      aria-invalid={errors.name ? 'true' : 'false'}
      aria-describedby={errors.name ? 'name-error' : undefined}
    />
    {errors.name && (
      <span id="name-error" role="alert">
        {errors.name}
      </span>
    )}
  </div>
</form>

// ✅ 스킵 링크
<a href="#main-content" className="sr-only focus:not-sr-only">
  메인 콘텐츠로 건너뛰기
</a>
 
<main id="main-content">
  {/* 메인 콘텐츠 */}
</main>
 
// 동적 콘텐츠 변경 알림
<div role="status" aria-live="polite" aria-atomic="true">
  {notification && <p>{notification}</p>}
</div>

/* ✅ 좋은 예 */
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}
 
/* 깜빡임 방지 */
.flash {
  animation: none; /* 3초에 3회 이상 깜빡이지 않도록 */
}

pnpm add -D eslint-plugin-jsx-a11y

// .eslintrc.js
module.exports = {
  plugins: ['jsx-a11y'],
  rules: {
    'jsx-a11y/alt-text': 'error',
    'jsx-a11y/anchor-is-valid': 'error',
    'jsx-a11y/aria-props': 'error',
    // ... 기타 규칙
  },
};

// Radix UI 사용 예시
import * as Dialog from '@radix-ui/react-dialog';
 
<Dialog.Root>
  <Dialog.Trigger>열기</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Title>제목</Dialog.Title>
      <Dialog.Description>설명</Dialog.Description>
      <Dialog.Close>닫기</Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

interface ButtonProps {
  children: React.ReactNode;
  onClick: () => void;
  ariaLabel?: string;
  disabled?: boolean;
}
 
export function AccessibleButton({
  children,
  onClick,
  ariaLabel,
  disabled = false,
}: ButtonProps) {
  return (
    <button
      onClick={onClick}
      disabled={disabled}
      aria-label={ariaLabel}
      aria-disabled={disabled}
      onKeyDown={(e) => {
        if ((e.key === 'Enter' || e.key === ' ') && !disabled) {
          e.preventDefault();
          onClick();
        }
      }}
      className={clsx(
        'px-4 py-2 rounded',
        'focus:outline-none focus:ring-2 focus:ring-primary',
        disabled && 'opacity-50 cursor-not-allowed'
      )}
    >
      {children}
    </button>
  );
}

export function AccessibleModal({
  isOpen,
  onClose,
  title,
  children,
}: ModalProps) {
  useEffect(() => {
    if (isOpen) {
      // 모달이 열릴 때 포커스를 모달로 이동
      const modal = document.getElementById('modal');
      modal?.focus();
      
      // 배경 스크롤 방지
      document.body.style.overflow = 'hidden';
    } else {
      document.body.style.overflow = '';
    }
  }, [isOpen]);
 
  if (!isOpen) return null;
 
  return (
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby="modal-title"
      id="modal"
      tabIndex={-1}
      className="fixed inset-0 z-50"
    >
      <div
        className="fixed inset-0 bg-black/50"
        onClick={onClose}
        aria-hidden="true"
      />
      <div className="fixed inset-0 flex items-center justify-center p-4">
        <div className="bg-white rounded-lg p-6 max-w-md w-full">
          <h2 id="modal-title" className="text-xl font-bold mb-4">
            {title}
          </h2>
          {children}
          <button
            onClick={onClose}
            aria-label="모달 닫기"
            className="mt-4"
          >
            닫기
          </button>
        </div>
      </div>
    </div>
  );
}