개발자 모범 사례

접근성 코드 리뷰

Accessibility in Code Review

코드 리뷰 체크 항목: 모든 인터랙티브 요소가 키보드로 접근 가능한가, 시맨틱 HTML을 올바르게 사용했는가, 이미지에 적절한 alt가 있는가, 폼 레이블이 연결되었는가, ARIA가 올바르게 쓰였는가(불필요한 ARIA는 없는가), 색상 대비가 충분한가, 포커스 관리가 적절한가.

Code review checklist: are all interactive elements keyboard-accessible; is semantic HTML used correctly; do images have appropriate alt; are form labels associated; is ARIA used correctly (and none unnecessarily); is contrast sufficient; is focus managed properly?

리뷰를 지속 가능하게 만드는 장치: 체크리스트를 PR 템플릿에 포함하고, eslint-plugin-jsx-a11y 같은 린터로 기계가 잡을 수 있는 것은 기계에 맡기며, 접근성을 완료 정의(Definition of Done)에 포함시킵니다. '접근성 리뷰 통과 전에는 머지하지 않는다'는 규칙이 리뷰 문화를 만듭니다.

Making review sustainable: put the checklist in the PR template, let linters like eslint-plugin-jsx-a11y catch what machines can, and include accessibility in the Definition of Done. A 'no merge before accessibility review' rule is what builds the culture.

APG와 접근 가능한 컴포넌트

The APG and Accessible Components

커스텀 위젯(탭, 아코디언, 콤보박스, 모달)을 만들 때의 표준 참고서는 WAI-ARIA Authoring Practices Guide(APG)입니다. 각 패턴의 역할 구조, 키보드 상호작용, ARIA 상태 관리를 예제와 함께 제공합니다 — 새 위젯을 만들기 전에 해당 APG 패턴부터 확인하는 습관이 중요합니다.

The standard reference for custom widgets (tabs, accordions, comboboxes, modals) is the WAI-ARIA Authoring Practices Guide (APG). It provides each pattern's role structure, keyboard interaction, and ARIA state management with examples — check the APG pattern before building any new widget.

컴포넌트 설계 원칙: 시맨틱 HTML 기반 위에 구축하고, 상태 변경 시 ARIA 상태를 갱신하며, 터치 타깃을 충분히 크게 유지합니다(WCAG 2.5.5 AAA는 44×44px, 2.2의 2.5.8 AA는 최소 24×24px). 컴포넌트 문서에 접근성 사용법(필수 prop, 키보드 동작)을 포함하면 라이브러리 사용자 전체의 품질이 올라갑니다.

Component design principles: build on semantic HTML, update ARIA states on change, and keep touch targets large (WCAG 2.5.5 AAA: 44×44px; 2.2's 2.5.8 AA: at least 24×24px). Documenting accessibility usage (required props, keyboard behavior) in component docs raises quality for every consumer of the library.

프레임워크별 지원

Framework Support

React: JSX에서 htmlFor(for 대체), aria-* 속성 직접 사용, Fragment로 불필요한 래퍼 DOM 방지. Next.js: next/image의 alt 필수화, 라우팅 시 접근성 알림 내장. Vue: v-bind로 동적 ARIA 바인딩. Angular: CDK a11y 모듈(FocusTrap, LiveAnnouncer, 고대비 감지).

React: htmlFor in JSX (replacing for), direct aria-* attributes, Fragments to avoid wrapper DOM. Next.js: enforced alt on next/image, built-in route announcements. Vue: dynamic ARIA via v-bind. Angular: the CDK a11y module (FocusTrap, LiveAnnouncer, high-contrast detection).

프레임워크는 도와줄 뿐 보장하지 않습니다. SPA 프레임워크의 기본 라우팅은 포커스·낭독 관리를 스스로 해주지 않는 경우가 많고, 인기 UI 라이브러리도 접근성 품질이 제각각입니다. '라이브러리를 채택하기 전 키보드·낭독기로 샘플 테스트한다'가 실무 원칙입니다.

Frameworks help but don't guarantee. SPA routing often doesn't manage focus and announcements by itself, and popular UI libraries vary widely in accessibility quality. The working rule: sample-test any library with keyboard and screen reader before adopting it.

접근성 성명 작성

Writing the Accessibility Statement

접근성 성명(Accessibility Statement)의 구성 요소: 목표·준수 표준과 적합성 수준(예: WCAG 2.2 AA), 알려진 제한 사항의 솔직한 공개, 접근성 문의·피드백 연락처, 최근 평가일과 평가 방법, 지속 개선 의지. EU 공공 부문(WAD)에서는 법적 필수이며, W3C가 성명 생성 도구를 제공합니다.

Elements of an accessibility statement: the target standard and conformance level (e.g., WCAG 2.2 AA), honest disclosure of known limitations, a contact for accessibility feedback, the date and method of the last evaluation, and a commitment to improvement. It's legally required in the EU public sector (WAD), and the W3C offers a statement generator.

성명은 마케팅 문서가 아니라 책임성 문서입니다. '완벽히 접근 가능합니다'라는 과장은 신뢰를 깎고 법적 리스크를 키웁니다. 알려진 문제와 수정 일정, 우회 방법을 공개하는 것이 사용자와 규제 기관 모두에게 좋은 신호입니다.

A statement is an accountability document, not marketing. Claiming 'fully accessible' erodes trust and increases legal risk. Disclosing known issues, remediation timelines, and workarounds sends the right signal to users and regulators alike.