🧩 Tailwind 11장: 컴포넌트 패턴과 재사용 설계

2026년 3월 5일 수정됨

📋 개요

cva, tailwind-merge 로 타입 안전한 재사용 컴포넌트 만들기 — 변형(variant) 기반 컴포넌트 설계의 정석

📋 목차

📌 이 문서를 읽기 전에
🤔 왜 알아야 하는가
⚠️ 클래스 충돌 문제: tailwind-merge
🎨 변형(Variant) 기반 컴포넌트: cva
🔗 cva + tailwind-merge 조합 (최강 패턴)
💻 실전: 영수네 커뮤니티 컴포넌트 라이브러리
🏁 이번에 배운 내용 총정리
📝 마무리 퀴즈
🐣 영철이의 퇴근 일기
🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 20분

🎯 이 문서를 다 읽으면 할 수 있는 것

tailwind-merge 로 클래스 충돌 없이 컴포넌트 스타일을 오버라이드할 수 있다
cva 로 타입 안전한 변형 기반 컴포넌트를 설계할 수 있다
Button, Badge, Input, Card 같은 기본 컴포넌트를 시니어 수준으로 작성할 수 있다

🤔 왜 알아야 하는가

영철이가 Button 컴포넌트를 이렇게 만들었어:

// 🐣 영철의 순진한 접근
function Button({ className, children }: { className?: string; children: React.ReactNode }) {
  return (
    <button className={`bg-blue-600 text-white px-6 py-3 rounded-xl ${className}`}>
      {children}
    </button>
  );
}
 
// 사용 시 크기를 바꾸고 싶어서...
<Button className="px-3 py-1.5">작은 버튼</Button>

결과? className 이 bg-blue-600 text-white px-6 py-3 rounded-xl px-3 py-1.5 — px-6 과 px-3 이 동시에 선언돼버려. CSS 에서는 나중에 오는 게 이기는데, 어느 쪽이 나중인지는 Tailwind 클래스 정의 순서에 따라 달라져서 예측 불가야.

이게 바로 클래스 충돌 문제이고, tailwind-merge 와 cva 가 해결해.

⚠️ 클래스 충돌 문제: tailwind-merge

🎯 이 섹션을 읽고 나면:

왜 문자열 연결(+ 또는 템플릿 리터럴)로 클래스를 합치면 위험한지 원리로 이해한다

twMerge 가 CSS 캐스케이딩을 어떻게 제어하는지 알 수 있다

cn() 헬퍼 유틸리티를 팀 공통 유틸로 등록하는 패턴을 익힌다

🦁 영호: "영철 님, 방금 만든 버튼 컴포넌트에서 px-3 이 적용이 안 되는 거 보이죠? 원인은 Tailwind 클래스 충돌이에요. tailwind-merge 를 쓰면 간단하게 해결돼요."

tailwind-merge 는 중복되는 Tailwind 클래스를 지능적으로 병합해주는 라이브러리야. 단순히 문자열을 붙이는 게 아니라, Tailwind 클래스들이 서로 같은 CSS 속성을 제어하는지 파악하고 마지막에 오는 클래스를 우선시해줘.

npm install tailwind-merge

설치 후, 동작 원리를 코드로 직접 확인해봐:

import { twMerge } from 'tailwind-merge';
 
// ❌ 일반 문자열 합치기 — px 충돌 발생, 어느 쪽이 적용될지 예측 불가
const badResult = `px-6 py-3 ${className}`;  // → "px-6 py-3 px-3 py-1"
 
// ✅ twMerge — 동일 CSS 속성 제어 클래스 중 마지막 값이 이김
twMerge('bg-blue-500', 'bg-red-500')    // → "bg-red-500" (bg 충돌 → 뒤가 이김)
twMerge('p-4', 'px-6')                  // → "p-4 px-6"  (p 와 px 는 서로 다른 속성!)
twMerge('p-4', 'p-6')                   // → "p-6"       (p 충돌 → 뒤가 이김)
twMerge('font-bold text-sm', 'text-lg') // → "font-bold text-lg" (text 충돌 → 뒤가 이김)

이제 Button 컴포넌트에 적용하면:

import { twMerge } from 'tailwind-merge';
 
// ✅ className 오버라이드가 안전하게 동작!
function Button({ className, children }: { className?: string; children: React.ReactNode }) {
  return (
    <button className={twMerge(
      'bg-blue-600 text-white px-6 py-3 rounded-xl font-semibold', // 기본값
      className  // 🦁 영호: "이 쪽이 뒤에 오니까, 기본값을 깔끔하게 오버라이드해요."
    )}>
      {children}
    </button>
  );
}
 
