tailwind-variants로 Button·Card 컴포넌트의 variant 체계를 선언적으로 구축하는 법 — Slots, extend, compoundVariants 활용

import { tv } from "tailwind-variants";
 
const button = tv({
  // 1. base: 어떤 variant든 항상 적용되는 공통 클래스
  base: "font-semibold rounded-full px-4 py-1 text-sm active:opacity-80",
 
  // 2. variants: 각 variant 키와 선택 가능한 값들
  variants: {
    color: {
      primary: "bg-blue-500 text-white hover:bg-blue-700",
      secondary: "bg-purple-500 text-white hover:bg-purple-700",
      ghost: "bg-transparent text-gray-700 border border-gray-300",
    },
    size: {
      sm: "text-xs px-2 py-0.5",
      md: "text-sm px-4 py-1",
      lg: "text-base px-6 py-2",
    },
    // boolean variant: 키를 true/false로 선언하면 논리값으로 제어됩니다
    disabled: {
      true: "opacity-50 pointer-events-none",
    },
  },
 
  // 3. compoundVariants: 특정 variant 조합일 때만 적용
  compoundVariants: [
    {
      color: "primary",
      disabled: true,
      class: "bg-blue-200",
    },
  ],
 
  // 4. defaultVariants: 기본값 지정
  defaultVariants: {
    color: "primary",
    size: "md",
  },
});
 
// 클래스 문자열을 반환합니다
button({ color: "secondary", size: "lg" });

import { tv, type VariantProps } from "tailwind-variants";
 
const card = tv({
  slots: {
    root: "rounded-xl border bg-white overflow-hidden transition-shadow",
    header: "px-6 py-4 border-b font-semibold text-gray-900",
    body: "px-6 py-4 text-gray-700",
    footer: "px-6 py-4 border-t bg-gray-50",
  },
  variants: {
    size: {
      sm: { root: "max-w-sm", header: "text-sm py-3", body: "text-xs" },
      md: { root: "max-w-md", header: "text-base", body: "text-sm" },
      lg: { root: "max-w-lg", header: "text-lg py-5", body: "text-base" },
    },
    variant: {
      elevated: { root: "shadow-md hover:shadow-xl" },
      outlined: { root: "border-2 border-blue-200 shadow-none" },
      flat: { root: "shadow-none border-transparent bg-gray-50" },
    },
  },
  // elevated + lg 조합일 때만 헤더에 추가 강조 스타일
  compoundVariants: [
    {
      variant: "elevated",
      size: "lg",
      class: { header: "text-xl font-bold" },
    },
  ],
  defaultVariants: {
    size: "md",
    variant: "elevated",
  },
});
 
// tv()의 반환 타입에서 variant props 타입을 추출합니다
type CardVariants = VariantProps<typeof card>;
 
type CardProps = CardVariants & {
  title: string;
  children: React.ReactNode;
  footerContent?: React.ReactNode;
  className?: string;
};
 
function Card({ size, variant, title, children, footerContent, className }: CardProps) {
  const { root, header, body, footer } = card({ size, variant });
 
  return (
    // 슬롯 함수 호출 시 추가 클래스를 인자로 넘길 수 있습니다
    <div className={root({ class: className })}>
      <div className={header()}>{title}</div>
      <div className={body()}>{children}</div>
      {footerContent && <div className={footer()}>{footerContent}</div>}
    </div>
  );
}

import { tv, type VariantProps } from "tailwind-variants";
 
// Base: 모든 버튼 공통 스타일
const button = tv({
  base: "font-semibold rounded-lg px-4 py-2 transition-colors focus-visible:outline-none focus-visible:ring-2",
  variants: {
    color: {
      primary: "bg-blue-500 text-white hover:bg-blue-600",
      danger: "bg-red-500 text-white hover:bg-red-600",
      ghost: "bg-transparent text-gray-700 border border-gray-300 hover:bg-gray-50",
    },
    size: {
      sm: "text-xs px-3 py-1.5",
      md: "text-sm px-4 py-2",
      lg: "text-base px-6 py-3",
    },
    // boolean variant: disabled 상태를 true 키로 제어합니다
    disabled: {
      true: "opacity-50 pointer-events-none cursor-not-allowed",
    },
  },
  defaultVariants: { color: "primary", size: "md" },
});
 
// IconButton: button을 확장 — color, size, disabled는 모두 상속됩니다
const iconButton = tv({
  extend: button,
  base: "inline-flex items-center gap-2",
  variants: {
    iconPosition: {
      left: "flex-row",
      right: "flex-row-reverse",
    },
    // boolean variant: 아이콘만 있을 때 패딩을 재정의합니다
    iconOnly: {
      true: "px-2 aspect-square",
    },
  },
});
 
type ButtonProps = VariantProps<typeof button>;
type IconButtonProps = VariantProps<typeof iconButton>;
 
// button의 color, size와 iconButton의 iconPosition 모두 사용 가능합니다
iconButton({ color: "primary", size: "lg", iconPosition: "left" });
iconButton({ color: "danger", iconOnly: true, size: "sm" });

import { createTV } from "tailwind-variants";
 
// 반응형 variant 객체 문법을 사용하려면 createTV로 옵션을 활성화해야 합니다
const tv = createTV({
  responsiveVariants: true,
});
 
const grid = tv({
  base: "grid gap-4",
  variants: {
    cols: {
      1: "grid-cols-1",
      2: "grid-cols-2",
      3: "grid-cols-3",
      4: "grid-cols-4",
    },
  },
});
 
// 반응형: 모바일 1열 → 태블릿 2열 → 데스크톱 3열
grid({ cols: { initial: "1", sm: "1", md: "2", lg: "3" } });
// → "grid gap-4 grid-cols-1 sm:grid-cols-1 md:grid-cols-2 lg:grid-cols-3"

/* globals.css — Tailwind v4 */
@import "tailwindcss";
 
@theme {
  /* Base 토큰: 원시값 */
  --color-blue-500: #3b82f6;
 
  /* Semantic 토큰: 목적 기반 */
  --color-brand-primary: var(--color-blue-500);
  --color-brand-danger: var(--color-red-500);
}

const button = tv({
  base: "font-semibold rounded-lg px-4 py-2",
  variants: {
    intent: {
      // CSS 변수 기반 임의값(arbitrary value) 문법으로 시맨틱 토큰을 참조합니다
      brand: "bg-[--color-brand-primary] text-white",
      danger: "bg-[--color-brand-danger] text-white",
    },
  },
});