ARIA 실전 가이드: 접근 가능한 웹 인터페이스 구현하기

<!-- ❌ 나쁜 예: 불필요한 ARIA -->
<button role="button" aria-label="클릭">클릭</button>
<!-- <button>은 이미 button이므로 role 중복 -->

<!-- ❌ 나쁜 예: 시맨틱 HTML이 존재하는데 ARIA 사용 -->
<div role="heading" aria-level="1">제목</div>
<!-- <h1>제목</h1>을 쓰면 ARIA 불필요 -->

<!-- ❌ 나쁜 예: aria-label이 필요 없는 경우 -->
<button aria-label="저장">
  <i class="icon-save"></i> 저장
</button>
<!-- 시각적 텍스트가 이미 있으면 aria-label 불필요 -->

<!-- ✅ 좋은 예: 아무 ARIA 없음 (시맨틱만으로 충분) -->
<button>저장</button>
<h1>제목</h1>
<form>
  <label for="email">이메일</label>
  <input id="email" type="email">
</form>

<!-- ✅ 필요한 경우 1: 커스텀 위젯 -->
<div class="custom-tabs">
  <div role="tablist">
    <button role="tab" aria-selected="true" aria-controls="panel-1" tabindex="0">
      탭 1
    </button>
    <button role="tab" aria-selected="false" aria-controls="panel-2" tabindex="-1">
      탭 2
    </button>
  </div>
  <div id="panel-1" role="tabpanel">내용 1</div>
  <div id="panel-2" role="tabpanel" hidden>내용 2</div>
</div>

<!-- ✅ 필요한 경우 2: 추가 정보 제공 -->
<button aria-label="차트 열기">📊</button>
<!-- 아이콘만 있는 경우 aria-label이 필수 -->

<!-- ✅ 필요한 경우 3: 상태 변화 알림 -->
<span aria-live="polite" aria-atomic="true" id="notifications"></span>
<script>
  // 사용자 액션 후 동적으로 메시지 추가
  document.getElementById('notifications').textContent = '저장되었습니다.';
</script>

<!-- 1. aria-label: 간단한 라벨 제공 -->
<button aria-label="닫기">×</button>

<!-- 2. aria-labelledby: 페이지의 다른 엘리먼트를 라벨로 참고 -->
<h2 id="dialog-title">사용자 설정</h2>
<div role="dialog" aria-labelledby="dialog-title">
  <!-- 다이얼로그 내용 -->
</div>

<!-- 3. 라벨 결합: 여러 엘리먼트를 조합 -->
<span id="search-label">상품 검색</span>
<span id="search-hint">(상품명, 카테고리)</span>
<input
  aria-labelledby="search-label search-hint"
  placeholder="검색어 입력"
>

<!-- 4. 숨겨진 라벨 -->
<!-- 스크린 리더만 읽는 라벨 클래스 -->
<style>
  .sr-only {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    border: 0;
  }
</style>

<button>
  <span class="sr-only">이전 페이지로</span>
  ←
</button>

<!-- 입력 필드에 추가 설명 -->
<label for="password">비밀번호</label>
<input
  id="password"
  type="password"
  aria-describedby="pwd-requirements pwd-strength"
