접근성

@mildang/design-system의 컴포넌트는 ark-ui·radix 위에 만들어져, 표준 역할(role)과 aria 속성, 키보드 조작, 포커스 관리가 컴포넌트에 기본으로 들어 있습니다. 이 문서는 무엇이 컴포넌트에서 보장되고, 무엇을 사용처에서 직접 처리해야 하는지 경계를 정리합니다.

1. 컴포넌트가 보장하는 것

아래 항목은 컴포넌트를 그대로 쓰면 별도 설정 없이 적용됩니다.

• 역할·상태: 각 컴포넌트에 맞는 role과 aria 속성(aria-expanded·aria-selected 등)이 상태에 따라 자동으로 붙습니다.
• 키보드 조작: 방향키·Enter·Esc·Tab 같은 표준 키 조작을 지원합니다. 컴포넌트별 구체적인 키 동작은 각 컴포넌트 문서에서 확인할 수 있습니다.
• 포커스 관리: 팝오버·다이얼로그 등은 열릴 때 포커스를 안으로 가두고 닫힐 때 원래 위치로 되돌립니다. 포커스 링도 키보드 사용 시 나타납니다.
• 모션 감축: 애니메이션이 있는 컴포넌트는 시스템의 모션 감축(reduced motion) 설정을 반영해 전환 효과를 줄이거나 없앱니다.
• 폼 연결: Field로 감싼 입력은 라벨과 컨트롤, 도움말(에러 텍스트)을 htmlFor· aria-describedby로 자동 연결합니다.

2. 직접 처리해야 하는 것

컴포넌트가 대신 처리하지 못하는 부분입니다. 아래 항목은 직접 확인해야 합니다.

1. 접근 가능한 이름

   버튼·입력 요소에는 보조 기술이 읽을 이름이 필요합니다. 특히 아이콘만 있는 버튼은 눈에 보이는 글자가 없어 접근 가능한 이름이 없으므로 aria-label을 넣어야 합니다.

   tsx

   // 지양: 아이콘만 있어 읽을 이름이 없음
   <IconButton>
     <CloseIcon />
   </IconButton>
   
   // 권장: aria-label 로 이름 제공
   <IconButton aria-label="닫기">
     <CloseIcon />
   </IconButton>

   입력 요소는 눈에 보이는 라벨을 label로 연결하는 것이 우선이고, 라벨을 표시하지 않는 경우에만 aria-label을 사용합니다.

2. 이미지 대체 텍스트

   내용을 전달하는 이미지에는 alt 속성을 넣습니다. 장식용 이미지는 alt=""으로 비워 보조 기술이 건너뛰도록 합니다.

3. 색상 대비

   토큰 기본값은 대비를 고려해 정해져 있어, 그대로 사용하면 배경과 글자의 대비가 충분합니다.

   정보를 색상만으로 구분하지 않습니다. 예를 들어 오류를 빨간색만으로 표시하면 색을 구별하기 어려운 사용자는 알아채지 못하므로, 색과 함께 텍스트나 아이콘('오류입니다' 등)으로도 알립니다.

4. 포커스 순서와 시맨틱 태그

   • 키보드 포커스는 DOM 순서를 따릅니다. 시각적 배치를 바꾸더라도 읽는 순서와 어긋나지 않도록 합니다.
   • 제목·목록처럼 의미가 있는 자리에는 as prop으로 알맞은 태그를 지정합니다. 사용법은 컴포넌트 스타일링의 태그 변경(as)을 참고하세요.

권장 사항