테마를 지원하는 UI 컴포넌트 라이브러리에서 컴포넌트 만들기·고치기

## 컴포넌트 변경이 닿는 파일 찾기 재사용할 수 있고 테마를 적용할 수 있으며 접근성이 확보된 컴포넌트 라이브러리에 신중하게 기여하세요. 편집하기 전에 요청된 동작, 영향을 받는 컴포넌트 또는 유틸리티, 직접 관련된 모든 영역을 식별하세요. 저장소의 실제 구조를 따르되, 컴포넌트 변경이 다음 영역 중 일부에 걸칠 수 있음을 고려하세요. - 런타임 컴포넌트와 컴포저블. - 공개 유형과 내보내기. - 테마 레시피, 변형, 기본값. - 단위 테스트, 렌더링 테스트, 스냅샷 테스트, 접근성 테스트. - 사용자 문서와 예제. - 로컬 플레이그라운드 또는 데모 페이지. 모든 영역을 변경해야 한다고 가정하지 마세요. 기존 컴포넌트와 가장 가까운 유사 구현을 추적한 다음 요청에 필요한 영역만 나열하세요. 소스와 테스트 규칙은 해당 디렉터리에만 적용하고 문서, 예제 또는 도구에 무분별하게 적용하지 마세요. 작업에서 명시적으로 변경하지 않는 한 기존 공개 동작을 보존하세요. 속성 전달, 기본값 해석, 접근성 의미, 오른쪽에서 왼쪽으로 쓰는 경우의 동작, 문서화된 API를 구현 세부 사항이 아니라 계약으로 취급하세요. ## 필요한 가이드만 읽고 생성기로 시작하기 먼저 저장소 수준의 기여 지침을 읽은 다음 작업과 관련된 참조 자료만 불러오세요. 예를 들어 props, slots, events, 템플릿 패턴에는 컴포넌트 구조 지침을, slots와 variants에는 테마 지침을, 렌더링, 스냅샷, 접근성에는 테스트 지침을, 예제와 마크업에는 문서 지침을 사용하세요. 참조 자료가 존재한다는 이유만으로 전부 불러오지 마세요. 영향을 받는 파일에서 시작해 최근의 비교 가능한 구현을 조사하고, 변경이 해당 문제에 닿을 때만 추가 지침을 여세요. 프로젝트에서 선언한 패키지 스크립트와 지원되는 패키지 관리자를 사용하세요. 종속성을 설치한 뒤 플레이그라운드, 문서 사이트 또는 검사를 시작하기 전에 필수 준비 단계나 유형 생성 단계를 실행하세요. 변경에 적합한 로컬 환경으로 주 애플리케이션 플레이그라운드, 다른 프레임워크용 플레이그라운드, 문제 재현에 집중한 환경 또는 문서 사이트를 사용하세요. 컴포넌트를 만들 때는 저장소에서 승인한 생성기를 우선 사용하세요. 생성된 파일을 편집하기 전에 검토하고 작업에 필요한 템플릿만 요청하세요. 적용할 수 있는 생성기가 없다면 확립된 파일 배치와 명명 규칙을 수동으로 재현하세요. ## 테마 기본값의 우선순위와 오른쪽에서 왼쪽 레이아웃 지키기 라이브러리에서 확립된 코드 규칙을 일관되게 따르세요. - 도구 체인이나 스타일 지침에서 요구하는 경우 유형 전용 가져오기를 분리하세요. - 표준 헬퍼를 통해 런타임 props 기본값을 정의하고 유형 중심 API에 공개 기본값을 문서화하세요. - 렌더링된 요소에 안정적인 slot 마커를 추가하세요. 루트 요소에서는 호출자가 제공한 마커가 컴포넌트의 대체 값을 재정의해야 하며, 내부 요소는 자체 마커를 유지해야 합니다. - 자동 속성 전달이 비활성화되어 있다면 호출자 속성이 조용히 덮어써지지 않도록 루트 바인딩의 순서를 정하거나 해석하세요. - 테마 상태를 한 번만 평가하지 말고 표준 계산 메커니즘을 통해 반응형 테마 출력을 구성하세요. - 전체 우선순위 체인을 통해 기본값을 해석하세요. 명시적인 컴포넌트 입력, 가장 가까운 그룹 또는 필드 컨텍스트, 라이브러리 수준 테마 재정의, 컴포넌트 기본값, 프로젝트에서 정의한 애플리케이션 구성 순서입니다. - 프록시 처리가 주입 우선순위를 바꾼다면 컨텍스트 헬퍼에 원시 입력을 전달하세요. 더 가까운 컨텍스트가 없을 때는 테마 수준 기본값을 버리지 말고 해석된 컴포넌트 값을 대체 값으로 사용하세요. - 해석된 기본값이 유지되도록 프리미티브 라이브러리의 props와 events를 프로젝트의 프록시 대응 어댑터를 통해 전달하세요. 원시 팔레트 값 대신 의미 기반 디자인 토큰을 사용하세요. 왼쪽에서 오른쪽과 오른쪽에서 왼쪽 컨텍스트 모두에서 레이아웃이 동작하도록 논리적 간격, 위치, 테두리, 반경, 텍스트 정렬 속성을 사용하세요. 논리 속성으로 동작을 표현할 수 없는 변형, 커서, 그라데이션 또는 전환에는 방향을 명시적으로 고려한 대안을 추가하세요. 구현을 기존 패턴에 맞추세요. 하나의 컴포넌트를 위해 경쟁하는 기본값 시스템, props 전달 경로 또는 테마 해석 계층을 도입하지 마세요. ## 체크리스트로 테마부터 테스트와 문서까지 만들기 다음 점검 목록을 사용해 새 컴포넌트 또는 주요 컴포넌트 기능을 추적하세요. 1. 표준 런타임 위치에 컴포넌트의 뼈대를 생성하거나 컴포넌트를 만드세요. 2. 동작, 공개 props, slots, events, 접근성 의미를 구현하세요. 3. slots, variants, 복합 variants, 의미 기반 토큰을 포함한 테마 레시피를 추가하거나 업데이트하세요. 4. 공개 유형을 내보내고 테마 시스템에 필요한 컴포넌트 기본값 인터페이스를 등록하세요. 5. 해당하는 경우 동작, props, slots, 속성 전달, 방향성, 접근성에 초점을 맞춘 테스트를 추가하세요. 6. 사용법, 예제, API 세부 정보를 포함하도록 사용자 문서를 업데이트하세요. 7. 변경된 동작을 보여 주는 플레이그라운드 예제를 추가하거나 업데이트하세요. 8. 린트, 정적 유형 검사, 관련 테스트 모음을 실행하세요. 프로젝트가 스냅샷을 유용한 계약으로 취급하는 경우에만 사용하고, 생성된 변경을 자동으로 수락하지 말고 검토하세요. 테스트는 외부에서 의미 있는 동작과 알려진 우선순위 규칙에 집중하세요. 문서가 패키지 릴리스보다 먼저 배포된다면 영향을 받는 제목이나 예제에 프로젝트가 승인한 사전 릴리스 마커를 유지하세요. 이 마커는 병합된 문서가 다음 릴리스에서 제공될 기능을 설명할 수 있음을 의도적으로 알립니다. 릴리스 정책을 확인하지 않은 채 마커를 제거하거나 불일치로 보고하지 마세요. ## 린트와 테스트를 실제로 돌리고 결과를 붙여 풀 리퀘스트 올리기 최종 diff를 가장 가까운 기존 패턴과 원래 요청에 대조해 검토하세요. 다음을 확인하세요. - 컴포넌트 구조, 공개 유형, 내보내기가 일관되어 있습니다. - 테마 코드가 의미 기반 토큰을 사용하고 전체 기본값 우선순위 체인을 보존합니다. - 루트 속성과 slot 마커가 호출자의 재정의를 존중합니다. - 논리 속성 또는 명시적인 방향 변형이 오른쪽에서 왼쪽으로 쓰는 경우의 동작을 다룹니다. - 테스트가 변경된 props, slots, 동작, 접근성 요구 사항을 다룹니다. - 문서에 필요한 사용법, 예제, API 변경이 포함되어 있습니다. - 의도적인 사전 릴리스 문서 마커가 그대로 유지됩니다. 저장소의 린트, 유형 검사, 관련 테스트 명령을 실행하고 실제 결과를 보고하세요. 코드를 살펴본 것만으로 검사가 통과했다고 주장하지 마세요. 공개 동작이 바뀌면 문서를 업데이트하세요. 저장소에서 요구하는 커밋 메시지 규칙과 풀 리퀘스트 템플릿을 사용하세요. 관련 작업 항목을 연결하고 변경 유형을 식별하며 동작과 검증 내용을 설명하고, 증거로 뒷받침되는 점검 목록 항목만 완료하세요. 단지 깔끔하게 보이게 하려고 기여자의 커밋 기록을 다시 작성하거나 `rebase`, `force-push`, 압축을 수행하지 마세요. 저장소에서 스쿼시 병합을 수행한다면 여러 개발 커밋이 허용될 수 있습니다. 저장소의 실제 병합 정책과 사용자 권한을 따르세요.