컴포넌트 작성 지침

컴포넌트 문서는 디자이너와 개발자가 같은 동작을 구현하고 검수하기 위한 명세입니다. 화면 모양만 설명하지 않고 사용 목적, 입력과 출력, 상태, 접근성, 제한 조건을 함께 기록해야 합니다.

구조와 이름

컴포넌트 이름은 역할을 드러내고 프레임워크에 종속된 표현을 피합니다. 상태 클래스, props, events는 공통 명세의 동일한 의미를 유지합니다. DOM 구조는 스타일 편의를 위해 불필요하게 깊어지지 않도록 하고 사용 가능한 시맨틱 HTML 요소를 우선합니다.

항목	문서에 포함할 내용
목적	컴포넌트가 해결하는 문제와 사용하지 않아야 하는 상황
API	속성, 타입, 기본값, 필수 여부와 값 사이의 제약
상태	기본, hover, focus, disabled, readonly, loading, error, empty
이벤트	발생 조건, 전달 값, 취소 가능 여부와 중복 실행 처리
접근성	역할, 접근 가능한 이름, 키보드 규칙, 포커스 이동과 상태 알림
콘텐츠	레이블 작성법, 길이 제한, 번역과 빈 값 처리

상태 문서화

기본 상태뿐 아니라 hover, focus, disabled, readonly, loading, error, empty 상태를 스토리북에서 각각 확인할 수 있어야 합니다. 여러 상태가 동시에 적용될 때 우선순위도 정의합니다. 예를 들어 로딩 중 Button이 비활성화되는지, 오류가 있는 readonly 필드는 어떻게 읽히는지 문서에 명시합니다.

예제 작성

단일 기능을 보여주는 최소 예제와 실제 화면에 가까운 조합 예제를 분리합니다. 예제는 복사해 사용할 수 있어야 하며 접근성 레이블, 오류 처리와 키보드 동작을 생략하지 않습니다. Example, Test 같은 임시 문구 대신 실제 길이와 의미에 가까운 콘텐츠를 사용합니다.

변경과 검수

1. 변경 목적과 영향받는 프레임워크, 기존 사용처를 확인합니다.
2. API나 DOM 구조가 바뀌면 이전 구현의 호환성과 마이그레이션 방법을 기록합니다.
3. Storybook에서 모든 상태와 대표 조합을 시각·키보드·접근성 관점으로 확인합니다.
4. HTML, Vue, React 등 각 구현의 속성 이름은 달라도 최종 DOM, 동작과 메시지가 같은지 비교합니다.
5. 문서, 디자인 토큰, 코드 예제와 배포 버전을 함께 갱신합니다.