>
<div id="pwd-requirements" class="hint">
  최소 8자, 대문자, 숫자, 특수문자(@, #, $) 포함
</div>
<div id="pwd-strength" aria-live="polite">
  강도: 약함
</div>

<!-- 복잡한 이미지에 설명 -->
<img
  src="chart.png"
  alt="월별 판매량"
  aria-describedby="chart-desc"
>
<p id="chart-desc">
  2024년 1월부터 12월까지의 판매량.
  최고점은 7월의 15,000개, 최저점은 2월의 5,000개
</p>

<!-- 폼 필드의 에러 메시지 -->
<label for="email">이메일</label>
<input id="email" type="email" aria-describedby="email-error">
<span id="email-error" role="alert">
  올바른 이메일 형식이 아닙니다.
</span>

<!-- 1. 체크박스/라디오 상태 -->
<label>
  <input type="checkbox">
  약관에 동의합니다
</label>

<!-- 네이티브 체크박스/라디오는 상태를 자동 노출하므로 aria-checked를 수동 설정하지 않습니다. 커스텀 위젯일 때만 aria-checked를 관리하세요. -->

<!-- 2. 토글 버튼 상태 -->
<button
  aria-pressed="false"
  aria-label="음소거"
  id="mute-btn"
>
  🔊
</button>

<script>
  const muteBtn = document.getElementById('mute-btn');
  muteBtn.addEventListener('click', function() {
    const isPressed = this.getAttribute('aria-pressed') === 'true';
    this.setAttribute('aria-pressed', !isPressed);
    // 음소거 토글 로직
  });
</script>

<!-- 3. 현재 페이지 표시 (네비게이션) -->
<nav>
  <a href="/products">상품</a>
  <a href="/blog" aria-current="page">블로그</a> <!-- 현재 페이지 -->
  <a href="/about">소개</a>
</nav>

<!-- 4. 트리 구조의 열기/닫기 상태 -->
<button aria-expanded="false" aria-controls="submenu">
  카테고리
</button>
<ul id="submenu" hidden>
  <li><a href="#">서브메뉴 1</a></li>
  <li><a href="#">서브메뉴 2</a></li>
</ul>

<script>
  document.querySelector('button').addEventListener('click', function() {
    const isExpanded = this.getAttribute('aria-expanded') === 'true';
    this.setAttribute('aria-expanded', !isExpanded);
    document.getElementById('submenu').hidden = isExpanded;
  });
</script>

<!-- 1. aria-live="polite" (기본) -->
<!-- 사용자가 현재 작업을 완료한 후 변경사항 알림 -->
<div id="notifications" aria-live="polite">
  <!-- 메시지가 여기에 추가됨 -->
</div>

<!-- 2. aria-live="assertive" -->
<!-- 즉시 변경사항 알림 (남용하면 방해됨, 긴급 상황에만) -->
<div id="error-alert" aria-live="assertive">
  <!-- 즉각적인 에러 메시지 -->
</div>

<!-- 3. aria-atomic="true" -->
<!-- 변경된 부분만이 아니라 전체 콘텐츠를 읽음 -->
<div aria-live="polite" aria-atomic="true" id="search-results">
  <p>검색 결과: 23개</p>
  <ul>
    <li>상품 1</li>
    <li>상품 2</li>
  </ul>
</div>

<!-- 4. aria-relevant="additions text" -->
<!-- 어떤 변경사항을 알릴지 지정 -->
<div aria-live="polite" aria-relevant="additions text">
  <!-- 추가된 항목과 텍스트 변경만 알림 -->
</div>

<div class="search-container">
  <input
    id="search-input"
    type="text"
    placeholder="검색..."
    aria-describedby="search-help"
  >
  <span id="search-help" class="sr-only">
    입력하면 실시간으로 검색 결과가 표시됩니다.
  </span>
</div>

<!-- 검색 결과 라이브 리전 -->
<div id="search-results" role="status">
  <!-- 결과가 여기에 표시됨 -->
</div>

<script>
  const input = document.getElementById('search-input');
  const resultsDiv = document.getElementById('search-results');

  input.addEventListener('input', function(e) {
    const query = e.target.value.trim();

    if (!query) {
      resultsDiv.innerHTML = '';
      return;
    }

    // API 호출 (예시)
    fetch(`/api/search?q=${query}`)
      .then(res => res.json())
      .then(data => {
        // 결과 업데이트 - aria-live가 변경을 감지
        resultsDiv.innerHTML = `
          <p>
            ${data.count}개 결과를 찾았습니다.
          </p>
          <ul>
            ${data.items.map(item => `<li>${item.name}</li>`).join('')}
          </ul>
        `;
      });
  });
</script>

<div class="tabs">
  <div role="tablist">
    <button
      role="tab"
      aria-selected="true"
      aria-controls="panel-1"
      tabindex="0"
      id="tab-1"
    >
      기본 정보
    </button>
    <button
      role="tab"
      aria-selected="false"
      aria-controls="panel-2"
      tabindex="-1"
      id="tab-2"
    >
      상세 정보
    </button>
  </div>

  <div id="panel-1" role="tabpanel" aria-labelledby="tab-1">
    기본 정보 내용
  </div>
  <div id="panel-2" role="tabpanel" aria-labelledby="tab-2" hidden>
    상세 정보 내용
  </div>
</div>

<style>
  [role="tab"][aria-selected="false"] {
    opacity: 0.6;
  }
</style>

<script>
  const tabs = document.querySelectorAll('[role="tab"]');
  const panels = document.querySelectorAll('[role="tabpanel"]');

  tabs.forEach(tab => {
    tab.addEventListener('click', function() {
      // 모든 탭 비활성화
      tabs.forEach(t => {
        t.setAttribute('aria-selected', 'false');
        t.setAttribute('tabindex', '-1');
      });
      panels.forEach(p => p.hidden = true);

      // 클릭된 탭 활성화
      this.setAttribute('aria-selected', 'true');
      this.setAttribute('tabindex', '0');
      const panelId = this.getAttribute('aria-controls');
      document.getElementById(panelId).hidden = false;
    });

    // 키보드 네비게이션
    tab.addEventListener('keydown', function(e) {
      let nextTab;
      if (e.key === 'ArrowRight' || e.key === 'ArrowDown') {
        nextTab = this.nextElementSibling || tabs[0];
      } else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') {
        nextTab = this.previousElementSibling || tabs[tabs.length - 1];
      } else if (e.key === 'Home') {
        nextTab = tabs[0];
      } else if (e.key === 'End') {
        nextTab = tabs[tabs.length - 1];
      }

      if (nextTab) {
        e.preventDefault();
        nextTab.click();
        nextTab.setAttribute('tabindex', '0');
        this.setAttribute('tabindex', '-1');
        nextTab.focus();
      }
    });
  });
