2nd/10_Wiki/Topics/AI_and_ML/유틸리티 퍼스트(Utility-first).md

---
id: wiki-2026-0508-유틸리티-퍼스트-utility-first
title: 유틸리티 퍼스트(Utility-first)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Utility-first CSS, Tailwind, Atomic CSS]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [css, tailwind, utility-first, frontend, styling]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: CSS
  framework: Tailwind/UnoCSS
---

# 유틸리티 퍼스트(Utility-first)

## 매 한 줄
> **"매 single-purpose utility class 의 의 의 의 의 — 의 stylesheet 의 의 의 markup 의 의 styling locality."**. Tailwind CSS (2017, Adam Wathan) 의 의 의 의 popularize, 매 2026 의 Tailwind v4 (Oxide engine, Rust-based, 100x faster) + UnoCSS (engine-agnostic, on-demand) 의 의. 매 atomic CSS 의 의 의 component 의 의 (의 React component) 의 의 의 의 reusability 의 의 의 의.

## 매 핵심

### 매 utility-first 의 의
- **Locality**: style 의 의 markup 의 — 의 stylesheet 의 의 의 jump 의.
- **No naming**: BEM `.card__header--featured` 의 의 의 의.
- **Constraint-based**: design token (spacing scale, color palette) 의 의 enforced.
- **Tree-shakable**: 의 사용된 utility 의 의 ship — 의 small bundle.
- **Refactor-friendly**: 의 selector specificity 의 의 — 의 confidence 의 change.

### 매 Tailwind v4 (2025-2026)
- **Oxide engine**: Rust 의 rewrite — 100x faster, 의 PostCSS plugin 의 의.
- **CSS-first config**: `@theme` directive — 의 `tailwind.config.js` 의 의.
- **Auto content detection**: 의 `content: []` config 의 의.
- **Native CSS variable**: `bg-blue-500` → `--color-blue-500` 의 의 직접 사용 의.
- **Container queries**: `@container` first-class.

### 매 응용
1. SPA / dashboard — rapid iteration.
2. Component library — Radix + Tailwind (shadcn/ui pattern).
3. Email HTML — limited CSS support 의 의 utility 의 의 의 의 의.
4. Static site — Astro + Tailwind.

## 💻 패턴

### Tailwind v4 setup (CSS-first)
```css
/* app.css */
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.7 0.15 250);
  --font-display: "Inter", sans-serif;
  --breakpoint-3xl: 1920px;
}

/* 매 의 더 ㅣ tailwind.config.js 의 의 */
```

### Component composition (React + Tailwind)
```tsx
import { cva, type VariantProps } from 'class-variance-authority';
import { twMerge } from 'tailwind-merge';

const button = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:opacity-50',
  {
    variants: {
      intent: {
        primary: 'bg-brand text-white hover:bg-brand/90',
        secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
        ghost: 'hover:bg-gray-100',
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4',
        lg: 'h-12 px-6 text-lg',
      },
    },
    defaultVariants: { intent: 'primary', size: 'md' },
  }
);

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

export function Button({ className, intent, size, ...props }: Props) {
  return <button className={twMerge(button({ intent, size }), className)} {...props} />;
}
```

### Responsive + dark mode
```html
<div class="
  flex flex-col gap-4 p-4
  md:flex-row md:gap-6 md:p-6
  lg:gap-8 lg:p-8
  bg-white dark:bg-gray-900
  text-gray-900 dark:text-gray-100
">
  ...
</div>
```

### Container queries (Tailwind v4)
```html
<div class="@container">
  <div class="grid grid-cols-1 @md:grid-cols-2 @xl:grid-cols-4 gap-4">
    <Card />  <!-- 의 viewport 의 의, container 의 의 -->
  </div>
</div>
```

### Custom utility (CSS-first)
```css
@utility scrollbar-hidden {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}

/* 매 사용 */
/* <div class="scrollbar-hidden overflow-x-scroll"> */
```

### Arbitrary value (escape hatch)
```html
<!-- 매 design token 의 의 의 의 — arbitrary -->
<div class="top-[117px] grid-cols-[1fr_2fr_1fr] bg-[oklch(0.7_0.15_250)]">
```

### `cn` helper (clsx + twMerge)
```ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

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

// 매 사용 — 의 conflicting class 의 의 right-most 의 win
<div className={cn('p-4 bg-red-500', isActive && 'bg-blue-500', className)} />
```

### UnoCSS alternative
```ts
// uno.config.ts
import { defineConfig, presetUno, presetAttributify } from 'unocss';

export default defineConfig({
  presets: [presetUno(), presetAttributify()],
  shortcuts: {
    'btn': 'inline-flex items-center px-4 py-2 rounded',
    'btn-primary': 'btn bg-blue-500 text-white hover:bg-blue-600',
  },
});
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| New project | Tailwind v4 (Oxide) + cva + tailwind-merge |
| Performance-critical | UnoCSS (on-demand, smaller runtime) |
| Design system 의 의 한 | Tailwind 의 의 — 의 design system 의 raw CSS or vanilla-extract |
| Email HTML | Tailwind email plugin (의 inline 의 의) |
| Astro / static | Tailwind + content-collections |
| Existing CSS-in-JS app | Migrate gradually — 의 새 component 의 Tailwind |

**기본값**: Tailwind v4 + cva + `cn` helper + shadcn/ui 의 component layer.

## 🔗 Graph
- 변형: [[Tailwind CSS]] · [[Atomic_CSS]]
- 응용: [[shadcn/ui]] · [[Design_System]] · [[Component_Library]]
- Adjacent: [[CSS in JS]] · [[CSS Modules]] · [[CVA]]

## 🤖 LLM 활용
**언제**: utility class lookup, component refactor, responsive variant 추가, dark mode setup.
**언제 X**: visual design judgement (의 designer 의 의), pixel-perfect Figma 의 의 (의 visual review 의 의).

## ❌ 안티패턴
- **`@apply` 의 abuse**: 매 utility 의 의 의 component class 의 — 의 utility-first 의 의 의 lose.
- **Long class string 의 의 abstraction 의 X**: 50+ class 의 의 → cva variant 의 의.
- **Arbitrary value 의 의**: 의 `top-[117px]` 의 의 → design token 추가.
- **Dynamic class 의 string interpolation**: `bg-${color}-500` — 의 tree-shake 의 의 (full class name 의 의 string 의 의).
- **Mixing CSS-in-JS + Tailwind**: 의 specificity war — 의 의 의 의.

## 🧪 검증 / 중복
- Verified (Tailwind v4 docs, Adam Wathan blog, UnoCSS docs, shadcn/ui).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — utility-first CSS + Tailwind v4 |