접근성

원칙

• 모든 화면에서 WCAG 2.2 AA를 지키세요. 컴포넌트는 자기 동작을 맡고, 이름과 구조와 메시지는 제품이 맡습니다.
• 네이티브 의미를 유지하세요. 링크는 이동하고 버튼은 실행하고 제목은 구조를 만들어야 보조 기술이 바르게 읽습니다.
• 입력값을 잃지 않게 하세요. 오류가 나도 값을 모두 유지하고, 무엇이 잘못됐고 어떻게 고치는지 알리세요.
• 결과는 한 번만 알리세요. 변경 하나에 상태 메시지 하나를 두고, 결과는 페이지에 남기세요.
• 작업 전체를 테스트하세요. 키보드만으로, 320px 너비와 400% 확대에서, 스크린 리더로 끝까지 해 보세요.

공유 책임과 제품 책임

공유 컴포넌트는 인터랙션, 포커스, 스타일을 맡습니다. 나머지는 제품이 맡습니다.

키보드와 포커스

Tab 순서는 DOM 순서를 따르므로 DOM을 읽는 순서대로 쓰세요. 양수 tabIndex나 클릭 가능한 div를 더하지 마세요. 대신 버튼이나 링크를 쓰세요.

터치와 좁은 화면에서 컨트롤 높이는 --surf-control-target-size(44px)입니다. 표 행의 체크박스나 트리의 펼침 버튼처럼 더 작게 보이는 컨트롤은 보이는 크기를 두고, 누르는 영역만 그 크기까지 넓힙니다. 촘촘한 모니터링 화면을 위한 compact 밀도에서는 크기를 그대로 두되, WCAG 2.2 AA의 24px 아래로는 줄이지 않습니다. 포커스 링은 없애거나 가리지 마세요.

대화상자는 포커스를 안에 가두고, Escape로 닫히고, 닫히면 트리거로 포커스를 돌려줍니다. 포커스 트랩을 직접 만들지 마세요. 작업이 트리거를 없애면 다음 의미 있는 요소로 포커스를 옮기세요.

오류와 복구

예시를 비워 두거나 공백을 넣어 제출한 뒤 이름 충돌을 시험해 보세요. 검증은 로컬에서만 하고 아무것도 보내지 않습니다.

필수 필드는 라벨과 required로 표시하세요. 원인과 해결 방법은 색만이 아니라 글로 알리세요. 포커스는 충돌 예시처럼 사용자가 동작한 뒤에만 필드로 옮기세요.

<Field.Root name='name'>
  <Field.Label>Environment name (required)</Field.Label>
  <Field.Control required />
  <Field.Description>Use a unique environment name.</Field.Description>
  <Field.Error />
</Field.Root>

// Keep this live region mounted before updating its text.
<p role='status' aria-atomic='true'>
  {result}
</p>

상태 알림

• 설정 저장이나 새 결과처럼 포커스가 움직이지 않는 변경은 role=status 영역에서 알리세요. 영역은 내용이 바뀌기 전에 마운트하세요.
• role=alert는 지금 조치가 필요한 오류에만 쓰세요.
• 한 번만 알리세요. 같은 메시지를 필드, 토스트, 상태 영역에 반복하지 마세요.
• 결과와 복구 경로는 페이지에 남기세요. 토스트에만 기대지 마세요.
• 체크박스 열의 이름처럼 화면에 자리가 없는 상태나 이름은 VisuallyHidden에 넣으세요. 읽는 순서에서 자리를 지키고 공간은 차지하지 않습니다. display: none으로 숨기면 모두에게서 사라지니 쓰지 마세요.

테스트

1. 키보드만으로 작업을 끝내 보세요. 시작, 편집, 취소, 오류 복구까지 해 봅니다.
2. 320px 너비, 200%와 400% 확대, 넓힌 텍스트 간격에서 확인하세요.
3. 라이트, 다크, 강제 색상, 모션 줄이기를 오가며 확인하세요.
4. VoiceOver나 NVDA로 이름, 순서, 상태를 확인하세요. axe 같은 자동 검사가 이를 대신하지 않습니다.

테스트한 항목만 완료로 표시하세요. 이 점검은 접근성 인증이 아닙니다.

WAI — 폼 알림 / WCAG — 포커스 순서 / W3C — 키보드 제어

관련 문서

• 인터랙션 상태 — 컨트롤이 호버, 누름, 포커스, 선택, 대기 상태를 보여 주는 방식을 정합니다.
• 색 — 색 역할, 대비 기준, 팔레트 만드는 법을 정합니다.
• 콘텐츠와 현지화 — 인터페이스 문구, 숫자와 날짜 형식을 정합니다.
• Dialog — 전체 주의가 필요한 독립 작업을 엽니다.