</script>

<div class="accordion">
  <div class="accordion-item">
    <button
      aria-expanded="false"
      aria-controls="section-1"
      id="accordion-1"
      class="accordion-btn"
    >
      자주 묻는 질문 1
    </button>
    <div
      id="section-1"
      role="region"
      aria-labelledby="accordion-1"
      hidden
      class="accordion-content"
    >
      <p>답변 내용 1</p>
    </div>
  </div>

  <div class="accordion-item">
    <button
      aria-expanded="false"
      aria-controls="section-2"
      id="accordion-2"
      class="accordion-btn"
    >
      자주 묻는 질문 2
    </button>
    <div
      id="section-2"
      role="region"
      aria-labelledby="accordion-2"
      hidden
      class="accordion-content"
    >
      <p>답변 내용 2</p>
    </div>
  </div>
</div>

<style>
  .accordion-content {
    max-height: 0;
    overflow: hidden;
    transition: max-height 0.3s ease;
  }

  .accordion-content:not([hidden]) {
    max-height: 500px;
  }

  button[aria-expanded="true"]::after {
    content: '▼';
  }

  button[aria-expanded="false"]::after {
    content: '▶';
  }
</style>

<script>
  document.querySelectorAll('.accordion-btn').forEach(btn => {
    btn.addEventListener('click', function() {
      const isExpanded = this.getAttribute('aria-expanded') === 'true';
      this.setAttribute('aria-expanded', !isExpanded);
      document.getElementById(this.getAttribute('aria-controls')).hidden = isExpanded;
    });
  });
</script>

<div class="dropdown">
  <button
    id="menu-btn"
    aria-expanded="false"
    aria-controls="menu-list"
  >
    메뉴
  </button>

  <ul id="menu-list" hidden aria-labelledby="menu-btn">
    <li><a href="#">옵션 1</a></li>
    <li><a href="#">옵션 2</a></li>
    <li><a href="#">옵션 3</a></li>
  </ul>