// 사용
<Button className="px-3 py-1.5 text-sm">작은 버튼</Button>
// 결과: "bg-blue-600 text-white rounded-xl font-semibold px-3 py-1.5 text-sm"
// px-6 → px-3, py-3 → py-1.5 로 오버라이드 성공!

🎨 변형(Variant) 기반 컴포넌트: cva

cva (class-variance-authority) 는 컴포넌트의 다양한 변형(variant, size 등)을 타입 안전하게 관리하는 라이브러리야. tailwind-merge 가 "클래스 충돌을 해결" 한다면, cva 는 "변형 조합을 구조화" 해.

영철이가 tailwind-merge 를 배운 뒤 이렇게 만들었어:

// 🐣 영철 2안: twMerge 는 쓰지만, 변형 처리가 또 지저분해짐
function Button({ variant, size, className, children }) {
  const variantClass = variant === 'secondary' ? 'bg-gray-100 text-gray-700'
                     : variant === 'danger'    ? 'bg-red-600 text-white'
                     : 'bg-blue-600 text-white'; // default: primary
  const sizeClass = size === 'sm' ? 'px-3 py-1.5 text-sm'
                  : size === 'lg' ? 'px-6 py-3 text-base'
                  : 'px-5 py-2.5 text-sm'; // default: md
  return (
    <button className={twMerge(variantClass, sizeClass, className)}>
      {children}
    </button>
  );
}

🦁 영호: "variant 가 5개, size 가 4개 되면 if-else 체인이 20개가 돼요. TypeScript 자동완성도 안 되고요. 이걸 cva 로 선언형으로 정의하면 코드도 줄고 타입도 생겨요."

npm install class-variance-authority

기본 구조

import { cva, type VariantProps } from 'class-variance-authority';
 
const buttonVariants = cva(
  // 1. 기본 클래스 (항상 적용)
  'inline-flex items-center justify-center rounded-xl font-semibold transition-all duration-200 focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
  {
    variants: {
      // 2. 변형 정의
      variant: {
        primary:   'bg-blue-600 text-white hover:bg-blue-700 focus-visible:ring-blue-500',
        secondary: 'bg-gray-100 text-gray-700 hover:bg-gray-200 focus-visible:ring-gray-400',
        danger:    'bg-red-600 text-white hover:bg-red-700 focus-visible:ring-red-500',
        ghost:     'text-gray-600 hover:bg-gray-100 focus-visible:ring-gray-400',
        link:      'text-blue-600 underline-offset-4 hover:underline focus-visible:ring-blue-500',
      },
      size: {
        sm:   'h-8 px-3 text-sm gap-1.5',
        md:   'h-10 px-5 text-sm gap-2',
        lg:   'h-12 px-6 text-base gap-2.5',
        icon: 'h-10 w-10 p-0',
      },
    },
    // 3. 기본값
    defaultVariants: {
      variant: 'primary',
      size: 'md',
    },
  }
);

cva 기반 Button 컴포넌트

import { cva, type VariantProps } from 'class-variance-authority';
import { twMerge } from 'tailwind-merge';
 
const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-xl font-semibold transition-all duration-200 active:scale-95 focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
  {
    variants: {
      variant: {
        primary:   'bg-blue-600 text-white hover:bg-blue-700 focus-visible:ring-blue-500',
        secondary: 'bg-gray-100 text-gray-700 hover:bg-gray-200 focus-visible:ring-gray-400',
        danger:    'bg-red-600 text-white hover:bg-red-700 focus-visible:ring-red-500',
        ghost:     'text-gray-600 hover:bg-gray-100 focus-visible:ring-gray-400',
      },
      size: {
        sm: 'h-8 px-3 text-xs gap-1.5',
        md: 'h-10 px-5 text-sm gap-2',
        lg: 'h-12 px-6 text-base gap-2.5',
      },
    },
    defaultVariants: {
      variant: 'primary',
      size: 'md',
    },
  }
);
 
// VariantProps 로 타입 자동 추론!
type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
  VariantProps<typeof buttonVariants> & {
    loading?: boolean;
  };
 
export function Button({ variant, size, loading, className, children, ...props }: ButtonProps) {
  return (
    <button
      disabled={loading || props.disabled}
      className={twMerge(buttonVariants({ variant, size }), className)}
      {...props}
    >
      {loading && (
        <span className="h-4 w-4 animate-spin rounded-full border-2 border-current border-t-transparent" />
      )}
      {children}
    </button>
  );
}
 
// 사용 예 — 타입 자동완성이 됨!
<Button>기본 버튼</Button>
<Button variant="secondary">보조 버튼</Button>
<Button variant="danger" size="lg">삭제 버튼 (크게)</Button>
<Button variant="ghost" size="sm">텍스트 버튼 (작게)</Button>
<Button loading>제출 중...</Button>
<Button className="w-full">너비 꽉 채우기 (twMerge 로 안전하게)</Button>

