웹 접근성 이슈가 프로덕션에만 나타날 때

접근성 문제는 시각적으로 보이지 않지만, 스크린리더 사용자나 키보드만 쓰는 사람에겐 심각하다. 문제는 보통 빌드 과정에서 발생한다.

스크린리더로 직접 테스트

Windows는 Narrator, macOS는 VoiceOver, Linux는 Orca를 쓸 수 있다.

# macOS에서 VoiceOver 시작
Command + F5

앱을 읽을 때 무엇이 공개되는지 들어본다. 버튼이 버튼으로 읽히는지, 이미지에 alt 텍스트가 있는지, 폼 필드에 라벨이 연결됐는지 확인한다.

키보드 네비게이션 확인

마우스를 완전히 빼고 Tab, Shift+Tab, Enter로만 조작해본다.

# 포커스 아웃라인을 더 눈에 띄게 하려면
# 브라우저 개발자 도구 > Settings > Elements > Show user agent shadow DOM 체크

모든 interactive 요소(버튼, 링크, 입력)에 포커스할 수 있어야 한다. 만약 특정 요소에서 포커스가 건너뛰면, tabindex가 잘못 설정됐거나, 요소가 focusable하지 않다는 뜻이다.

색상 대비 확인

텍스트와 배경의 명도 대비가 충분한지 확인한다. WCAG 2.1 기준으로 일반 텍스트는 최소 4.5:1, 큰 텍스트는 3:1이어야 한다.

chrome DevTools에서 color picker를 열고, 대비 비율을 바로 볼 수 있다.

빌드 후 생성된 HTML 검사

프로덕션 빌드 후 실제 HTML을 확인한다. Next.js라면:

npm run build
npm run start

# 브라우저에서 View Source를 보고 실제로 semantic HTML이 있는지 확인
# 예: <button>이 <div className="button">으로 컴파일되진 않았는지

특히 CSS-in-JS를 쓰거나 동적으로 요소를 만들 때, 접근성 속성들이 빠질 수 있다.

ARIA 속성 확인

aria-label, aria-labelledby, aria-describedby, aria-live 등이 제대로 붙어 있는지 확인한다.

// 버튼에 텍스트가 없으면
<button aria-label="Menu">
  <MenuIcon />
</button>

// 동적 알림
<div aria-live="polite" aria-atomic="true">
  {message}
</div>

브라우저 확장 프로그램으로 자동 검사

Axe DevTools나 Lighthouse (Chrome DevTools > Lighthouse)로 접근성 문제를 자동 검사할 수 있다.

# 터미널에서도 가능
npm install -g @axe-core/cli
axe https://example.com

자동 검사는 모든 문제를 찾지 못하지만, 명백한 이슈들(alt 텍스트 누락, 색상 대비 부족, heading 구조 오류)은 빠르게 잡을 수 있다.

로컬과 프로덕션의 차이 추적

가장 흔한 원인은 빌드 최적화다. CSS 클래스명이 축약되거나, 동적 콘텐츠가 초기 렌더링에서 누락될 수 있다.

dev 환경과 production 환경을 명시적으로 번갈아 테스트하면서, 어디서부터 문제가 생기는지 찾는다. 보통 build process나 배포 환경 설정에서 접근성 관련 플러그인이 빠진 경우가 많다.