React Tailwind className 정리: 조건부·variant·가독성 기준

• 긴 className이 정상인 경우
• 짧은 조건을 JSX 안에 두는 기준
• 반복 조합을 상수와 객체로 분리하기
• UI 의미가 생기면 컴포넌트로 분리하기
• disabled·hover·focus 상태 정확히 처리하기
• clsx와 tailwind-merge 역할 구분하기
• variant가 커질 때 CVA 적용하기
• 상황별 선택표와 리뷰 체크리스트

긴 className이 정상인 경우

Tailwind는 작은 utility를 markup에서 조합하므로 className이 길어지는 것이 자연스럽습니다. 길이만 줄이려고 의미 없는 상수나 CSS 파일로 옮기면 화면과 스타일을 함께 읽기 어려워질 수 있습니다. 중요한 질문은 글자 수가 아니라 수정할 때 어떤 클래스가 어떤 책임인지 한 번에 판단되는가입니다.

function PageHeader() {
  return (
    <header className='mx-auto flex max-w-5xl flex-col gap-6 rounded-2xl border border-slate-200 bg-white p-6 shadow-sm md:flex-row md:items-center md:justify-between'>
      <div>
        <p className='text-sm font-medium text-blue-600'>Dashboard</p>
        <h1 className='mt-1 text-2xl font-bold text-slate-950'>주문 관리</h1>
      </div>
      <button className='rounded-lg bg-blue-600 px-4 py-2 text-sm font-semibold text-white hover:bg-blue-700 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600'>
        새 주문 등록
      </button>
    </header>
  );
}

이 컴포넌트가 한 번만 쓰이고 모든 utility가 한 요소의 레이아웃과 시각 상태를 설명한다면 굳이 분리하지 않아도 됩니다. 반대로 같은 헤더 조합이 여러 페이지에서 복사되거나, 조건이 겹쳐 어느 색상이 적용되는지 추적하기 어렵다면 구조를 나눌 시점입니다.

그대로 둘 신호	분리를 검토할 신호
한 요소에서만 사용되고 조건이 없음	같은 클래스 묶음이 여러 곳에 복사됨
markup과 스타일을 함께 보면 의도가 선명함	조건·variant·size가 한 문자열에서 교차함
수정 범위가 해당 컴포넌트에만 한정됨	여러 화면이 같은 UI 규칙을 공유함
외부 className override가 필요 없음	소비자가 기본 스타일을 안전하게 확장해야 함

짧은 조건을 JSX 안에 두는 기준

active 하나에 따라 두 완성 클래스 묶음 중 하나를 고르는 정도라면 JSX의 삼항식이 가장 직접적입니다. 별도 파일과 추상화를 찾지 않아도 상태와 결과를 한자리에서 볼 수 있습니다.

type FilterButtonProps = {
  active: boolean;
  children: React.ReactNode;
};

function FilterButton({ active, children }: FilterButtonProps) {
  return (
    <button
      type='button'
      aria-pressed={active}
      className={`rounded-full px-4 py-2 text-sm font-medium transition-colors ${
        active
          ? 'bg-slate-900 text-white'
          : 'bg-slate-100 text-slate-700 hover:bg-slate-200'
      }`}
    >
      {children}
    </button>
  );
}

두 후보가 bg-slate-900, bg-slate-100처럼 소스에 완성된 문자열로 남아 있으므로 Tailwind의 감지에도 안전합니다. bg-${color}-500처럼 조각을 조립하면 다른 문제입니다. 그 경우에는 Tailwind 동적 클래스와 @source 사용법의 정적 매핑 기준을 적용합니다.

반복 조합을 상수와 객체로 분리하기

공통 모양과 목적별 색상 조합이 반복되면 상수와 variant 객체로 나눕니다. 목표는 줄 수를 줄이는 것이 아니라 base, variant, size, state의 수정 책임을 분리하는 것입니다.

const buttonBase =
  'inline-flex items-center justify-center rounded-lg font-semibold transition-colors focus-visible:outline-2 focus-visible:outline-offset-2';

