프론트엔드 접근성 패턴

프론트엔드 접근성 패턴은(는) 무엇을 하나요?

React와 Next.js를 위한 실용적인 접근성 패턴입니다. 코드 리뷰에서 가장 자주 지적되는 문제(누락된 폼 레이블, 잘못된 ARIA 사용, 비의미론적 인터랙티브 요소, 깨진 키보드 탐색)를 다룹니다.

활성화 시점

• 폼 컴포넌트(<input>, <select>, <textarea>)를 빌드하거나 리뷰할 때
• 인터랙티브 요소(모달, 드롭다운, 툴팁, 탭)를 만들 때
• onClick과 함께 <div> 또는 <span>을 사용할 때
• 요소에 aria-* 속성을 추가할 때
• 키보드 탐색 또는 포커스 관리를 구현할 때
• 코드 리뷰 도구(CodeRabbit, ESLint a11y)로부터 접근성 피드백을 받을 때
• 스크린 리더를 지원해야 하는 컴포넌트를 빌드할 때

폼 접근성

htmlFor / id 연결 누락 및 분리된 오류 메시지는 코드 리뷰에서 가장 자주 지적되는 문제입니다.

레이블 연결

// BAD: 레이블이 input과 연결되지 않음 — 스크린 리더가 연관시킬 수 없음
<label>이메일</label>
<input type="email" />

// GOOD: htmlFor가 input id와 일치함
<label htmlFor="email">이메일</label>
<input id="email" type="email" />

필수 입력 필드

// BAD: 시각적 별표만으로 스크린 리더에 아무 정보도 전달되지 않음
<label htmlFor="email">이메일 *</label>
<input id="email" type="email" />

// GOOD: required는 브라우저 내장 유효성 검사를 활성화하고, aria-required는 스크린 리더에 신호를 보냄
<label htmlFor="email">
  이메일 <span aria-hidden="true">*</span>
</label>
<input id="email" type="email" required aria-required="true" />

오류 메시지

// BAD: 오류 텍스트가 시각적으로는 존재하지만 input과 연결되지 않음
<input id="email" type="email" />
<span className="error">잘못된 이메일 주소입니다</span>

// GOOD: aria-describedby가 input을 오류 메시지에 연결함
// aria-invalid가 스크린 리더에 잘못된 상태를 신호로 전달함
<input
  id="email"
  type="email"
  aria-describedby="email-error"
  aria-invalid={!!error}
/>
{error && (
  <span id="email-error" role="alert">
    {error}
  </span>
)}

완전한 접근성 폼

interface LoginFormProps {
  onSubmit: (email: string, password: string) => void;
}

export function LoginForm({ onSubmit }: LoginFormProps) {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [errors, setErrors] = useState<{ email?: string; password?: string }>({});

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    const newErrors: typeof errors = {};
    if (!email) newErrors.email = '이메일을 입력해주세요';
    if (!password) newErrors.password = '비밀번호를 입력해주세요';
    if (Object.keys(newErrors).length) {
      setErrors(newErrors);
      return;
    }
    onSubmit(email, password);
  };

  return (
    <form onSubmit={handleSubmit} noValidate>
      <div>
        <label htmlFor="email">
          이메일 <span aria-hidden="true">*</span>
        </label>
        <input
          id="email"
          type="email"
          value={email}
          onChange={e => setEmail(e.target.value)}
          aria-required="true"
          aria-describedby={errors.email ? 'email-error' : undefined}
          aria-invalid={!!errors.email}
          autoComplete="email"
        />
        {errors.email && (
          <span id="email-error" role="alert">
            {errors.email}
          </span>
        )}
      </div>

      <div>
        <label htmlFor="password">
          비밀번호 <span aria-hidden="true">*</span>
        </label>
        <input
          id="password"
          type="password"
          value={password}
          onChange={e => setPassword(e.target.value)}
          aria-required="true"
          aria-describedby={errors.password ? 'password-error' : undefined}
          aria-invalid={!!errors.password}
          autoComplete="current-password"
        />
        {errors.password && (
          <span id="password-error" role="alert">
            {errors.password}
          </span>
        )}
      </div>

      <button type="submit">로그인</button>
    </form>
  );
}

시맨틱 HTML

의도에 맞는 요소를 사용하세요. 스크린 리더와 키보드 사용자는 네이티브 시맨틱에 의존합니다.

// BAD: role, 키보드 지원, 접근 가능한 이름이 없는 div
<div onClick={handleClick}>제출</div>

