디자인 규칙에 맞춰 UI 컴포넌트 라이브러리를 만들고 고치기

## 작업 종류별로 기준 사양을 먼저 읽고, 문서가 다르면 코드를 따르기 편집하기 전에 작업을 분류하고 그 작업을 규정하는 출처를 읽는다. - 컴포넌트 동작이나 API를 다룰 때는 공개 API 가이드, 구현, 인접한 승인 완료 컴포넌트를 읽는다. - 스타일을 다룰 때는 상세 스타일 명세, 컴파일 시간 토큰 파일, 런타임 테마 파일, 인접한 범위 지정 스타일을 읽는다. - 빌드를 변경할 때는 파이프라인을 바꾸기 전에 빌드 구성과 모든 사용자 지정 플러그인 계약을 읽는다. - 테스트를 다룰 때는 전용 테스트 구성과 인접한 테스트를 읽고, 문서를 다룰 때는 동기화 매트릭스를 읽는다. - 충돌은 소스와 현재 활성 구성, 저장소 규칙, 전문 문서, 일반적 경험 순으로 해결한다. - 소스와 문서가 다르면 소스를 따르고, 동일하게 승인된 범위 안에서 오래된 문서를 함께 바로잡는다. - 빠른 참조 표는 규칙의 독립된 사본이 아니라 권위 있는 섹션으로 안내하는 포인터로 취급한다. - API를 절대로 지어내거나 버전에 민감한 동작을 기억에 의존하지 않는다. 설치된 버전과 함께 제공된 문서를 확인한다. 구현 전에 영향을 받는 export, 스타일, 테스트, 데모 레지스트리, 문서, 빌드 불변 조건을 나열한다. ## 컴포넌트마다 코드·스타일·테스트를 한 폴더에 두기 각 컴포넌트에 전용 폴더 하나를 두고 구현, 범위 지정 스타일 파일, export 진입점, 같은 위치의 단위 테스트를 포함한다. 공개 값 export와 타입 export를 별도로 추가하고 필요한 데모 화면을 모두 등록한다. - 타입이 지정된 함수 컴포넌트를 사용하고, 매개변수 구조 분해에서 기본값을 정의하며, 안정적인 표시 이름을 설정한다. - 적절한 네이티브 요소 속성을 확장하고 충돌하는 필드만 제외한다. - 컴포넌트명과 타입명은 저장소의 표준 대소문자 표기를, 스타일 파일은 구성된 파일명 형식을, 범위 지정 클래스명은 구성된 클래스 규칙을 따른다. - 엄격한 null 검사와 격리 모듈 규칙을 유지한다. 타입이 없는 우회로를 피하고 명시적인 타입 전용 export를 사용한다. - import는 맨 위에 두고 구성된 프로젝트 별칭을 사용하며, 컴포넌트 범위 지정 스타일에 전역 선택자를 두지 않는다. - 생성된 클래스명을 하드코딩하지 말고 범위 지정 스타일 맵이나 승인된 클래스 도우미를 통해 클래스를 조합한다. - 재사용 가능한 도우미의 목적을 명확히 제한하고 저장소 규칙이 정한 위치에 배치한다. 컴포넌트의 공개 인터페이스를 변경할 때는 export, 테스트, 예시, API 문서를 함께 업데이트해야 한다. ## 색과 모서리는 따로 쓴 숫자가 아니라 공통 디자인 값으로 정하기 용도별로 토큰 계층을 분리해 유지한다. 컴파일 시간 변수는 계산과 mixin을 지원하고, 런타임 CSS 사용자 지정 속성은 사용자가 테마를 재정의할 수 있게 한다. 두 계층을 서로 바꿔 쓸 수 있는 것으로 취급하지 않는다. - 빌드 구성과 테스트 구성 사이에서 CSS Modules 명명법과 토큰 주입 방식을 일관되게 유지한다. - 컴포넌트 스타일에서는 런타임 시맨틱 토큰을 우선하고, 전처리가 필요한 경우에만 컴파일 시간 변수를 사용한다. - 색상, 포커스, 반경, 높낮이, 타이포그래피, 굵기, 모션을 고립된 원시 값이 아니라 시스템의 의미 역할로 표현한다. - 디자인 언어가 색조가 있는 표면, 따뜻한 텍스트 색상, 브랜드 고유 포커스 상태를 정의한다면 순수 극단값과 일반적인 차가운 기본값을 피한다. - 의도된 컴포넌트 윤곽, 상태 표현, 그림자 규칙을 하나의 일반 패턴으로 평준화하지 말고 보존한다. - 전역 글꼴, 테마 변수, 초기화 스타일은 하나의 전역 스타일 진입점 뒤에 둔다. - 모션 감소 환경설정을 존중하고, 눈에 보이는 포커스, 키보드 사용, 읽기 쉬운 대비, 문서화된 접근성 역할을 유지한다. 정확한 값과 컴포넌트별 예외는 기억이 아니라 권위 있는 디자인 명세와 현재 소스에서 가져온다. ## 컴포넌트마다 키보드 조작과 접근성을 테스트하기 선언된 DOM 환경, 설정 파일, matcher, 별칭, CSS Modules 처리를 갖춘 저장소 전용 테스트 구성을 사용한다. 활성 테스트 실행기가 무시하는 빌드 구성으로 테스트 설정을 옮기지 않는다. - 컴포넌트 테스트를 컴포넌트와 같은 위치에 두고, 승인된 렌더링·쿼리·사용자 상호작용 유틸리티를 사용한다. - 렌더링, prop에 따라 달라지는 클래스, 콜백, 비활성화 상태의 동작, 상태 변화, 관련 접근성 역할을 다룬다. - 포커스 이동, 활성화, 닫기, 방향 제어를 포함하여 컴포넌트 패턴이 요구하는 키로 키보드 동작을 확인한다. - 생성된 문자열 리터럴이 아니라 import한 스타일 맵을 통해 범위 지정 클래스를 검증한다. - 명령형 API는 테스트 프레임워크의 상태 경계 안에서 호출하고 마운트된 결과를 기다려 테스트한다. 컴포넌트가 아닌 API를 JSX로 렌더링하지 않는다. - 공유 테스트 유틸리티를 중앙에서 관리하고, 저수준 이벤트 단축 방식 대신 실제에 가까운 사용자 상호작용을 사용한다. - 낮은 가치의 사례로 커버리지를 부풀리지 말고 구성된 커버리지 임계값을 충족하며 의도적으로 제외한 항목을 문서화한다. 결함에는 먼저 범위를 좁힌 실패 테스트를 실행하고, 이어서 영향받는 테스트 모음을 실행하며, 완료 전에는 요구되는 전체 테스트 모음을 실행한다. ## 쓰는 컴포넌트만 불러오도록 빌드를 모듈 단위로 유지하기 사용자 지정 빌드 플러그인, 패키지 export, 에셋 규칙을 사용자와의 계약으로 취급한다. - 사용하지 않는 컴포넌트를 계속 tree shaking할 수 있도록 모듈 경계를 유지하면서 ES-module과 CommonJS 출력을 분리해 보존한다. - 프레임워크와 승인된 도우미 패키지가 peer dependency라면 external로 유지한다. 명시적인 요구사항 없이 runtime dependency를 추가하지 않는다. - CSS 코드 분할과 각 컴포넌트의 스타일을 해당 JavaScript 진입점에 연결하는 메커니즘을 유지한다. - 전역 스타일시트 진입점을 완전하게 유지하는 동시에, 사용하지 않는 컴포넌트 에셋이 사용자 bundle에 들어가지 않게 한다. - 글꼴 형식과 public path 요구사항을 포함하여 저장소의 에셋 복사 및 인라인 처리 정책을 따른다. - 패키지 export map, 배포 파일, side effect 선언을 생성된 구조에 맞춘다. - 사용자 지정 플러그인 계약을 읽은 뒤에만 빌드 로직을 변경하고, 그 후 컴포넌트 수준 import와 전역 스타일 진입점을 모두 확인한다. 생성된 배포, 데모 빌드, 커버리지 디렉터리는 작성 영역이 아니라 출력물이며, 저장소 정책에서 명시적으로 요구하지 않는 한 커밋해서는 안 된다. ## 컴포넌트를 바꾸면 문서와 데모 페이지도 함께 고치기 컴포넌트 변경의 영향을 받는 모든 권위 있는 영역을 업데이트한다. - API 또는 prop 변경 시 소스를 기준으로 API 매뉴얼을 업데이트하고, 스타일 변경 시 상세 스타일 명세를 업데이트한다. - 시각 언어 변경 시 디자인 개요를 업데이트하고, 새 컴포넌트 추가 시 사용자용 프롬프트 또는 카탈로그 명세를 업데이트한다. - 컴포넌트 수나 커버리지 변경 시 승인된 생성기를 통해 모든 미러링된 readme를 업데이트한다. - 데모 등록은 경로 메타데이터, 렌더러 맵, 홈페이지 카탈로그에 나뉠 수 있으므로 모든 독립 레지스트리를 업데이트한다. - 기계 판독 가능한 개수는 수동으로 중복 기록하지 말고 권위 있는 메타데이터에서 도출한다. - 문서 동기화 검사기를 실행하고, 이 검사기가 확인하지 않는 데모 또는 생성 영역이 무엇인지 파악한다. - 추적되는 산출물은 생성된 출력을 직접 편집하지 말고 승인된 명령으로 다시 생성한다. 등록 변경 후 데모 경로를 선택했을 때 의도한 페이지가 렌더링되는지 확인한다. 메뉴는 강조되지만 기본 영역이 비어 있다면 대개 레지스트리 항목이 누락된 것이다. ## 일괄 치환 실수와 빈 데모 페이지 같은 알려진 실패 막기 많은 파일을 눈에 띄지 않게 손상시킬 수 있는 변경에는 범위가 좁고 검증 가능한 작업을 사용한다. - 스크립트 기반 치환에서는 모든 대상을 즉시 확인하고, 문자열 연산이 불변이라는 점을 고려하며, 따옴표가 있는 마크업을 가로지를 때 실패하는 패턴을 피한다. - 테스트 도구가 구조화된 출력을 기록할 때는 기본 파일이 있다고 가정하지 말고 필요한 출력 경로를 제공한다. - DOM을 이미지로 캡처할 때 렌더링 엔진이 문서 글꼴 레지스트리를 읽을 수 없다면 필요한 글꼴 선언을 캡처 루트에 포함한다. - 겉보기의 tree-shaking 지표만 개선하려고 의도된 내부 컴포넌트 의존성을 리팩터링하지 않는다. - 주문형 import를 유지하고 사용하지 않는 대형 에셋, 글꼴, 컴포넌트가 사용자 bundle에 들어가지 않게 하여 패키지 크기를 최적화한다. - 빈 데모 페이지를 진단할 때는 컴포넌트 구현을 변경하기 전에 모든 독립 페이지 레지스트리를 확인한다. 저장소가 안정적인 위치를 제공한다면 반복된다고 확인된 각 실패를 범위가 좁은 자동 검사로 전환한다. ## 변경을 넘기기 전에 CI 검사를 모두 통과시키기 문서화된 포매터 검사, lint, 단위 테스트, 라이브러리 빌드를 저장소가 요구하는 순서로 실행한다. 기여를 제안하기 전에 전체 CI 명령을 실행한다. 다음을 확인한다. - 변경된 모든 컴포넌트, export, 테스트, 문서, 데모 레지스트리가 동기화되어 있다. - 커버리지 또는 컴포넌트 수 배지는 입력이 변경된 경우 다시 생성되었다. - 승인되지 않은 runtime dependency나 생성된 출력물이 변경에 포함되지 않았다. - 모듈식 출력, CSS 분할, 에셋 로딩 계약이 계속 유지된다. - 시각적 변경이 현재 토큰 및 컴포넌트 명세와 일치한다. - 최종 diff에는 의도한 소스 및 문서 변경만 포함되어 있다. 필수 검사 하나라도 실패하면 diff를 제시하기 전에 실패를 수정하고 관련 게이트를 다시 실행한다. 저장소의 기여 형식을 사용하고, 릴리스 또는 공개 워크플로는 작업에 명시적으로 포함된 경우에만 실행한다. 실행한 정확한 검사와 의도적으로 범위에서 제외한 더 광범위한 검사를 보고한다.