한국 프론트엔드를 위한
A11y 코드 리뷰 도감
표면적으로는 a11y 시리즈입니다. 본질은 SEO·GEO·AEO 최적화 시리즈입니다. 구글 공식 가이드(2026-05-15)가 흘린 단서로부터 — accessibility tree가 AI 에이전트의 입력값이라는 사실에서 — 시작된 16편 도감 카드.
시리즈 카드
미래 발행 카드는 회색으로 표시됩니다.
- #0012026년 6월 6일
div는 클릭되지만 버튼은 아닙니다 — button vs a 코드 리뷰
div onClick은 클릭되지만 button이 아닙니다. 스크린리더, 키보드 사용자, AI 에이전트 모두 그 차이를 압니다. 구글 공식 가이드(2026-05-15)가 흘린 단서로부터 button과 a의 의미론을 다시 봅니다.
시맨틱 HTML - #0022026년 6월 13일
placeholder는 label이 아닙니다 — label·fieldset·legend 코드 리뷰
placeholder만 있는 폼은 스크린리더에게 '편집 가능'으로만 들리고, AI 에이전트의 자동 입력에서 가장 자주 실패합니다. label·fieldset·legend의 의미론을 코드와 함께 다시 봅니다.
시맨틱 HTML - #0032026년 6월 20일
모달을 띄우면 키보드 사용자는 갇히거나 도망갑니다 — dialog 코드 리뷰
직접 만든 모달은 포커스 트랩이 깨지거나 ESC가 안 닫히는 게 기본값입니다. native <dialog>, Radix, Headless UI의 차이를 코드로 비교하고 AI 에이전트가 모달을 어떻게 보는지 정리합니다.
시맨틱 HTML - #0042026년 6월 27일
FAQ 아코디언에 JavaScript는 필요 없습니다 — details/summary 코드 리뷰
FAQ 아코디언을 만들 때 JavaScript와 상태 관리부터 떠올렸다면 — native <details>/<summary> 두 태그가 그 모든 일을 하고 a11y까지 무료로 줍니다. SEO·AI 인용에 미치는 영향도 다릅니다.
시맨틱 HTML - #0052026년 7월 4일
h1은 한 개만이라는 미신과 스크린리더 사용자의 실제 길찾기 — heading 코드 리뷰
SEO 도구는 'h1은 한 개여야 한다'고 외치지만 스크린리더 사용자는 헤딩 목록으로 페이지를 탐색합니다. 헤딩의 본질은 SEO가 아닌 목차이며, 그래서 AI Overviews 인용 신호이기도 합니다.
시맨틱 HTML - #0062026년 7월 11일
Next.js layout.tsx에 main이 두 개 — landmark 코드 리뷰
main·nav·header·footer 같은 landmark 태그는 페이지의 지도입니다. 지도가 두 장이거나 없으면 스크린리더 사용자도 AI 에이전트도 길을 잃습니다. 가장 자주 잘못된 케이스부터 정리합니다.
시맨틱 HTML - #0072026년 7월 18일
관리자 table은 OK, 가격표는 div grid — table 코드 리뷰
데이터는 table이고 레이아웃은 grid입니다. 이 한 줄을 거꾸로 적용한 페이지는 AI가 가격을 못 읽고, 스크린리더가 행과 열을 못 잡습니다. 두 케이스의 경계를 코드로 그어봅니다.
시맨틱 HTML예정 - #0082026년 7월 25일
OG 이미지에 alt를 자동 생성한다는 발상 — alt와 이미지 텍스트 코드 리뷰
alt 속성은 시각장애 사용자만을 위한 게 아닙니다. AI Overviews가 이미지를 답변에 포함하고, 검색엔진이 이미지를 인덱싱하는 가장 강한 신호입니다. 빈 alt와 누락된 alt의 차이부터 봅니다.
시맨틱 HTML예정 - #0092026년 8월 1일
Toast로 띄운 에러는 누구에게 안 들립니다 — form 에러 메시지 코드 리뷰
폼 에러를 toast나 alert로만 띄우면 스크린리더 사용자는 못 듣고, AI 에이전트는 폼 자동 입력에서 실패합니다. aria-describedby와 aria-live의 차이부터 코드로 짚습니다.
시맨틱 HTML예정 - #0102026년 8월 8일
Radix Dialog도 깨지는 그 케이스 — focus trap 코드 리뷰
포커스 트랩은 native <dialog>가 무료로 해주는 일이지만, 라이브러리·SPA 라우팅·autoFocus가 섞이면 미세하게 깨집니다. 깨지는 다섯 시나리오를 코드로 짚어봅니다.
시맨틱 HTML예정 - #0112026년 8월 15일
type=text는 거의 항상 잘못된 선택입니다 — input 타입별 코드 리뷰
type 속성 한 글자가 모바일 키보드를 바꾸고, AI 자동완성 정확도를 결정하고, 한국 전화번호 입력의 함정을 만듭니다. input 타입 13개의 실무 결정 트리를 정리합니다.
시맨틱 HTML예정 - #0122026년 8월 22일
커스텀 dropdown은 거의 항상 잘못된 선택입니다 — select와 combobox 코드 리뷰
native <select>는 모바일에서 압도적으로 좋은 UX를 줍니다. 커스텀 dropdown으로 갈아탈 정당한 이유는 검색 가능, 멀티 선택, 가상화 셋 정도뿐입니다. ARIA combobox의 진짜 비용을 봅니다.
시맨틱 HTML예정 - #0132026년 8월 29일
탭처럼 보이는 div는 탭이 아닙니다 — ARIA tab 패턴 코드 리뷰
탭 UI를 div와 onClick으로 만들면 키보드 사용자는 탭 사이를 못 옮기고, AI 에이전트는 어느 탭이 활성인지 모릅니다. role=tablist의 진짜 키보드 규칙부터 코드로 짚습니다.
시맨틱 HTML예정 - #0142026년 9월 5일
tooltip은 전세계 a11y 함정 1위입니다 — tooltip 코드 리뷰
hover로만 뜨는 tooltip은 모바일에서 안 뜨고, 키보드에서 안 뜨고, 정보를 tooltip 안에만 두면 누구도 못 봅니다. 진짜 tooltip이 정당한 케이스는 좁고, 그 경우의 표준 패턴도 까다롭습니다.
시맨틱 HTML예정 - #0152026년 9월 12일
비동기 알림은 alert가 아닙니다 — live region 코드 리뷰
비동기로 등장하는 알림·에러·상태 변경은 시각 사용자에게는 보이지만 스크린리더와 AI 에이전트에게는 사라집니다. aria-live의 polite와 assertive의 진짜 차이부터 코드로 짚습니다.
시맨틱 HTML예정 - #0162026년 9월 19일
outline: none 한 줄이 모든 키보드 사용자를 쫓아냅니다 — skip link와 키보드 네비 코드 리뷰
skip link, focus 스타일, 키보드 순서 — 이 세 가지는 모든 다른 a11y 패턴의 전제조건입니다. 16편 도감의 마지막 카드이자 첫 번째로 점검해야 할 기본기를 정리합니다.
시맨틱 HTML예정
시리즈 명제
사람을 위한 코드 = AI를 위한 코드
시맨틱 HTML과 accessibility tree는 스크린리더 사용자만이 아니라 AI 에이전트의 입력값입니다. 구글 가이드(2026-05-15)가 명시적으로 인정했습니다.
태그 한 장 = 도감 카드 한 장
각 글은 한 태그(또는 한 패턴)의 도감 카드. 7단 deep dive + 도감 메타데이터로 16편이 모이면 한 권의 백과가 됩니다.
외국 사례 적극 활용
Adrian Roselli, Sarah Higley, Ben Myers, Matuzović, WebAIM 등 글로벌 a11y 전문가들의 인용 + 한국 맥락 + KWCAG 매핑.
실명 안티패턴 금지
한국 실명 기업의 안티패턴은 공식 출처 3건 이상일 때만. 그 외는 '국내 핀테크', '국내 이커머스' 같이 익명화.