Tailwind CSS 유틸리티 규칙

18.2.1. 클래스 순서 규칙

유틸리티 클래스는 다음 순서로 작성해야 합니다.

순서	카테고리	예시
1	레이아웃	flex, grid, block, hidden, relative, absolute
2	박스 모델	w-, h-, p-, m-, gap-, border-
3	타이포그래피	text-, font-, leading-, tracking-
4	시각 효과	bg-, text-{color}, shadow-, opacity-, rounded-
5	기타	transition-, cursor-, hover:, focus:

수동으로 순서를 관리하지 않습니다. prettier-plugin-tailwindcss를 설치하여 자동 정렬해야 합니다.

npm install -D prettier-plugin-tailwindcss

.prettierrc에 플러그인을 등록합니다.

{
  "plugins": ["prettier-plugin-tailwindcss"]
}

• 이 플러그인은 Tailwind CSS 공식 권장 순서에 따라 클래스를 자동 정렬합니다.
• 저장 시 자동 포매팅이 적용되므로 개발자가 순서를 암기할 필요가 없습니다.
• CI 파이프라인에서 Prettier 검사를 수행하여 정렬되지 않은 클래스를 차단해야 합니다.

---

18.2.2. @apply 사용 기준

@apply는 동일한 클래스 조합이 3회 이상 반복될 때만 허용합니다.

/* 허용: 여러 곳에서 반복 사용되는 버튼 기본 스타일 */
@layer components {
  .btn-primary {
    @apply inline-flex items-center justify-center rounded-md bg-brand-600
           px-4 py-2 text-sm font-medium text-white
           hover:bg-brand-700 focus:outline-none focus:ring-2;
  }
}

/* 금지: 한두 곳에서만 사용되는 스타일 */
@layer components {
  .my-special-card {
    @apply mt-4 rounded-lg p-6;
  }
}

• @apply를 과도하게 사용하면 Tailwind의 유틸리티 퍼스트 원칙이 훼손됩니다.
• 반복 횟수가 3회 미만이면 템플릿에 유틸리티 클래스를 직접 작성합니다.
• @apply로 추출한 클래스는 반드시 @layer components 내부에 정의합니다.

---

18.2.3. 커스텀 유틸리티

프로젝트 고유 디자인 토큰은 tailwind.config.ts의 theme.extend에서 정의합니다.

// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#f0f5ff',
          500: '#3b82f6',
          600: '#2563eb',
          700: '#1d4ed8',
        },
        success: '#16a34a',
        warning: '#f59e0b',
        error: '#dc2626',
      },
      spacing: {
        '4.5': '1.125rem',
        '13': '3.25rem',
        '15': '3.75rem',
      },
      borderRadius: {
        '4xl': '2rem',
      },
    },
  },
} satisfies Config

• 디자인 시스템에서 정의한 색상, 간격, 폰트 등을 theme.extend에 등록합니다.
• 임의 값([32px], [#ff0000])은 사용하지 않습니다. 반복되는 값은 설정 파일에 등록해야 합니다.
• 1회성 예외 값은 임의 값 문법을 허용하되, 코드 리뷰에서 설정 파일 등록 여부를 검토합니다.

---

18.2.4. 인라인 스타일 금지

Vue 템플릿에서 style 바인딩을 사용하지 않습니다. Tailwind 유틸리티 클래스로 대체해야 합니다.

<!-- 금지: 인라인 스타일 -->
<div :style="{ padding: '16px', backgroundColor: '#f5f5f5' }">
  내용
</div>

<!-- 올바른 예: Tailwind 유틸리티 -->
<div class="bg-gray-100 p-4">
  내용
</div>

예외 허용 조건

다음 경우에 한하여 :style 바인딩을 허용합니다.

• 런타임에 계산되는 동적 값 (예: 사용자 입력 기반 너비, 드래그 위치)
• CSS 변수를 동적으로 설정해야 하는 경우

<!-- 예외 허용: 런타임 동적 계산 값 -->
<div
  class="absolute rounded-lg bg-white shadow-md"
  :style="{ top: `${popoverY}px`, left: `${popoverX}px` }"
>
  팝오버 내용
</div>

• 예외 사용 시 코드 리뷰에서 Tailwind 유틸리티로 대체 가능 여부를 반드시 검토합니다.
• 색상, 폰트, 간격 등 디자인 토큰에 해당하는 값은 인라인 스타일로 지정하지 않습니다.