// GOOD: button은 포커스 가능하고, Enter/Space로 활성화되며, "button"으로 알림
<button type="button" onClick={handleClick}>제출</button>

// BAD: 비의미론적 탐색
<div onClick={() => navigate('/home')}>홈</div>

// GOOD: anchor는 우클릭, 중간 클릭, 키보드 탐색 지원
<a href="/home">홈</a>

// BAD: 제목 계층 생략 (h1에서 h4로)
<h1>대시보드</h1>
<h4>최근 활동</h4>

// GOOD: 순차적인 제목 수준
<h1>대시보드</h1>
<h2>최근 활동</h2>

ARIA 속성

네이티브 HTML 시맨틱이 충분하지 않을 때만 ARIA를 사용하세요. 잘못된 ARIA는 ARIA가 없는 것보다 나쁩니다.

aria-label vs aria-labelledby

// aria-label: 인라인 문자열 레이블 — 보이는 레이블 텍스트가 없을 때 사용
<button aria-label="모달 닫기">
  <XIcon />
</button>

// aria-labelledby: 다른 요소의 텍스트를 참조 — 보이는 레이블이 있을 때 사용
<section aria-labelledby="section-title">
  <h2 id="section-title">최근 주문</h2>
  {/* 내용 */}
</section>

aria-describedby

// 레이블 외에 추가 설명 제공
<button
  aria-describedby="삭제-경고"
  onClick={handleDelete}
> 계정 삭제
</button>
<p id="삭제-경고">이 작업은 되돌릴 수 없습니다.</p>

동적 콘텐츠를 위한 aria-live

// 페이지 새로고침 없이 업데이트되는 콘텐츠를 알리려면 aria-live 사용
// polite: 사용자가 현재 작업을 마칠 때까지 기다렸다가 알림
// assertive: 즉시 중단 — 긴급 오류에만 사용

export function StatusMessage({ message, isError }: { message: string; isError?: boolean }) {
  return (
    <div role="status" aria-live={isError ? 'assertive' : 'polite'} aria-atomic="true">
      {message}
    </div>
  );
}

aria-expanded와 aria-controls

export function Accordion({ title, children }: { title: string; children: React.ReactNode }) {
  const [isOpen, setIsOpen] = useState(false);
  const contentId = useId();

  return (
    <div>
      <button aria-expanded={isOpen} aria-controls={contentId} onClick={() => setIsOpen(prev => !prev)}>
        {title}
      </button>
      <div id={contentId} hidden={!isOpen}>
        {children}
      </div>
    </div>
  );
}

키보드 탐색

모든 인터랙티브 요소는 키보드만으로 접근 가능하고 작동 가능해야 합니다.

커스텀 드롭다운

