Accessibility & Content

이 문서는 각 component 문서에 흩어져 있는 접근성 기준과 문구 규칙을 한곳에 모아 설명해요. 개별 prop 설명보다, 여러 component에서 반복되는 공통 약속을 먼저 이해하고 싶을 때 읽으면 좋아요.

Overview

PAI Design에서 공통으로 먼저 맞춰야 하는 기준은 아래 4가지예요.

접근 가능한 이름 먼저 만들기

Icon only Button

아이콘만 있는 Button에는 반드시 aria-label 또는 aria-labelledby를 함께 써요. 보이는 텍스트가 없으면 스크린 리더가 버튼 목적을 읽을 수 없기 때문이에요.

import { Button } from "@pai-design/react";

export function CloseButton() {
  return <Button aria-label="닫기" leadingIcon={<span aria-hidden>×</span>} variant="ghost" />;
}

Dialog와 AlertDialog

Dialog와 AlertDialog는 가능한 한 Title과 필요할 때 Description을 함께 제공해요. 제목이 없으면 aria-label로 접근 가능한 이름을 보강해야 해요.

제목은 이 표면이 왜 열렸는지 먼저 알려주고, 설명은 사용자가 확인해야 할 맥락이나 결과를 덧붙여요.

HelpBubble

HelpBubble도 열린 동안에는 목적이 읽혀야 해요. 아주 짧더라도 제목이나 aria-label로 이 버블이 왜 떠 있는지 바로 알 수 있게 해요.

키보드와 focus 흐름 지키기

Dialog와 AlertDialog

• 열리면 focus가 안쪽으로 이동해야 해요.
• Escape로 닫을 수 있어야 해요.
• 닫힌 뒤에는 focus가 trigger나 이전 작업 위치로 자연스럽게 돌아가야 해요.
• 사용자가 별도 표면 안에서 읽거나 조작해야 하는 흐름에 사용해요.

HelpBubble

• Trigger 근처에서 짧게 열리고 닫히는 흐름에 사용해요.
• Escape나 바깥 클릭으로 닫을 수 있어야 해요.
• 여러 단계 조작이나 필수 선택을 시키는 용도로는 사용하지 않아요.

현재 흐름을 잠시 보조하는 정도를 넘기기 시작하면 HelpBubble보다 Dialog나 AlertDialog가 더 자연스러워요.

어떤 overlay를 고를지 먼저 정하기

• 읽거나 조작한 뒤 닫으면 되는 별도 표면: Dialog
• 결과가 크고 취소와 확인 중 하나를 분명하게 골라야 하는 경우: AlertDialog
• 현재 흐름을 유지한 채 짧은 도움말만 보여주는 경우: HelpBubble

패턴이 헷갈리면 문구보다 먼저 overlay 종류를 다시 골라요. 잘못된 overlay 위에 좋은 문구를 얹어도 전체 경험은 어색할 수 있어요.

비교가 필요하면 Overlay Patterns 문서를 같이 보세요.

문구는 행동과 결과를 먼저 말해요

Button

버튼 라벨은 가능한 한 사용자가 누른 뒤 어떤 일이 일어나는지 바로 읽히게 써요.

• 저장, 저장하기, 삭제하기, 다음으로
• 되돌리기 어려운 액션에서는 확인보다 삭제하기, 초기화하기처럼 결과를 직접 말해요.

Dialog

제목은 사용자가 여기서 해야 할 일을 먼저 알려줘요. 설명은 필요한 배경만 짧게 덧붙여요.

• 제목: 프로젝트 이름 바꾸기
• 설명: 이 이름은 팀원 모두에게 보여져요.

AlertDialog

결과가 큰 결정은 제목과 버튼 모두에서 위험도를 분명하게 말해요.

• 제목: 정말 삭제할까요?
• 설명: 삭제하면 되돌릴 수 없어요.
• 버튼: 삭제하기, 닫기

HelpBubble

제목은 현재 보강하는 개념을 먼저 알려주고, 설명은 한두 문장 안에서 끝내요.

• 제목: 자동 저장
• 설명: 입력한 내용은 일정 간격으로 자동 저장돼요.

tooltip처럼 한 단어 이름만 보여주면 충분한 상황이라면 HelpBubble까지 쓰지 않는 편이 나아요.

Writing과 연결되는 기준

문구는 아래 원칙을 반복해서 확인해요.

• 기능 이름보다 사용 목적을 먼저 말해요.
• 같은 뜻이라면 부정문보다 긍정문과 능동문을 우선해요.
• 위험한 상황은 부드럽지만 분명하게 말해요.
• API 이름은 정확히 유지하고, 설명 문장은 익숙한 한국어로 풀어요.

더 자세한 문체 규칙은 Writing에서 확인해요.

체크리스트

• 이 component의 목적을 스크린 리더가 읽을 수 있나요?
• 사용자가 Escape와 focus 흐름을 예측할 수 있나요?
• 지금 필요한 overlay가 맞나요?
• 버튼과 제목이 행동과 결과를 바로 말하나요?

이 4가지만 먼저 맞춰도 대부분의 component 문서와 제품 UI가 훨씬 일관되게 정리돼요.

다음에 읽으면 좋은 문서

• overlay 선택 기준은 Overlay Patterns에서 비교해요.
• 문체와 표현 원칙은 Writing에서 확인해요.
• Button, Dialog, AlertDialog, HelpBubble의 개별 contract는 Components에서 이어서 볼 수 있어요.