개발 안내

작업 기준

변경 전에 디자인 원칙과 대상 컴포넌트 문서를 읽습니다. 안정성을 먼저 확보하고 명확성을 함께 충족하며, 모션으로 둘을 지원합니다. 접근성·작업 완결성·사용자 통제권·오류 예방과 복구는 공통 조건입니다.

원칙의 원문은 docs/content/design-principles.mdx에서 관리합니다. AI 작업 지침은 저장소 루트의 AGENTS.md에서 이 원문을 참조합니다. 구현 규칙과 검증 조건은 관련 문서·소스·테스트에 연결하고, 확정된 결정과 제안을 구분합니다.

변경 후에는 해결한 문제, 설계 이유, 기존 API·동작에 미치는 영향, 검증한 범위와 남은 한계를 설명합니다. 자동 테스트 통과만으로 실제 사용성이나 미검증 환경의 지원을 선언하지 않습니다.

실행

Node.js 22 이상과 pnpm 11을 사용합니다.

pnpm install
pnpm dev

로컬 문서는 http://127.0.0.1:5173/docs, Storybook은 같은 서버의 /storybook에서 실행됩니다. pnpm dev는 시작할 때 Storybook을 한 번 빌드합니다.

컴포넌트를 수정하면서 즉시 확인하려면 별도 터미널에서 Storybook 개발 서버를 실행합니다.

pnpm storybook

Storybook 개발 서버는 http://localhost:6006에서 실행됩니다. 컴포넌트별 예제와 상태를 비교하고 Controls에서 지원하는 속성을 변경할 수 있습니다. 예제에서 문서로 이동하려면 5173 문서 서버도 실행합니다.

배포

pnpm build로 문서와 Storybook을 함께 빌드합니다. 배포 후에는 상단 Storybook 링크가 같은 사이트의 /storybook으로 연결됩니다. 별도 배포 주소 설정은 필요하지 않습니다.

/storybook은 /storybook/index.html로 이동하며, 예제와 이미지도 /storybook/ 아래에서 불러옵니다. Storybook 예제의 /docs 링크는 같은 사이트의 문서로 돌아갑니다.

storybook-static/과 public/storybook/은 자동 생성하는 결과물입니다. Git에 추가하지 않습니다. 로컬 문서 서버의 Storybook을 갱신할 때는 pnpm storybook:build를 실행합니다.

폴더

예제와 코드

문서의 예제 이름은 examples의 파일 이름과 연결됩니다. 미리보기는 이 파일을 실행하고, 코드 영역은 같은 파일을 읽습니다. Storybook도 같은 예제를 import합니다.

문서 예제는 iframe에서 실행되므로 문서 스타일과 모달 상태가 예제에 전달되지 않습니다. 새 창으로 열면 뷰포트 전체에서 동작을 확인할 수 있습니다.

검증

변경에 관련된 검사를 선택합니다. 문서 변경은 링크·MDX·타입을 확인하고, 컴포넌트 동작 변경은 관련 UI 검사를 실행합니다. 조합·스타일 변경은 pnpm test:resilience, 패키지·복사 배포에 영향을 주는 변경은 pnpm package:test로 문서 밖의 실제 사용도 확인합니다. 아래 명령은 사용할 수 있는 검사이며, 모든 변경에 전체 검사를 반복할 필요는 없습니다.

pnpm typecheck
pnpm test
pnpm build
pnpm test:ui
pnpm storybook:build
pnpm test:storybook

문구 작성

제목은 대상의 이름으로 씁니다. 설명에는 용도, 동작, 조건, 제약을 적습니다. 감성적인 수식과 반복적인 안내는 사용하지 않습니다. 구현 과정은 개발 기록에 남기고 컴포넌트 사용 문서와 구분합니다.