Communitygithub.com

UI 컴포넌트 패턴

재사용 가능하고 유지보수하기 쉬운 UI 컴포넌트를 현대적인 디자인 패턴으로 구축합니다. 컴포넌트 라이브러리 생성, 디자인 시스템 구현, 확장 가능한 프론트엔드 아키텍처 구축 시 사용합니다. React 패턴, 컴포지션, prop 설계, TypeScript 및 컴포넌트 모범 사례를 다룹니다.

UI 컴포넌트 패턴란 무엇인가요?

이 스킬은 재사용 가능하고 유지보수 가능한 UI 컴포넌트를 현대적인 디자인 패턴으로 구축하기 위한 포괄적인 가이드를 제공합니다. 주요 대상은 React와 TypeScript를 사용하는 프론트엔드 개발자이며, 컴포넌트 라이브러리 생성, 디자인 시스템 구현, 또는 확장 가능한 프론트엔드 아키텍처를 구축할 때 특히 유용합니다. 이 스킬은 Props API 설계, 합성(Composition) 패턴, Render Props, Custom Hooks를 통한 로직 분리, 성능 최적화(React.memo, useMemo, useCallback) 등의 핵심 개념을 단계별로 설명합니다. 또한 접근성, 단일 책임 원칙, 과도한 Props Drilling 금지 등 엄격한 제약 사항을 명시하여 실무에서 바로 적용 가능한 모범 사례를 제시합니다. Claude, ChatGPT, Gemini와 같은 주요 AI 플랫폼과 호환됩니다.

지원 대상✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/aiskillstore/marketplace/supercent-io/ui-component-patterns

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

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

미리보기

스킬 README에서

UI 컴포넌트 패턴 preview

문서

UI 컴포넌트 패턴은(는) 무엇을 하나요?

이 스킬을 사용해야 할 때

  • 컴포넌트 라이브러리 구축: 재사용 가능한 UI 컴포넌트 생성
  • 디자인 시스템 구현: 일관된 UI 패턴 적용
  • 복잡한 UI: 여러 변형이 필요한 컴포넌트 (Button, Modal, Dropdown)
  • 리팩토링: 중복 코드를 컴포넌트로 추출

지침

1단계: Props API 설계

사용하고 확장하기 쉬운 Props를 설계합니다.

원칙:

  • 명확한 이름
  • 합리적인 기본값
  • TypeScript를 이용한 타입 정의
  • 선택적 Props는 선택적 마커(?) 사용

예시 (Button):

interface ButtonProps {
  // 필수
  children: React.ReactNode;

  // 선택적 (기본값 있음)
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  isLoading?: boolean;

  // 이벤트 핸들러
  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;

  // HTML 속성 상속
  type?: 'button' | 'submit' | 'reset';
  className?: string;
}

function Button({
  children,
  variant = 'primary',
  size = 'md',
  disabled = false,
  isLoading = false,
  onClick,
  type = 'button',
  className = '',
  ...rest
}: ButtonProps) {
  const baseClasses = 'btn';
  const variantClasses = `btn-${variant}`;
  const sizeClasses = `btn-${size}`;
  const classes = `${baseClasses} ${variantClasses} ${sizeClasses} ${className}`;

  return (
    <button
      type={type}
      className={classes}
      disabled={disabled || isLoading}
      onClick={onClick}
      {...rest}
    >
      {isLoading ? <Spinner /> : children}
    </button>
  );
}

// 사용 예시
<Button variant="primary" size="lg" onClick={() => alert('클릭!')}>
  클릭하세요
</Button>

2단계: 합성(Composition) 패턴

작은 컴포넌트를 결합하여 복잡한 UI를 구축합니다.

예시 (Card):

// Card 컴포넌트 (컨테이너)
interface CardProps {
  children: React.ReactNode;
  className?: string;
}

function Card({ children, className = '' }: CardProps) {
  return <div className={`card ${className}`}>{children}</div>;
}

// Card.Header
function CardHeader({ children }: { children: React.ReactNode }) {
  return <div className="card-header">{children}</div>;
}

// Card.Body
function CardBody({ children }: { children: React.ReactNode }) {
  return <div className="card-body">{children}</div>;
}

// Card.Footer
function CardFooter({ children }: { children: React.ReactNode }) {
  return <div className="card-footer">{children}</div>;
}

// 복합 컴포넌트 패턴
Card.Header = CardHeader;
Card.Body = CardBody;
Card.Footer = CardFooter;

export default Card;

// 사용법
import Card from './Card';

function ProductCard() {
  return (
    <Card>
      <Card.Header>
        <h3>상품명</h3>
      </Card.Header>
      <Card.Body>
        <img src="..." alt="상품" />
        <p>여기에 상품 설명...</p>
      </Card.Body>
      <Card.Footer>
        <button>장바구니에 추가</button>
      </Card.Footer>
    </Card>
  );
}