</div>

<script>
  const btn = document.getElementById('menu-btn');
  const menu = document.getElementById('menu-list');
  const items = menu.querySelectorAll('a');

  btn.addEventListener('click', () => {
    const isExpanded = btn.getAttribute('aria-expanded') === 'true';
    btn.setAttribute('aria-expanded', !isExpanded);
    menu.hidden = isExpanded;

    if (!isExpanded) {
      items[0].focus();
    }
  });

  // Escape 키로 메뉴 닫기
  menu.addEventListener('keydown', (e) => {
    if (e.key === 'Escape') {
      btn.click();
      btn.focus();
    }
  });

  // 외부 클릭으로 메뉴 닫기
  document.addEventListener('click', (e) => {
    if (!e.target.closest('.dropdown')) {
      menu.hidden = true;
      btn.setAttribute('aria-expanded', 'false');
    }
  });
</script>

<button id="open-modal">모달 열기</button>

<div
  id="modal"
  role="dialog"
  aria-labelledby="modal-title"
  aria-modal="true"
  hidden
>
  <div class="modal-content">
    <h2 id="modal-title">중요한 정보</h2>

    <p>여기는 모달의 내용입니다.</p>

    <button id="close-modal">닫기</button>
  </div>
</div>

<style>
  #modal:not([hidden]) {
    display: flex;
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background: rgba(0, 0, 0, 0.5);
  }

  .modal-content {
    margin: auto;
    background: white;
    padding: 2rem;
    border-radius: 8px;
  }
</style>

<script>
  const modal = document.getElementById('modal');
  const openBtn = document.getElementById('open-modal');
  const closeBtn = document.getElementById('close-modal');
  let previousFocus = null;

  openBtn.addEventListener('click', () => {
    previousFocus = document.activeElement;
    modal.hidden = false;
    // 모달 밖 요소만 inert 처리해 포커스가 밖으로 나가지 않게 함
    const siblings = Array.from(document.body.children).filter(el => el !== modal);
    siblings.forEach(el => (el.inert = true));

    // 포커스를 모달로 이동
    const focusableElements = modal.querySelectorAll(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );
    focusableElements[0]?.focus();

    // 모달 내에서만 포커스 이동 가능 (포커스 트래핑)
    focusableElements[focusableElements.length - 1].addEventListener('keydown', (e) => {
      if (e.key === 'Tab' && !e.shiftKey) {
        e.preventDefault();
        focusableElements[0].focus();
      }
    });

    focusableElements[0].addEventListener('keydown', (e) => {
      if (e.key === 'Tab' && e.shiftKey) {
        e.preventDefault();
        focusableElements[focusableElements.length - 1].focus();
      }
    });
  });

  closeBtn.addEventListener('click', () => {
    modal.hidden = true;
    const siblings = Array.from(document.body.children).filter(el => el !== modal);
    siblings.forEach(el => (el.inert = false));
    previousFocus?.focus();
  });

  // Escape 키로 닫기
  document.addEventListener('keydown', (e) => {
    if (e.key === 'Escape' && !modal.hidden) {
      closeBtn.click();
    }
  });
</script>

<!-- ❌ 실수 1: 역할 오용 -->
<div role="button" onclick="alert('클릭')">클릭하세요</div>
<!-- 문제: 키보드 포커스 없음, 키보드 네비게이션 불가 -->

<!-- ✅ 올바른 방법 -->
<button onclick="alert('클릭')">클릭하세요</button>

<!-- ❌ 실수 2: 시각적 라벨 없이 aria-label만 사용 -->
<input aria-label="검색" placeholder="검색어 입력">
<!-- 문제: 화면에는 라벨이 없고, 보조기술에만 라벨이 전달됨 -->

<!-- ✅ 올바른 방법 -->
<label for="search">검색</label>
<input id="search" placeholder="검색어 입력">