const buttonClassByVariant = {
  primary: 'bg-blue-600 text-white hover:bg-blue-700 focus-visible:outline-blue-600',
  secondary: 'border border-slate-300 bg-white text-slate-800 hover:bg-slate-50 focus-visible:outline-slate-500',
  danger: 'bg-red-600 text-white hover:bg-red-700 focus-visible:outline-red-600',
} as const;

const buttonClassBySize = {
  sm: 'h-8 px-3 text-xs',
  md: 'h-10 px-4 text-sm',
  lg: 'h-12 px-5 text-base',
} as const;

type ButtonVariant = keyof typeof buttonClassByVariant;
type ButtonSize = keyof typeof buttonClassBySize;

이름에는 구현보다 역할을 드러냅니다. blueButton보다 primary, redButton보다 danger가 디자인 변화에 강합니다. 색상이 바뀌어도 호출부의 의미가 유지되기 때문입니다.

UI 의미가 생기면 컴포넌트로 분리하기

상수만으로는 접근성 속성, loading UI, 이벤트, ref, HTML button 속성을 반복하게 됩니다. 이때는 재사용 컴포넌트의 API를 정의합니다. variant는 목적, size는 크기, fullWidth는 레이아웃, loading은 진행 상태를 담당하도록 경계를 잡습니다.

import type { ButtonHTMLAttributes } from 'react';

type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
  variant?: ButtonVariant;
  size?: ButtonSize;
  fullWidth?: boolean;
  loading?: boolean;
};

function Button({
  variant = 'primary',
  size = 'md',
  fullWidth = false,
  loading = false,
  disabled = false,
  children,
  ...props
}: ButtonProps) {
  const isDisabled = disabled || loading;

  const className = [
    buttonBase,
    buttonClassByVariant[variant],
    buttonClassBySize[size],
    fullWidth && 'w-full',
    isDisabled && 'cursor-not-allowed opacity-50',
  ]
    .filter(Boolean)
    .join(' ');

  return (
    <button {...props} disabled={isDisabled} className={className}>
      {loading ? '처리 중' : children}
    </button>
  );
}

이 정도 규모에서는 배열 조합만으로 충분합니다. 다만 filter(Boolean).join(' ')은 false 값을 제거하고 문자열을 이어 붙일 뿐, px-2 px-4나 bg-blue-600 bg-red-600 같은 충돌을 판단하지 않습니다. 또한 위 예제는 외부 className override를 받지 않아 컴포넌트가 자체 variant를 완전히 통제합니다.

컴포넌트 분리 기준이 아직 모호하다면 React 컴포넌트 기본 구조에서 props와 재사용 경계를 함께 확인하는 편이 좋습니다.

disabled·hover·focus 상태 정확히 처리하기

비활성 버튼은 흐리게 보이는 것만으로 충분하지 않습니다. 실제 HTML disabled 속성으로 상호작용과 폼 동작을 막고, Tailwind 상태 variant로 시각 피드백을 맞춥니다. 키보드 사용자를 위해 활성 상태의 focus-visible도 유지합니다.

type SubmitButtonProps = {
  disabled?: boolean;
  children: React.ReactNode;
};

function SubmitButton({ disabled = false, children }: SubmitButtonProps) {
  return (
    <button
      type='submit'
      disabled={disabled}
      className='rounded-lg bg-blue-600 px-4 py-2 font-semibold text-white transition-colors hover:bg-blue-700 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600 disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:bg-blue-600'
    >
      {children}
    </button>
  );
}

상태가 복잡해지면 hover 클래스를 조건부로 분리할 수도 있습니다. 핵심은 스타일 문자열만 바꾸지 말고 실제 DOM 상태와 접근성 의미를 일치시키는 것입니다. 부모·형제 상태까지 연결해야 한다면 Tailwind group·peer·has 선택 기준을 함께 봅니다.

clsx와 tailwind-merge 역할 구분하기

clsx: 조건에 따라 문자열 조합

clsx는 문자열·배열·객체·false 값을 읽어 className을 조합합니다. 배열 join보다 호출부를 간결하게 만들지만 Tailwind utility 충돌을 해결하지는 않습니다.

import { clsx } from 'clsx';

