2nd/10_Wiki/Topics/Coding/Frontend_Tailwind_Architecture.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
frontend-tailwind-architecture	Tailwind CSS — 디자인 토큰 / 컴포넌트 / 조직	Coding	draft	B	conceptual	2026-05-09	2026-05-09	frontend tailwind css design-tokens vibe-coding	language applicable_to TS / CSS / Tailwind Web		tailwind utility-first cva tw-merge design system

Tailwind Architecture

Utility-first. className spam 이 아닌 컴포넌트 추출 + cva 변형. tailwind.config.ts 의 theme 가 디자인 시스템. v4 = CSS-first config.

📖 핵심 개념

• Utility-first: 미리 만든 작은 클래스 조합.
• Theme: 색 / 크기 / 폰트 = 디자인 토큰.
• cva: variants + compoundVariants 로 component variant 정의.
• tw-merge: 충돌하는 클래스 (p-2 p-4) 자동 정리.

💻 코드 패턴

theme = 디자인 토큰 (v3)

// tailwind.config.ts
import type { Config } from 'tailwindcss';

export default {
  content: ['./src/**/*.{ts,tsx}'],
  theme: {
    extend: {
      colors: {
        brand: { 50: '#eff6ff', 500: '#3b82f6', 900: '#1e3a8a' },
        surface: 'hsl(var(--surface))', // CSS var = dark mode 쉬움
      },
      borderRadius: { sm: '4px', md: '8px', lg: '16px' },
      fontFamily: { sans: ['Inter', 'system-ui'] },
      spacing: { 18: '4.5rem' },
    },
  },
  plugins: [require('@tailwindcss/forms')],
} satisfies Config;

v4 — CSS-first

/* app.css */
@import "tailwindcss";

@theme {
  --color-brand-500: #3b82f6;
  --radius-md: 8px;
  --font-sans: Inter, system-ui;
}

Component with cva

import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/cn';

const button = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition focus-visible:ring-2',
  {
    variants: {
      variant: {
        primary: 'bg-brand-500 text-white hover:bg-brand-600',
        secondary: 'bg-surface text-foreground hover:bg-muted',
        ghost: 'hover:bg-muted',
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4',
        lg: 'h-12 px-6 text-lg',
      },
      fullWidth: { true: 'w-full' },
    },
    defaultVariants: { variant: 'primary', size: 'md' },
  }
);

type Props = React.ButtonHTMLAttributes<HTMLButtonElement> & VariantProps<typeof button>;

export function Button({ className, variant, size, fullWidth, ...rest }: Props) {
  return <button className={cn(button({ variant, size, fullWidth }), className)} {...rest} />;
}

cn helper

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

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

Dark mode (CSS var)

/* root */
:root {
  --surface: 0 0% 100%;
  --foreground: 222 47% 11%;
}
.dark {
  --surface: 222 47% 11%;
  --foreground: 0 0% 100%;
}

// theme.ts
colors: {
  surface: 'hsl(var(--surface) / <alpha-value>)',
  foreground: 'hsl(var(--foreground) / <alpha-value>)',
}

Repsonsive + state

<div className="text-sm md:text-base hover:bg-muted dark:hover:bg-muted/50">

Plugin (custom utility)

// tailwind.config.ts
plugins: [
  plugin(({ addUtilities }) => {
    addUtilities({
      '.no-scrollbar::-webkit-scrollbar': { display: 'none' },
      '.no-scrollbar': { 'scrollbar-width': 'none' },
    });
  }),
],

🤔 의사결정 기준

상황	패턴
작은 1회용	inline className
반복 변형 (button, badge)	cva component
디자인 토큰 통일	theme.extend
다크 모드	CSS var + class strategy
외부 라이브러리 (Radix)	data-* selector + Tailwind
거대 제품 디자인 시스템	shadcn/ui + cva

❌ 안티패턴

• className="text-red-500 bg-blue-200 ..." 30개: 컴포넌트 추출.
• 인라인 magic value (mt-[17px]): 토큰화 또는 spacing extend.
• JIT 안 적용 path: content 에 모든 src 포함.
• !important (!text-red) 남발: cn + variant 우선순위로.
• dark mode 매 클래스 dark:`: CSS var 가 깨끗.
• theme 색 random: red-500, red-600, red-700 정해진 stops 만.
• cva 없이 거대 ternary: 가독성 0.

🤖 LLM 활용 힌트

• cva + cn + tw-merge 3종.
• theme.extend = design token.
• shadcn/ui 가 좋은 reference.

🔗 관련 문서

• Frontend_Design_Tokens