Writing
PAI Design 문서와 컴포넌트 문구를 같은 톤으로 쓰는 기준을 소개해요.
PAI Design 문서는 친근하고 정확한 톤으로 설명해요. 사용자가 지금 무엇을 이해해야 하는지 자연스럽게 따라올 수 있도록 익숙한 단어를 사용하고, 헷갈리기 쉬운 개념은 비교와 예시로 차이와 맥락을 보여줘요.
아래 기준은 이런 문장을 쓰기 위한 가이드예요. 다만 가이드보다 좋은 문장이 먼저예요. 사용자가 더 쉽게 이해하는 표현이 있다면 그 표현을 먼저 선택해요.
문체 원칙
명확하게 말해요
먼저 필요한 말을 해요. 다만 이유나 비교가 있어야 더 잘 이해되는 내용이라면 배경 설명도 함께 써요. 문장을 억지로 잘게 끊기보다, 읽는 사람이 한 번에 이해할 수 있는 흐름으로 정리해요.
| Do | Don't |
|---|---|
가장 중요한 액션에는 primary를 사용해요. | primary는 높은 수준의 액션 계층을 표현하기 위한 variant입니다. |
| Dialog가 열리면 포커스가 안으로 이동해야 해요. | Dialog 오픈 시 focus management가 수행되어야 합니다. |
익숙한 단어를 사용해요
기술 용어가 꼭 필요하지 않다면 쉬운 말로 바꿔요. 다만 컴포넌트명, prop 이름, literal value처럼 API를 가리키는 말은 그대로 써요.
| Do | Don't |
|---|---|
| 버튼을 누를 수 없어요. | 버튼 interaction이 unavailable 상태가 됩니다. |
| 스크린 리더가 버튼 이름을 읽을 수 있어야 해요. | assistive technology가 semantic label을 announce해야 합니다. |
사려 깊게 말해요
사용자를 탓하는 말보다, 다음 행동을 도와주는 말을 먼저 써요. 위험하거나 되돌리기 어려운 상황은 부드럽지만 분명하게 말해요.
| Do | Don't |
|---|---|
| 삭제하면 되돌릴 수 없어요. 한 번 더 확인해보세요. | 실수로 삭제하지 않게 주의하세요. |
| 아이콘만 있는 버튼에는 이름을 함께 적어주세요. 스크린 리더가 버튼 목적을 읽을 수 있어요. | aria-label을 빼먹지 마세요. |
작성 규칙
이해를 돕는 흐름으로 써요
설명을 억지로 덜어내기보다, 읽고 바로 이해하는 것이 더 중요해요. 문서 첫머리에서는 무엇을 설명하는지, 언제 쓰는지, 비슷한 개념과 무엇이 다른지를 먼저 알려줘요.
| Do | Don't |
|---|---|
| AlertDialog는 되돌리기 어려운 확인에 사용해요. 단순 안내에는 Dialog를 사용해요. | AlertDialog는 중요한 상황에 사용하고, Dialog는 일반적인 상황에 사용해요. |
| 이 문서를 읽고 나면 Dialog와 AlertDialog를 언제 나눠 쓰는지 이해할 수 있어요. | 이 문서에서는 Dialog와 AlertDialog를 소개해요. |
친근하게 설명해요
딱딱한 종결형보다 자연스럽게 읽히는 표현을 먼저 써요. 필요한 요구사항은 분명하게 말하고, 이해를 돕는 이유나 예시는 함께 덧붙여요.
| Do | Don't |
|---|---|
| Button은 사용자가 바로 실행할 수 있는 동작에 사용해요. | Button은 사용자가 바로 실행할 수 있는 동작에 사용합니다. |
| 지금 저장하고 있어요. | 저장 처리가 진행 중입니다. |
기능 이름보다 목적을 말해요
기능의 이름만 반복하지 말고, 사용자가 그 기능으로 무엇을 할 수 있는지 설명해요.
| Do | Don't |
|---|---|
| 화면에서 가장 중요한 액션을 더 눈에 잘 띄게 보여줘요. | primary variant를 적용해요. |
| 사용자가 원할 때 Dialog를 닫을 수 있어요. | close action을 실행할 수 있어요. |
긍정문과 능동문을 우선해요
같은 뜻이라면 부정문보다 긍정문을 쓰고, 누가 무엇을 하는지 보이는 능동문을 우선해요.
| Do | Don't |
|---|---|
| 닉네임은 한 달에 1번만 바꿀 수 있어요. | 닉네임은 한 달에 2번 이상 바꿀 수 없어요. |
| 사용자는 Escape로 Dialog를 닫을 수 있어요. | Dialog는 Escape로 닫힐 수 있어요. |
숫자는 아라비아 숫자로 써요
수량, 횟수, 크기처럼 바로 비교해야 하는 값은 아라비아 숫자로 써요.
| Do | Don't |
|---|---|
| 한 화면에 중요한 액션은 1개만 두는 것이 좋아요. | 한 화면에 중요한 액션은 한 개만 두는 것이 좋아요. |
축약어와 유행어를 피해요
줄임말은 빠르게 보일 수 있지만, 뜻을 다르게 이해할 수 있어요.
| Do | Don't |
|---|---|
| 아이콘만 있는 버튼 | 아이콘 온리 버튼 |
| 접근 가능한 이름 | a11y label |
마침표를 일관되게 사용해요
평서문과 명령문 끝에는 마침표를 사용해요. 다만 버튼, 메뉴, 라벨, 표 제목처럼 짧은 UI 문구에는 마침표를 쓰지 않아요.
| Do | Don't |
|---|---|
| 스크린 리더가 버튼의 목적을 읽을 수 있어야 해요. | 스크린 리더가 버튼의 목적을 읽을 수 있어야 해요 |
| 기본 구성 | 기본 구성. |
원어 유지 기준
개발자가 그대로 복사하거나 검색해야 하는 값은 번역하지 않아요.
- 컴포넌트명:
Button,Dialog,AlertDialog - prop 이름:
variant,size,leadingIcon - literal value:
primary,secondary,ghost - ARIA 속성:
aria-label,aria-labelledby,aria-modal
이 값들은 문장 안에서도 정확한 철자를 유지해요.