function Alert({
  error,
  compact,
}: {
  error: boolean;
  compact: boolean;
}) {
  return (
    <div
      className={clsx(
        'rounded-lg border',
        compact ? 'p-2 text-sm' : 'p-4 text-base',
        error
          ? 'border-red-200 bg-red-50 text-red-900'
          : 'border-blue-200 bg-blue-50 text-blue-900',
      )}
    >
      알림 내용
    </div>
  );
}

tailwind-merge: 상충 utility를 아는 병합

재사용 컴포넌트의 기본 클래스와 소비자가 전달한 className을 합치면서 뒤의 Tailwind utility로 override해야 할 때 tailwind-merge를 검토합니다.

import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

cn('px-2 py-2 bg-blue-600', 'px-4 bg-red-600');
// 결과 예: py-2 px-4 bg-red-600

Tailwind 공식 문서가 설명하듯 같은 CSS 속성을 다루는 utility를 동시에 붙이지 않는 것이 기본입니다. tailwind-merge는 component composition 경계에서 의도적인 override가 필요할 때 유용하지만, 모든 내부 조합에 자동으로 붙일 필요는 없습니다. 사용자 정의 utility나 비표준 theme 규칙은 라이브러리 설정과 어긋날 수 있으므로 테스트해야 합니다.

도구	주 역할	충돌 해결	권장 시점
filter(Boolean).join(' ')	아주 단순한 조건 문자열 조합	아니요	작고 로컬인 컴포넌트
clsx	문자열·객체·배열 조건 조합	아니요	조건 표현이 반복될 때
tailwind-merge	Tailwind 상충 utility 병합	예	기본 스타일과 외부 className을 합칠 때
CVA	타입 가능한 variant API와 조합 규칙	기본적으로 아니요	디자인 시스템 수준의 variant가 생길 때

variant가 커질 때 CVA 적용하기

버튼·배지·알림처럼 intent, size, boolean 상태, 복합 규칙이 여러 사용처에서 반복되면 Class Variance Authority의 cva로 variant API를 선언할 수 있습니다. 단순 버튼 하나 때문에 바로 도입하기보다 팀이 같은 variant 표를 반복 관리하기 시작할 때 가치가 커집니다.

import type { ButtonHTMLAttributes } from 'react';
import { cva, type VariantProps } from 'class-variance-authority';

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-lg font-semibold transition-colors focus-visible:outline-2 focus-visible:outline-offset-2',
  {
    variants: {
      intent: {
        primary: 'bg-blue-600 text-white focus-visible:outline-blue-600',
        secondary: 'border border-slate-300 bg-white text-slate-800 focus-visible:outline-slate-500',
        danger: 'bg-red-600 text-white focus-visible:outline-red-600',
      },
      size: {
        sm: 'h-8 px-3 text-xs',
        md: 'h-10 px-4 text-sm',
        lg: 'h-12 px-5 text-base',
      },
      disabled: {
        true: 'cursor-not-allowed opacity-50',
        false: null,
      },
    },
    compoundVariants: [
      { intent: 'primary', disabled: false, class: 'hover:bg-blue-700' },
      { intent: 'secondary', disabled: false, class: 'hover:bg-slate-50' },
      { intent: 'danger', disabled: false, class: 'hover:bg-red-700' },
    ],
    defaultVariants: {
      intent: 'primary',
      size: 'md',
      disabled: false,
    },
  },
);

type VariantPropsOfButton = VariantProps<typeof buttonVariants>;

type ButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'disabled'> &
  VariantPropsOfButton & {
    disabled?: boolean;
  };

function Button({
  intent,
  size,
  disabled = false,
  className,
  ...props
}: ButtonProps) {
  return (
    <button
      {...props}
      disabled={disabled}
      className={cn(buttonVariants({ intent, size, disabled }), className)}
    />
  );
}

compoundVariants는 여러 조건이 동시에 맞을 때만 클래스를 붙입니다. 위 예제에서는 disabled가 아닐 때만 hover 배경을 제공합니다. 외부 className override가 제품 규칙상 필요 없다면 아예 받지 않는 API가 더 안전할 수 있습니다. CVA와 twMerge를 함께 쓰더라도 variant 이름과 허용 조합을 테스트해야 합니다.