3단계: Render Props / 함수형 Children

유연한 커스터마이징을 위한 패턴입니다.

예시 (Dropdown):

interface DropdownProps<T> {
  items: T[];
  renderItem: (item: T, index: number) => React.ReactNode;
  onSelect: (item: T) => void;
  placeholder?: string;
}

function Dropdown<T>({ items, renderItem, onSelect, placeholder }: DropdownProps<T>) {
  const [isOpen, setIsOpen] = useState(false);
  const [selected, setSelected] = useState<T | null>(null);

  const handleSelect = (item: T) => {
    setSelected(item);
    onSelect(item);
    setIsOpen(false);
  };

  return (
    <div className="dropdown">
      <button onClick={() => setIsOpen(!isOpen)}>
        {selected ? renderItem(selected, -1) : placeholder || '선택...'}
      </button>

      {isOpen && (
        <ul className="dropdown-menu">
          {items.map((item, index) => (
            <li key={index} onClick={() => handleSelect(item)}>
              {renderItem(item, index)}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

// 사용법
interface User {
  id: string;
  name: string;
  avatar: string;
}

function UserDropdown() {
  const users: User[] = [...];

  return (
    <Dropdown
      items={users}
      placeholder="사용자 선택"
      renderItem={(user) => (
        <div className="user-item">
          <img src={user.avatar} alt={user.name} />
          <span>{user.name}</span>
        </div>
      )}
      onSelect={(user) => console.log('선택됨:', user)}
    />
  );
}

4단계: Custom Hooks로 로직 분리

UI와 비즈니스 로직을 분리합니다.

예시 (Modal):

// hooks/useModal.ts
function useModal(initialOpen = false) {
  const [isOpen, setIsOpen] = useState(initialOpen);

  const open = useCallback(() => setIsOpen(true), []);
  const close = useCallback(() => setIsOpen(false), []);
  const toggle = useCallback(() => setIsOpen(prev => !prev), []);

  return { isOpen, open, close, toggle };
}

// components/Modal.tsx
interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  title: string;
  children: React.ReactNode;
}

function Modal({ isOpen, onClose, title, children }: ModalProps) {
  if (!isOpen) return null;

  return (
    <div className="modal-overlay" onClick={onClose}>
      <div className="modal-content" onClick={(e) => e.stopPropagation()}>
        <div className="modal-header">
          <h2>{title}</h2>
          <button onClick={onClose} aria-label="닫기">×</button>
        </div>
        <div className="modal-body">{children}</div>
      </div>
    </div>
  );
}

// 사용법
function App() {
  const { isOpen, open, close } = useModal();

  return (
    <>
      <button onClick={open}>모달 열기</button>
      <Modal isOpen={isOpen} onClose={close} title="내 모달">
        <p>여기에 모달 내용...</p>
      </Modal>
    </>
  );
}

5단계: 성능 최적화

불필요한 리렌더링을 방지합니다.

React.memo:

// ❌ 나쁨: 부모가 리렌더링될 때마다 자식도 리렌더링됨
function ExpensiveComponent({ data }) {
  console.log('렌더링...');
  return <div>{/* 복잡한 UI */}</div>;
}

// ✅ 좋음: props가 변경될 때만 리렌더링
const ExpensiveComponent = React.memo(({ data }) => {
  console.log('렌더링...');
  return <div>{/* 복잡한 UI */}</div>;
});

useMemo & useCallback:

function ProductList({ products, category }: { products: Product[]; category: string }) {
  // ✅ 필터링된 결과 메모이제이션
  const filteredProducts = useMemo(() => {
    return products.filter(p => p.category === category);
  }, [products, category]);

  // ✅ 콜백 메모이제이션
  const handleAddToCart = useCallback((productId: string) => {
    // 장바구니에 추가
    console.log('추가:', productId);
  }, []);

  return (
    <div>
      {filteredProducts.map(product => (
        <ProductCard
          key={product.id}
          product={product}
          onAddToCart={handleAddToCart}
        />
      ))}
    </div>
  );
}

const ProductCard = React.memo(({ product, onAddToCart }) => {
  return (
    <div>
      <h3>{product.name}</h3>
      <button onClick={() => onAddToCart(product.id)}>장바구니 추가</button>
    </div>
  );
});

출력 형식

컴포넌트 파일 구조

components/
├── Button/
│   ├── Button.tsx           # 메인 컴포넌트
│   ├── Button.test.tsx      # 테스트
│   ├── Button.stories.tsx   # 스토리북
│   ├── Button.module.css    # 스타일
│   └── index.ts             # 내보내기
├── Card/
│   ├── Card.tsx
│   ├── CardHeader.tsx
│   ├── CardBody.tsx
│   ├── CardFooter.tsx
│   └── index.ts
└── Modal/
    ├── Modal.tsx
    ├── useModal.ts          # Custom hook
    └── index.ts

컴포넌트 템플릿

import React from 'react';

export interface ComponentProps {
  // Props 정의
  children: React.ReactNode;
  className?: string;
}

/**
 * 컴포넌트 설명
 *
 * @example
 * ```tsx
 * <Component>안녕하세요</Component>
 * ```
 */
export const Component = React.forwardRef<HTMLDivElement, ComponentProps>(
  ({ children, className = '', ...rest }, ref) => {
    return (
      <div ref={ref} className={`component ${className}`} {...rest}>
        {children}
      </div>
    );
  }
);

Component.displayName = 'Component';

export default Component;

제약 사항

필수 규칙 (MUST)

  1. 단일 책임 원칙: 하나의 컴포넌트는 하나의 역할만 담당

    • Button은 버튼만, Form은 폼만 처리
  2. Props 타입 정의: TypeScript 인터페이스 필수

    • 자동 완성 지원
    • 타입 안전성
  3. 접근성: aria-*, role, tabindex 등

금지 규칙 (MUST NOT)

  1. 과도한 Props Drilling: 5단계 이상 깊이 전파 금지

    • Context 또는 Composition 사용
  2. 비즈니스 로직 금지: UI 컴포넌트 내 API 호출 및 복잡한 계산 금지

    • Custom hooks로 분리
  3. 인라인 객체/함수: 성능 저하

    // ❌ 잘못된 예시
    <Component style={{ color: 'red' }} onClick={() => handleClick()} />
    
    // ✅ 올바른 예시
    const style = { color: 'red' };
    const handleClick = useCallback(() => {...}, []);
    <Component style={style} onClick={handleClick} />
    

예시

예시 1: Accordion (복합 컴포넌트)

import React, { createContext, useContext, useState } from 'react';

// Context로 상태 공유
const AccordionContext = createContext<{
  activeIndex: number | null;
  setActiveIndex: (index: number | null) => void;
} | null>(null);

function Accordion({ children }: { children: React.ReactNode }) {
  const [activeIndex, setActiveIndex] = useState<number | null>(null);

  return (
    <AccordionContext.Provider value={{ activeIndex, setActiveIndex }}>
      <div className="accordion">{children}</div>
    </AccordionContext.Provider>
  );
}

function AccordionItem({ index, title, children }: {
  index: number;
  title: string;
  children: React.ReactNode;
}) {
  const context = useContext(AccordionContext);
  if (!context) throw new Error('AccordionItem은 Accordion 내에서 사용해야 합니다');

  const { activeIndex, setActiveIndex } = context;
  const isActive = activeIndex === index;

  return (
    <div className="accordion-item">
      <button
        className="accordion-header"
        onClick={() => setActiveIndex(isActive ? null : index)}
        aria-expanded={isActive}
      >
        {title}
      </button>
      {isActive && <div className="accordion-body">{children}</div>}
    </div>
  );
}

Accordion.Item = AccordionItem;
export default Accordion;

// 사용법
<Accordion>
  <Accordion.Item index={0} title="섹션 1">
    섹션 1의 내용
  </Accordion.Item>
  <Accordion.Item index={1} title="섹션 2">
    섹션 2의 내용
  </Accordion.Item>
</Accordion>

예시 2: 다형성 컴포넌트 (as prop)

type PolymorphicComponentProps<C extends React.ElementType> = {
  as?: C;
  children: React.ReactNode;
} & React.ComponentPropsWithoutRef<C>;

function Text<C extends React.ElementType = 'span'>({
  as,
  children,
  ...rest
}: PolymorphicComponentProps<C>) {
  const Component = as || 'span';
  return <Component {...rest}>{children}</Component>;
}

// 사용법
<Text>기본 span</Text>
<Text as="h1">제목 1</Text>
<Text as="p" style={{ color: 'blue' }}>문단</Text>
<Text as={Link} href="/about">링크</Text>

모범 사례

  1. Props보다 Composition: 많은 props 대신 children 활용
  2. 제어 vs 비제어: 상황에 따라 선택
  3. 기본 Props: 합리적인 기본값 제공
  4. Storybook: 컴포넌트 문서화 및 개발

참고 자료

메타데이터

버전

  • 현재 버전: 1.0.0
  • 마지막 업데이트: 2025-01-01
  • 호환 플랫폼: Claude, ChatGPT, Gemini

관련 스킬

태그

#UI-components #React #design-patterns #composition #TypeScript #frontend

Individual skills in this repo

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

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

관련 스킬