<!-- ❌ 실수 3: 부정확한 라이브 리전 -->
<div aria-live="assertive" id="log">
  로그 메시지들...
</div>
<!-- 문제: 모든 메시지를 읽음, 성능 저하 -->

<!-- ✅ 올바른 방법 -->
<div aria-live="polite" aria-atomic="false" id="notification">
  <!-- 최신 메시지만 추가 -->
</div>

<!-- ❌ 실수 4: 역순 접근 가능 엘리먼트들 -->
<div role="tablist">
  <div role="tab" tabindex="0">첫 번째</div>
  <div role="tab">두 번째</div> <!-- tabindex 없음 -->
  <div role="tab" tabindex="0">세 번째</div>
</div>
<!-- 문제: 일관성 없는 포커스 순서 -->

<!-- ✅ 올바른 방법: 첫 탭만 tabindex="0", 나머지는 -1 -->
<div role="tablist">
  <div role="tab" tabindex="0">첫 번째</div>
  <div role="tab" tabindex="-1">두 번째</div>
  <div role="tab" tabindex="-1">세 번째</div>
</div>

<!-- 1. 네이티브 엘리먼트에는 역할을 중복하지 않기 -->
<button>좋음</button>
<div role="button">필요할 때만 사용</div>

<!-- 2. 역할 변경보다 엘리먼트 교체가 나음 -->
<!-- ❌ 안 좋음 -->
<div id="button" role="button">클릭</div>
<script>
  document.getElementById('button').setAttribute('role', 'link');
</script>

<!-- ✅ 좋음 -->
<button>클릭</button>

<!-- 3. 복합 역할은 명시적으로 -->
<div role="tablist">
  <div role="tab">탭 1</div>
  <div role="tabpanel">콘텐츠 1</div>
</div>

/* ARIA 상태로 스타일링 - 접근성 정보와 시각 표현 동기화 */
button[aria-pressed="true"] {
  background-color: #4A90E2;
  color: white;
}

button[aria-pressed="false"] {
  background-color: #f0f0f0;
  color: #333;
}

/* 포커스 표시 */
[role="button"]:focus {
  outline: 3px solid #4A90E2;
  outline-offset: 2px;
}

/* 라이브 리전 변경 시각화 (선택사항) */
[aria-live="polite"] {
  border-left: 3px solid #27AE60;
  padding-left: 0.5rem;
}

/* 숨겨진 탭 스타일 */
[role="tabpanel"][hidden] {
  display: none;
}

// ❌ 나쁜 예: 모든 변경사항을 aria-live에 추가
const notifications = document.getElementById('notifications');
for (let i = 0; i < 1000; i++) {
  notifications.innerHTML += `<p>알림 ${i}</p>`;
}

// ✅ 좋은 예: 배치 업데이트
const notifications = document.getElementById('notifications');
const fragment = document.createDocumentFragment();
for (let i = 0; i < 1000; i++) {
  const p = document.createElement('p');
  p.textContent = `알림 ${i}`;
  fragment.appendChild(p);
}
notifications.appendChild(fragment);

// ✅ 좋은 예: 최신 메시지만 유지
const notification = document.getElementById('notification');
function showNotification(message) {
  notification.innerHTML = message;
  // 5초 후 제거
  setTimeout(() => {
    notification.innerHTML = '';
  }, 5000);
}

// React 예제
function Tabs() {
  const [selected, setSelected] = useState(0);

  return (
    <div role="tablist">
      {tabs.map((tab, i) => (
        <button
          key={i}
          role="tab"
          aria-selected={i === selected}
          aria-controls={`panel-${i}`}
          onClick={() => setSelected(i)}
        >
          {tab.label}
        </button>
      ))}
      {tabs.map((tab, i) => (
        <div
          key={i}
          id={`panel-${i}`}
          role="tabpanel"
          aria-labelledby={`tab-${i}`}
          hidden={i !== selected}
        >
          {tab.content}
        </div>
      ))}
    </div>
  );
}