상황별 선택표

상황	먼저 선택할 구조	이유
한 요소, 조건 없음	긴 className 그대로 유지	markup과 스타일을 한자리에서 읽기 쉬움
boolean 조건 한두 개	삼항식 또는 clsx	추상화 이동 비용이 적음
완성 클래스 묶음이 반복	상수·객체 매핑	base와 상태 수정 위치가 선명함
접근성·이벤트·상태까지 반복	재사용 컴포넌트	UI 의미와 동작을 함께 캡슐화
외부 className이 기본 스타일을 override	clsx + 선택적 tailwind-merge	조합과 충돌 해결 역할을 분리
variant·size·compound 규칙이 많음	CVA 또는 프로젝트의 기존 variant 도구	허용 조합을 선언적·타입 안전하게 관리

코드 리뷰 체크리스트

1. 긴 이유가 한 요소의 정상적인 utility 조합인지, 여러 책임이 섞인 것인지 구분합니다.
2. 조건 양쪽의 Tailwind 클래스가 완성된 정적 문자열인지 확인합니다.
3. 동시에 붙는 p-2 p-4, flex grid, 배경·텍스트 충돌이 없는지 봅니다.
4. disabled, aria-pressed, aria-expanded 같은 DOM 의미가 시각 상태와 일치하는지 확인합니다.
5. focus-visible, hover, dark, responsive 상태가 빠지지 않았는지 키보드와 실제 viewport에서 확인합니다.
6. 상수 분리가 단순 이동에 그치지 않고 base·variant·size 책임을 드러내는지 봅니다.
7. 공용 컴포넌트가 외부 className을 정말 허용해야 하는지 판단합니다.
8. tailwind-merge와 CVA가 이미 있는 프로젝트 패턴을 따르는지, 커스텀 theme에서도 테스트되는지 확인합니다.

utility를 CSS 추상화로 옮겨야 하는 상황은 Tailwind @apply·@utility·custom variant 기준에서 별도로 판단할 수 있습니다.

자주 묻는 질문

className이 몇 글자면 분리해야 하나요?

고정 길이 기준은 없습니다. 반복 여부, 상태 조합 수, 수정 책임, 컴포넌트 의미가 더 중요합니다. 한 요소의 정적 스타일이면 길어도 그대로 둘 수 있습니다.

clsx만 쓰면 tailwind-merge는 필요 없나요?

상충 utility가 없도록 API를 설계했다면 필요 없습니다. 기본 클래스와 외부 className을 의도적으로 override할 때만 병합 도구의 가치가 생깁니다.

tailwind-merge를 모든 className에 써도 되나요?

가능하다는 것과 필요한 것은 다릅니다. 충돌이 없는 내부 조합은 단순 join이 더 명확하고 추가 설정·런타임 비용도 적습니다. 컴포넌트 composition 경계에 선택적으로 둡니다.

CVA를 쓰면 Tailwind 동적 클래스 감지 문제가 사라지나요?

CVA 설정 안에 완성된 클래스 토큰을 작성하면 감지에 유리하지만, 문자열 조각을 런타임에 조립하면 같은 문제가 남습니다. 도구보다 소스에 완성 후보가 존재하는지가 핵심입니다.

공식 문서와 도구 문서

• Tailwind CSS: Styling with utility classes — 긴 utility 조합과 상충 클래스 관리 기준
• Tailwind CSS: Hover, focus, and other states — disabled·focus-visible 등 상태 variant
• Tailwind CSS: Detecting classes in source files — 완성된 정적 클래스 후보 기준
• clsx 저장소 — 조건부 className 조합 API
• tailwind-merge 사용 기준 — join과 conflict merge의 경계
• CVA Variants — variants·compoundVariants·defaultVariants 구조

정리 순서는 단순합니다. 먼저 긴 className을 그대로 읽을 수 있는지 보고, 조건이 생기면 완성된 후보를 명시합니다. 반복되는 규칙만 상수와 컴포넌트로 옮기고, 여러 variant가 제품 API가 되었을 때 도구를 도입합니다. 추상화의 수보다 수정 기준이 선명한지가 더 중요한 판단 기준입니다.