🔗 cva + tailwind-merge 조합 (최강 패턴)

cn() 유틸리티 함수 (업계 표준)

shadcn/ui 를 비롯한 대부분의 현대 React 컴포넌트 라이브러리에서 사용하는 패턴이야.

// lib/utils.ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';
 
// cn = clsx + tailwind-merge
// clsx: 조건부 클래스 병합 (object/array 형태도 지원)
// twMerge: Tailwind 클래스 충돌 해결
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

npm install clsx tailwind-merge

cn() 사용 예

import { cn } from '@/lib/utils';
 
// 조건부 클래스 + 충돌 해결을 한 번에!
<div className={cn(
  'base-class',
  isActive && 'active-class',
  isDisabled && 'disabled-class',
  className  // 오버라이드 클래스
)} />
 
// 실전: 탭 버튼 컴포넌트
function Tab({ active, children, onClick }: Props) {
  return (
    <button
      onClick={onClick}
      className={cn(
        'border-b-2 px-4 py-2 text-sm font-medium transition-colors',
        active
          ? 'border-blue-600 text-blue-600'
          : 'border-transparent text-gray-500 hover:border-gray-300 hover:text-gray-700'
      )}
    >
      {children}
    </button>
  );
}

💻 실전: 영수네 커뮤니티 컴포넌트 라이브러리

Badge 컴포넌트

// components/Badge.tsx
const badgeVariants = cva(
  'inline-flex items-center rounded-full px-3 py-0.5 text-xs font-semibold',
  {
    variants: {
      variant: {
        default: 'bg-gray-100 text-gray-700',
        primary: 'bg-blue-100 text-blue-700',
        success: 'bg-green-100 text-green-700',
        warning: 'bg-amber-100 text-amber-700',
        danger:  'bg-red-100 text-red-700',
        purple:  'bg-purple-100 text-purple-700',
      },
    },
    defaultVariants: { variant: 'default' },
  }
);
 
export function Badge({ variant, className, children }: VariantProps<typeof badgeVariants> & { className?: string; children: React.ReactNode }) {
  return (
    <span className={cn(badgeVariants({ variant }), className)}>
      {children}
    </span>
  );
}
 
// 사용
<Badge>기본</Badge>
<Badge variant="primary">React</Badge>
<Badge variant="success">모집 중</Badge>
<Badge variant="danger">마감</Badge>

Input 컴포넌트

// components/Input.tsx
const inputVariants = cva(
  'block w-full rounded-lg border text-sm placeholder:text-gray-400 transition-colors focus:outline-none focus:ring-2',
  {
    variants: {
      variant: {
        default: 'border-gray-300 focus:border-blue-500 focus:ring-blue-500/20',
        error:   'border-red-400 focus:border-red-500 focus:ring-red-500/20',
        success: 'border-green-400 focus:border-green-500 focus:ring-green-500/20',
      },
      size: {
        sm: 'px-3 py-2',
        md: 'px-4 py-2.5',
        lg: 'px-4 py-3 text-base',
      },
    },
    defaultVariants: { variant: 'default', size: 'md' },
  }
);
 
type InputProps = React.InputHTMLAttributes<HTMLInputElement> &
  VariantProps<typeof inputVariants> & {
    label?: string;
    error?: string;
    hint?: string;
  };
 
export function Input({ label, error, hint, variant, size, className, id, ...props }: InputProps) {
  const inputId = id ?? label?.toLowerCase().replace(/\s/g, '-');
  const resolvedVariant = error ? 'error' : variant;
 
  return (
    <div className="flex flex-col gap-1.5">
      {label && (
        <label htmlFor={inputId} className="text-sm font-medium text-gray-700">
          {label}
        </label>
      )}
      <input
        id={inputId}
        className={cn(inputVariants({ variant: resolvedVariant, size }), className)}
        {...props}
      />
      {error && <p className="text-xs text-red-500">{error}</p>}
      {!error && hint && <p className="text-xs text-gray-400">{hint}</p>}
    </div>
  );
}
 
// 사용
<Input label="이메일" type="email" placeholder="you@example.com" />
<Input label="비밀번호" type="password" error="8자 이상 입력해주세요" />
<Input label="닉네임" hint="한글 또는 영문 2~20자" />

🏁 이번에 배운 내용 총정리

도구	역할	언제 사용
`tailwind-merge`	클래스 충돌 해결	className 오버라이드 시 항상
`cva`	변형 기반 컴포넌트	여러 variant 가 있는 컴포넌트
`clsx`	조건부 클래스 병합	`isActive && 'class'` 패턴
`cn()`	clsx + twMerge 조합	모든 컴포넌트 className 처리

📝 마무리 퀴즈

