components.build 규격은(는) 무엇을 하나요?
현대적이고 구성 가능하며 접근성 높은 UI 컴포넌트 구축을 위한 포괄적인 가이드라인입니다. 핵심 원칙부터 배포까지 16가지 규칙 범주를 포함하며, Hayden Bleasel과 shadcn이 공동 집필했습니다.
적용 시점
다음 상황에서 이 가이드라인을 참조하세요:
- 새로운 React 컴포넌트 또는 컴포넌트 라이브러리 생성 시
- 컴포넌트 API 및 prop 인터페이스 설계 시
- 접근성 기능(키보드, ARIA, 포커스 관리) 구현 시
- 구성 가능한 컴포넌트 아키텍처 구축 시
- Tailwind CSS 및 CVA를 사용한 컴포넌트 스타일링 시
- 레지스트리 또는 npm에 컴포넌트 게시 시
우선순위별 규칙 범주
| 우선순위 | 범주 | 초점 | 접두사 |
|---|---|---|---|
| 1 | 개요 | 규격의 범위와 목표 | overview |
| 2 | 원칙 | 핵심 디자인 철학 | principles |
| 3 | 정의 | 공통 용어 | definitions |
| 4 | 구성 | 복잡한 컴포넌트 분해 | composition |
| 5 | 접근성 | 키보드, 스크린 리더, ARIA | accessibility |
| 6 | 상태 | 제어/비제어 패턴 | state |
| 7 | 타입 | TypeScript props와 인터페이스 | types |
| 8 | 다형성 | as prop을 통한 요소 전환 | polymorphism |
| 9 | As-Child | Radix Slot 구성 패턴 | as-child |
| 10 | 데이터 속성 | data-state 및 data-slot | data-attributes |
| 11 | 스타일링 | Tailwind CSS, cn 유틸리티, CVA | styling |
| 12 | 디자인 토큰 | CSS 변수 및 테마 | design-tokens |
| 13 | 문서화 | 컴포넌트 문서 | documentation |
| 14 | 레지스트리 | 컴포넌트 레지스트리 | registry |
| 15 | NPM | npm에 게시 | npm |
| 16 | 마켓플레이스 | 컴포넌트 마켓플레이스 | marketplaces |
빠른 참조
1. 개요
overview- 규격의 범위, 목표 및 철학
2. 원칙
principles- 구성 가능성, 접근성, 사용자 정의, 투명성
3. 정의
definitions- 공통 용어 (원시, 복합, 헤드리스 등)
4. 구성
composition-root- Context를 통한 공유 상태를 가진 루트 컴포넌트composition-item- 아이템 래퍼 컴포넌트composition-trigger- 대화형 트리거 컴포넌트composition-content- 콘텐츠 표시 컴포넌트composition-export- 네임스페이스 내보내기 패턴
5. 접근성
accessibility-semantic-html- 적절한 HTML 요소 사용accessibility-keyboard- 완전한 키보드 탐색 지원accessibility-aria- 적절한 ARIA 역할, 상태 및 속성accessibility-focus- 포커스 관리 및 복원accessibility-live-regions- 스크린 리더 알림accessibility-contrast- 색상 대비 요구 사항
6. 상태
state-uncontrolled- 내부 상태 관리state-controlled- 외부 상태 위임state-controllable- useControllableState로 두 패턴 모두 지원
7. 타입
types-extend-html- 네이티브 HTML 속성 확장types-export- 소비자를 위한 prop 타입 내보내기types-single-element- 하나의 컴포넌트는 하나의 요소만 감쌈
8. 다형성
polymorphism-as-prop- 렌더링된 요소 타입 변경polymorphism-typescript- 타입 안전 다형성 컴포넌트polymorphism-defaults- 시맨틱 요소 기본값
9. As-Child
as-child-slot- prop 병합을 위한 Radix Slotas-child-composition- 자식 컴포넌트와 구성
10. 데이터 속성
data-attributes-state- 상태 스타일링에data-state사용data-attributes-slot- 하위 컴포넌트 타겟팅에data-slot사용
11. 스타일링
styling-cn-utility- clsx와 tailwind-merge 결합styling-order- 기본 → 변형 → 조건부 → 사용자 재정의styling-cva- 변형을 위한 Class Variance Authoritystyling-css-variables- CSS 변수를 사용한 동적 값
12. 디자인 토큰
design-tokens-css-variables- CSS 변수로 토큰 정의design-tokens-theming- 라이트/다크 모드 및 테마 지원
13. 문서화
documentation-props- JSDoc으로 모든 prop 문서화documentation-examples- 사용 예제 제공
14. 레지스트리
registry-structure- 레지스트리 파일 구조registry-schema- 컴포넌트 메타데이터 스키마
15. NPM
npm-package-json- 패키지 구성npm-exports- 모듈 내보내기
16. 마켓플레이스
marketplaces-distribution- 컴포넌트 배포 전략
사용 방법
자세한 설명과 코드 예제는 개별 규칙 파일을 읽으세요:
rules/composition/SKILL.md
rules/accessibility/SKILL.md
rules/styling/SKILL.md
각 규칙 파일에는 다음이 포함됩니다:
- 왜 중요한지에 대한 간략한 설명
- 설명이 포함된 잘못된 코드 예제
- 설명이 포함된 올바른 코드 예제
- 모범 사례와 일반적인 함정
전체 컴파일된 문서
모든 규칙이 확장된 전체 가이드는 AGENTS.md를 참조하세요.
핵심 원칙
- 구성(Configuration)보다 구성(Composition) - 컴포넌트를 구성 가능한 하위 컴포넌트로 분해
- 기본적으로 접근성(Accessibility by Default) - 부수적인 고려사항이 아닌 필수 요구 사항
- 단일 요소 래핑 - 각 컴포넌트는 하나의 HTML 요소를 감쌈
- HTML 속성 확장 - 항상 네이티브 요소 props를 확장
- 타입 내보내기 - prop 타입을 소비자가 사용할 수 있도록 함
- 두 상태 패턴 모두 지원 - 제어 및 비제어
- 지능형 클래스 병합 - tailwind-merge와 함께
cn()유틸리티 사용
저자
공동 집필:
- Hayden Bleasel (@haydenbleasel)
- shadcn (@shadcn)
AI 스킬로 각색:
- Jordan Gilliam (@nolansym)
components.build 규격 기반.