export function Dropdown({ options, onSelect }: { options: string[]; onSelect: (value: string) => void }) {
  const [isOpen, setIsOpen] = useState(false);
  const [activeIndex, setActiveIndex] = useState(0);
  const listId = useId();

  if (!options.length) return null;

  const handleKeyDown = (e: React.KeyboardEvent) => {
    switch (e.key) {
      case 'ArrowDown':
        e.preventDefault();
        setActiveIndex(i => Math.min(i + 1, options.length - 1));
        break;
      case 'ArrowUp':
        e.preventDefault();
        setActiveIndex(i => Math.max(i - 1, 0));
        break;
      case 'Enter':
      case ' ':
        e.preventDefault();
        if (isOpen) onSelect(options[activeIndex]);
        setIsOpen(prev => !prev);
        break;
      case 'Escape':
        setIsOpen(false);
        break;
    }
  };

  return (
    <div
      role="combobox"
      aria-expanded={isOpen}
      aria-haspopup="listbox"
      aria-controls={listId}
      tabIndex={0}
      onKeyDown={handleKeyDown}
      onClick={() => setIsOpen(prev => !prev)}
    >
      <span>{options[activeIndex]}</span>
      {isOpen && (
        <ul id={listId} role="listbox">
          {options.map((option, index) => (
            <li
              key={option}
              role="option"
              aria-selected={index === activeIndex}
              onClick={() => {
                onSelect(option);
                setIsOpen(false);
              }}
            >
              {option}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

포커스 관리

UI 상태가 변경될 때(특히 모달 및 경로 전환) 포커스가 논리적으로 이동해야 합니다.

모달 포커스 복원

이 예제는 초기 포커스와 복원을 다룹니다. 전체 포커스 트랩(모달 내 Tab/Shift+Tab 순환)을 위해서는 동적 콘텐츠 및 중첩 포털과 같은 엣지 케이스를 처리하는 focus-trap-react와 같은 라이브러리를 사용하세요.

export function Modal({ isOpen, onClose, title, children }: { isOpen: boolean; onClose: () => void; title: string; children: React.ReactNode }) {
  const modalRef = useRef<HTMLDivElement>(null);
  const previousFocusRef = useRef<HTMLElement | null>(null);

  useEffect(() => {
    if (isOpen) {
      // 현재 포커스된 요소를 저장하고 모달로 포커스 이동
      previousFocusRef.current = document.activeElement as HTMLElement;
      modalRef.current?.focus();
    } else {
      // 모달을 연 요소로 포커스 복원
      previousFocusRef.current?.focus();
    }
  }, [isOpen]);

  if (!isOpen) return null;

  return (
    <div ref={modalRef} role="dialog" aria-modal="true" aria-labelledby="modal-title" tabIndex={-1} onKeyDown={e => e.key === 'Escape' && onClose()}>
      <h2 id="modal-title">{title}</h2>
      {children}
      <button onClick={onClose}>닫기</button>
    </div>
  );
}

이미지 및 아이콘

// BAD: 장식용 아이콘이 레이블 없는 이미지로 알림됨
<img src="/icon.svg" />

// GOOD: 장식용 이미지가 스크린 리더에서 숨겨짐
<img src="/decoration.png" alt="" aria-hidden="true" />

// GOOD: 설명적인 대체 텍스트가 있는 의미 있는 이미지
<img src="/chart.png" alt="월별 수익이 1월부터 3월까지 23% 증가했습니다" />

// GOOD: 접근 가능한 레이블이 있는 아이콘 버튼
<button aria-label="항목 삭제">
  <TrashIcon aria-hidden="true" />
</button>

동작 줄이기

운영 체제 설정에서 동작 줄이기를 요청한 사용자를 존중하세요.

export function useReducedMotion(): boolean {
  const [prefersReduced, setPrefersReduced] = useState(false);

  useEffect(() => {
    const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
    setPrefersReduced(mq.matches);
    const handler = (e: MediaQueryListEvent) => setPrefersReduced(e.matches);
    mq.addEventListener('change', handler);
    return () => mq.removeEventListener('change', handler);
  }, []);

  return prefersReduced;
}

// 사용법
export function AnimatedCard({ children }: { children: React.ReactNode }) {
  const reduceMotion = useReducedMotion();

  return (
    <div
      style={{
        transition: reduceMotion ? 'none' : 'transform 300ms ease'
      }}
    >
      {children}
    </div>
  );
}

안티 패턴

// BAD: 키보드 지원이 없는 비인터랙티브 요소의 onClick
<div onClick={handleClick}>클릭하세요</div>

// BAD: role이 없는 div에 aria-label 사용
<div aria-label="탐색">...</div>

// BAD: 레이블 대신 placeholder 사용
<input placeholder="이메일을 입력하세요" />

// BAD: 양수 tabIndex는 예측 불가능한 탭 순서를 만듦
<button tabIndex={3}>제출</button>

// BAD: 포커스 가능한 요소에 aria-hidden — 키보드 사용자가 갇힘
<button aria-hidden="true">열기</button>

// BAD: 키보드 핸들러가 없는 div에 role="button"
<div role="button" onClick={handleClick}>제출</div>
// 누락: tabIndex={0}, Enter/Space를 위한 onKeyDown

체크리스트

리뷰를 위해 인터랙티브 컴포넌트를 제출하기 전에:

• 모든 <input>, <select>, <textarea>가 htmlFor/id를 통해 연결된 <label>을 가지고 있는가?
• 오류 메시지가 aria-describedby로 연결되고 role="alert"로 표시되었는가?
• <div> 또는 <span>에 role, tabIndex, onKeyDown 없이 onClick이 사용되지 않았는가?
• 아이콘 전용 버튼에 aria-label이 있는가?
• 장식용 이미지에 alt=""와 aria-hidden="true"가 사용되었는가?
• 모달이 닫힐 때 포커스를 복원하는가? (Tab/Shift+Tab 순환을 통한 전체 포커스 트래핑은 focus-trap-react와 같은 라이브러리 사용)
• 동적 콘텐츠 업데이트에 aria-live가 사용되었는가?
• 애니메이션에 대해 prefers-reduced-motion이 존중되는가?

관련 스킬

• frontend-patterns — 일반적인 React 컴포넌트 및 상태 패턴
• design-system — 디자인 토큰 및 컴포넌트 일관성
• motion-foundations 및 motion-patterns: 접근성 고려 사항이 포함된 애니메이션 패턴