Q1. twMerge('p-4 bg-blue-500', 'p-6 bg-red-500') 의 결과는?

✅ 정답: "bg-red-500 p-6" (또는 "p-6 bg-red-500" — 순서는 구현에 따름)

💡 상세 해설:

tailwind-merge 는 같은 CSS 속성을 대상으로 하는 Tailwind 클래스 중 나중에 오는 값이 이기도록 처리해.
p-4 와 p-6 은 모두 padding 을 대상으로 하므로 나중 값인 p-6 만 남아.
bg-blue-500 과 bg-red-500 은 모두 background-color 를 대상으로 하므로 나중 값인 bg-red-500 만 남아.
이게 바로 className 오버라이드를 안전하게 만드는 원리야.
📌 핵심 기억법: "twMerge 는 같은 CSS 속성 클래스 충돌 시 나중이 이긴다."

Q2. cva 의 defaultVariants 설정이 없으면 어떤 문제가 발생하는가?

✅ 정답: 변형 props 가 전달되지 않을 때 해당 변형의 클래스가 적용되지 않아 스타일이 없는 상태가 된다.

💡 상세 해설:

defaultVariants: { variant: 'primary', size: 'md' } 가 없으면, <Button> 처럼 아무 props 도 전달 안 하면 variant 클래스가 없어서 버튼이 텅 빈 스타일(기본 브라우저 스타일)로 보여.
VariantProps 타입도 defaultVariants 가 있으면 해당 prop 을 optional (variant?: ...) 로, 없으면 required (variant: ...) 로 만들어줘서 타입 수준에서도 영향이 있어.
📌 핵심 기억법: "defaultVariants = 아무것도 안 줬을 때의 기본값. 없으면 스타일도 없다."

Q3. cn() 유틸리티 함수가 clsx 와 tailwind-merge 를 모두 사용하는 이유는?

✅ 정답: clsx 는 조건부/배열/객체 형태의 클래스를 문자열로 합쳐주고, tailwind-merge 는 그 결과에서 Tailwind 클래스 충돌을 해결해준다. 두 문제를 각자 잘 해결하는 도구를 조합한 것이다.

💡 상세 해설:

clsx('base', isActive && 'active', { 'special': isSpecial }) → "base active" (조건부 처리)
twMerge('px-4', 'px-6') → "px-6" (충돌 해결)
cn = 먼저 clsx 로 조건부 클래스를 문자열로 합치고, 그 결과를 twMerge 에 넘겨서 충돌을 해결.
clsx 만 쓰면 Tailwind 충돌이 해결 안 되고, twMerge 만 쓰면 조건부 클래스 처리가 번거로워.
📌 핵심 기억법: "cn = clsx (조건부 병합) + twMerge (충돌 해결). 두 개의 짝꿍."

🐣 영철이의 퇴근 일기

cn() 함수 하나 만들어 두면 모든 컴포넌트에서 쓸 수 있다는 게 너무 편하다. 영호 님이 "이건 shadcn/ui 에서도 쓰는 패턴이에요. 업계 표준이라 팀원 누가 봐도 바로 이해해요" 라고 하셨는데, 이런 게 진짜 실무 감각이구나.

cva 로 Button 컴포넌트 만들 때 TypeScript 자동완성이 착착 되는 게 신기했다. variant="danger" 라고 타이핑하면 자동으로 선택지가 나오고, 없는 variant 쓰면 타입 에러가 나고. 이게 타입 안전한 컴포넌트의 진짜 의미구나 싶었다.

💡 오늘의 교훈: "재사용 컴포넌트의 핵심은 '열린 확장, 닫힌 수정'. cva 로 variant 를 잘 설계하면 새 스타일이 필요해도 기존 코드를 건드리지 않아도 된다."

이번 주 안에 영수네 커뮤니티 컴포넌트 라이브러리 파일 하나에 Button, Badge, Input 다 모아서 영호 님한테 PR 올려봐야겠다. 내일 아침 일찍 출근해서 시작하자. 오늘 저녁은 일찍 자야지! 💤

🧩 Tailwind 11장: 컴포넌트 패턴과 재사용 설계

📋 목차

📌 이 문서를 읽기 전에

🤔 왜 알아야 하는가

⚠️ 클래스 충돌 문제: tailwind-merge

🎨 변형(Variant) 기반 컴포넌트: cva

기본 구조

cva 기반 Button 컴포넌트

🔗 cva + tailwind-merge 조합 (최강 패턴)

cn() 유틸리티 함수 (업계 표준)

cn() 사용 예

💻 실전: 영수네 커뮤니티 컴포넌트 라이브러리

Badge 컴포넌트

Input 컴포넌트

🏁 이번에 배운 내용 총정리

📝 마무리 퀴즈

🐣 영철이의 퇴근 일기

🔗 더 알아보기