Communitygithub.com

components.build 규격

최신 React UI 컴포넌트를 구성 가능하고 접근성 높게 제작하기 위한 포괄적인 가이드라인. 컴포넌트 라이브러리, 디자인 시스템, 또는 재사용 가능한 UI 컴포넌트를 생성, 검토, 리팩토링할 때 사용합니다.

components.build 규격란 무엇인가요?

이 스킬은 Hayden Bleasel과 shadcn이 공동 작성한 components.build 규격을 기반으로 현대적이고 구성 가능하며 접근성 높은 React UI 컴포넌트를 구축하기 위한 16가지 규칙 범주를 제공합니다. 핵심 원칙, 정의, 구성, 접근성, 상태 관리, TypeScript 타입, 다형성, as-child 패턴(Radix Slot), 데이터 속성, Tailwind CSS 및 CVA를 활용한 스타일링, 디자인 토큰, 문서화, 레지스트리, npm 배포, 마켓플레이스 전략을 다룹니다. Claude Code, Cursor, Codex 등 AI 어시스턴트가 컴포넌트 API 설계, 접근성 구현, 스타일링 시스템 구축 시 이 지침을 참조할 수 있도록 설계되었습니다. 각 규칙은 왜 중요한지, 잘못된 예시, 올바른 예시, 모범 사례를 포함한 마크다운 파일로 제공됩니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ulasalyesil/personal-website-v2/tree/HEAD/.agents/skills/components-build

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

components.build 규격은(는) 무엇을 하나요?

현대적이고 구성 가능하며 접근성 높은 UI 컴포넌트 구축을 위한 포괄적인 가이드라인입니다. 핵심 원칙부터 배포까지 16가지 규칙 범주를 포함하며, Hayden Bleasel과 shadcn이 공동 집필했습니다.

적용 시점

다음 상황에서 이 가이드라인을 참조하세요:

  • 새로운 React 컴포넌트 또는 컴포넌트 라이브러리 생성 시
  • 컴포넌트 API 및 prop 인터페이스 설계 시
  • 접근성 기능(키보드, ARIA, 포커스 관리) 구현 시
  • 구성 가능한 컴포넌트 아키텍처 구축 시
  • Tailwind CSS 및 CVA를 사용한 컴포넌트 스타일링 시
  • 레지스트리 또는 npm에 컴포넌트 게시 시

우선순위별 규칙 범주

우선순위범주초점접두사
1개요규격의 범위와 목표overview
2원칙핵심 디자인 철학principles
3정의공통 용어definitions
4구성복잡한 컴포넌트 분해composition
5접근성키보드, 스크린 리더, ARIAaccessibility
6상태제어/비제어 패턴state
7타입TypeScript props와 인터페이스types
8다형성as prop을 통한 요소 전환polymorphism
9As-ChildRadix Slot 구성 패턴as-child
10데이터 속성data-state 및 data-slotdata-attributes
11스타일링Tailwind CSS, cn 유틸리티, CVAstyling
12디자인 토큰CSS 변수 및 테마design-tokens
13문서화컴포넌트 문서documentation
14레지스트리컴포넌트 레지스트리registry
15NPMnpm에 게시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 Slot
  • as-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 Authority
  • styling-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를 참조하세요.

핵심 원칙

  1. 구성(Configuration)보다 구성(Composition) - 컴포넌트를 구성 가능한 하위 컴포넌트로 분해
  2. 기본적으로 접근성(Accessibility by Default) - 부수적인 고려사항이 아닌 필수 요구 사항
  3. 단일 요소 래핑 - 각 컴포넌트는 하나의 HTML 요소를 감쌈
  4. HTML 속성 확장 - 항상 네이티브 요소 props를 확장
  5. 타입 내보내기 - prop 타입을 소비자가 사용할 수 있도록 함
  6. 두 상태 패턴 모두 지원 - 제어 및 비제어
  7. 지능형 클래스 병합 - tailwind-merge와 함께 cn() 유틸리티 사용

저자

공동 집필:

AI 스킬로 각색:

components.build 규격 기반.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ulasalyesil/personal-website-v2

Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.

ulasalyesil/personal-website-v2

Conduct design interviews, generate five distinct UI variations in a temporary design lab, collect feedback, and produce implementation plans. Use when the user wants to explore UI design options, redesign existing components, or create new UI with multiple approaches to compare.

ulasalyesil/personal-website-v2

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

ulasalyesil/personal-website-v2

Design and implement microinteractions, motion design, transitions, and user feedback patterns. Use when adding polish to UI interactions, implementing loading states, or creating delightful user experiences.

ulasalyesil/personal-website-v2

This skill is for interface design — dashboards, admin panels, apps, tools, and interactive products. NOT for marketing design (landing pages, marketing sites, campaigns).

ulasalyesil/personal-website-v2

Best practices and example-driven guidance for building SwiftUI views and components. Use when creating or refactoring SwiftUI UI, designing tab architecture with TabView, composing screens, or needing component-specific patterns and examples.

ulasalyesil/personal-website-v2

UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples.

ulasalyesil/personal-website-v2

Conduct WCAG 2.2 accessibility audits with automated testing, manual verification, and remediation guidance. Use when auditing websites for accessibility, fixing WCAG violations, or implementing accessible design patterns.

ulasalyesil/personal-website-v2

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".

ulasalyesil/personal-website-v2

Enforces an opinionated UI baseline to prevent AI-generated interface slop.

ulasalyesil/personal-website-v2

Ship correct, complete metadata.

ulasalyesil/personal-website-v2

Survey any codebase as a senior advisor and produce prioritized, self-contained implementation plans for OTHER models/agents to execute. Strictly read-only on source code — never implements, fixes, or refactors anything itself. Use when asked to audit a codebase, find improvement opportunities (bugs, security, performance, test coverage, tech debt, migrations, DX), suggest features or where to take the project next (roadmap, product direction), or generate handoff plans for another agent to implement.

ulasalyesil/personal-website-v2

Defines the product's objects, relationships, states, and vocabulary independently of any interface — the most load-bearing layer

ulasalyesil/personal-website-v2

Maps domain concepts, terminology conflicts, and bounded contexts — produces a noun harvest for the conceptual model layer

ulasalyesil/personal-website-v2

Maps interaction structure and flow — produces breadboard notation with edge cases, failure paths, and open decisions

ulasalyesil/personal-website-v2

Framework orientation for Layers of Product Design — load this first; provides the context all other skills depend on

ulasalyesil/personal-website-v2

User research planning and synthesis at the observed behaviour layer — produces candidate job stories with confidence ratings

ulasalyesil/personal-website-v2

Diagnostic audit across all seven layers — identifies the bottleneck layer and recommends where to focus

ulasalyesil/personal-website-v2

Connects user opportunities to business outcomes and solution bets — produces a strategy tree and prioritised experiments

ulasalyesil/personal-website-v2

Audits existing surface against lower-layer decisions and produces a surface decision inventory — vocabulary, object consistency, completeness, feedback, hierarchy, accessibility

관련 스킬