Tailwind의 복잡성과 추상화

<button class="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600">
  클릭
</button>

bg-blue-500        →  background-color: rgb(59, 130, 246)
text-white         →  color: rgb(255, 255, 255)
px-4               →  padding-left: 1rem; padding-right: 1rem
rounded            →  border-radius: 0.25rem
hover:bg-blue-600  →  :hover { background-color: rgb(37, 99, 235) }

// vite.config.ts
import tailwindcss from '@tailwindcss/vite'
 
export default {
  plugins: [tailwindcss()]  // 이게 있어야 @import "tailwindcss"가 컴파일러를 거침
}

/* globals.css */
@import "tailwindcss";
 
/* 테마 커스터마이징도 같은 파일에서 */
@theme {
  --color-brand: #ff6b00;  /* bg-brand, text-brand 등으로 사용 가능 */
  --spacing-18: 4.5rem;    /* p-18, m-18 등으로 사용 가능 */
}

// index.ts의 parseCss() 내부
features |= await substituteAtImports(ast, base, loadStylesheet, 0, from !== undefined)

// at-import.ts의 substituteAtImports() 핵심 부분
walk(ast, (node) => {
  if (node.name === '@import') {
    promises.push((async () => {
      // './theme.css'든 'tailwindcss'든 동일한 loadStylesheet을 호출
      // enhanced-resolve가 상대 경로 vs 패키지 이름을 자동 구분
      let loaded = await loadStylesheet(uri, base)     // 경로 해석 + 파일 로드가 여기서 발생
      let ast = CSS.parse(loaded.content)              // CSS 파싱
      await substituteAtImports(ast, loaded.base,      // 재귀: 로드된 파일의
            loadStylesheet, recurseCount + 1)          //      @import도 처리
    })())
  }
})

// @tailwindcss-node/src/compile.ts
const cssResolver = EnhancedResolve.ResolverFactory.createResolver({
  extensions: ['.css'],
  mainFields: ['style'],        // package.json의 최상위 "style" 필드를 봄
  conditionNames: ['style'],    // exports의 "style" 조건을 봄
  modules: ['node_modules'],
})

// tailwindcss/package.json
{
  "exports": {
    ".": {
      "style": "./index.css"   // conditionNames: ['style']에 매칭
    }
  },
  "style": "index.css"          // mainFields: ['style']에 매칭 (fallback)
}

/* tailwindcss/index.css */
@layer theme, base, components, utilities;
 
@import './theme.css' layer(theme);
@import './preflight.css' layer(base);
@import './utilities.css' layer(utilities);

@layer theme, base, components, utilities;
         ↑                           ↑
      가장 낮음                   가장 높음

/* base 레이어 (preflight.css) */
@layer base {
  h1 { font-size: 2rem; margin-bottom: 0.5rem; }
}
 
/* utilities 레이어 (Tailwind가 생성) */
@layer utilities {
  .text-sm { font-size: 0.875rem; }
  .mb-0 { margin-bottom: 0; }
}

<h1 class="text-sm mb-0">제목</h1>

/* tailwindcss/utilities.css */
@tailwind utilities;

AST (substituteAtImports 완료 후)
├── @layer theme, base, components, utilities
├── [theme.css 내용]
│   ├── --color-blue-500: oklch(62.3% 0.214 259.815)
│   ├── --color-white: #fff
│   ├── --spacing: 0.25rem
│   └── ...
├── [preflight.css 내용]
│   ├── *, ::after, ::before, ::backdrop { box-sizing: border-box; margin: 0; padding: 0; border: 0 solid; }
│   └── ...
└── [utilities.css 내용]
    └── @tailwind utilities   ← parseCss()가 이 노드를 utilitiesNode로 기록

// index.ts의 parseCss() 내부
if (node.name === '@tailwind' && node.params === 'utilities') {
  utilitiesNode = node    // "여기에 나중에 유틸리티 CSS를 넣어라"는 위치 마커
  features |= Features.Utilities
}

#[derive(Debug, Default)]
pub struct CandidateMachine {
    start_pos: usize,
    last_variant_end_pos: Option<usize>,
    utility_machine: UtilityMachine,
    variant_machine: VariantMachine,
}

// named_utility_machine.rs
/// Extracts named utilities from an input.
///
/// E.g.:
///   flex
///   bg-red-500
 
// named_variant_machine.rs
/// Extract named variants from an input including the `:`.
///
/// E.g.:
///   hover:flex
///   data-[state=pending]:flex

// candidate.ts
export type Candidate =
  // "underline", "box-border" 같은 고정 유틸리티
  | { kind: 'static'; root: string; variants: Variant[]; important: boolean; raw: string }
  // "bg-red-500", "bg-[#0088cc]" 같은 값을 받는 유틸리티
  | { kind: 'functional'; root: string; value: ArbitraryUtilityValue | NamedUtilityValue | null;
      modifier: ArbitraryModifier | NamedModifier | null; variants: Variant[]; important: boolean; raw: string }
  // "[color:red]" 같은 임의 속성+값 유틸리티
  | { kind: 'arbitrary';  property: string; value: string;
      modifier: ArbitraryModifier | NamedModifier | null; variants: Variant[]; important: boolean; raw: string }

// candidate.ts의 parseCandidate() 핵심 흐름
// 입력: "hover:bg-blue-500/50!"
 
// ① variant 분리: ':' 기준으로 분할
let rawVariants = segment(input, ':')
// → ['hover', 'bg-blue-500/50!']
 
let base = rawVariants.pop()!
// → base = 'bg-blue-500/50!'
// → rawVariants = ['hover']
 
// 남은 rawVariants를 역순으로 파싱하여 Variant 객체로 변환
let parsedCandidateVariants: Variant[] = []
for (let i = rawVariants.length - 1; i >= 0; --i) {
  let parsedVariant = designSystem.parseVariant(rawVariants[i])
  parsedCandidateVariants.push(parsedVariant)
}
// → [{ kind: 'static', root: 'hover' }]
 
// ② important 감지: base 끝이 '!'이면 제거하고 플래그 설정
let important = false
if (base[base.length - 1] === '!') {
  important = true
  base = base.slice(0, -1)
}
// → important = true, base = 'bg-blue-500/50'
 
// ③ modifier 분리: '/' 기준으로 분할
let [baseWithoutModifier, modifierSegment = null] = segment(base, '/')
// → baseWithoutModifier = 'bg-blue-500', modifierSegment = '50'
 
let parsedModifier = modifierSegment === null ? null : parseModifier(modifierSegment)
// → { kind: 'named', value: '50' }
 
// ④ root/value 분리: findRoots()가 뒤에서부터 '-'를 잘라가며 탐색
//    'bg-blue-500' → has('bg-blue-500')? No
//    'bg-blue'     → has('bg-blue')?     No
//    'bg'          → has('bg')?          Yes ✓ → root = 'bg', value = 'blue-500'
let roots = findRoots(baseWithoutModifier, (root) => {
  return designSystem.utilities.has(root, 'functional')
})
 
// ⑤ value 종류 판별: '[' 로 끝나면 arbitrary, 아니면 named
for (let [root, value] of roots) {
  let candidate: Candidate = {
    kind: 'functional', root, modifier: parsedModifier,
    value: null, variants: parsedCandidateVariants, important, raw: input,
  }
 
  // value가 '[...]'이면 arbitrary, 아니면 named
  if (value[value.length - 1] === ']') {
    // arbitrary 처리 (예: bg-[#0088cc])
    candidate.value = { kind: 'arbitrary', dataType: null, value: decodeArbitraryValue(...) }
  } else {
    // named 처리 (예: blue-500)
    candidate.value = { kind: 'named', value, fraction: null }
  }
  // → { kind: 'named', value: 'blue-500', fraction: null }
 
  yield candidate
}

{
  kind: 'functional',
  root: 'bg',
  value: { kind: 'named', value: 'blue-500', fraction: null },
  modifier: { kind: 'named', value: '50' },
  variants: [{ kind: 'static', root: 'hover' }],
  important: true,
  raw: 'hover:bg-blue-500/50!',
}

// utilities.ts
type CompileFn<T extends Candidate['kind']> = (
  value: Extract<Candidate, { kind: T }>,
) => AstNode[] | undefined | null
 
export type Utility = {
  kind: 'static' | 'functional'
  compileFn: CompileFn<any>
  options?: UtilityOptions
}

// static: 클래스 이름이 고정된 CSS에 1:1 대응
// "flex" → display: flex
staticUtility('flex', [['display', 'flex']])
 
// functional: 뒤에 붙는 값에 따라 다른 CSS를 생성
// "z-10" → z-index: 10, "z-auto" → z-index: auto
functionalUtility('z', {
  supportsNegative: true,
  handleBareValue: ({ value }) => {
    if (!isPositiveInteger(value)) return null
    return value
  },
  themeKeys: ['--z-index'],
  handle: (value) => [decl('z-index', value)],
  staticValues: {
    auto: [decl('z-index', 'auto')],
  },
})
 
// colorUtility: 색상 전용 헬퍼 (내부적으로 utilities.functional()을 호출)
// "accent-blue-500" → accent-color: ...
colorUtility('accent', {
  themeKeys: ['--accent-color', '--color'],
  handle: (value) => [decl('accent-color', value)],
})

// compile.ts의 compileCandidates() 핵심 흐름
// ① 원본 문자열 → Candidate 파싱
for (let rawCandidate of rawCandidates) {
  let candidates = designSystem.parseCandidate(rawCandidate)
  // → "hover:bg-blue-500/50!" → [{ kind: 'functional', root: 'bg', ... }]
  matches.set(rawCandidate, candidates)
}
 
// ② Candidate → CSS AST 생성
for (let [rawCandidate, candidates] of matches) {
  for (let candidate of candidates) {
    let rules = designSystem.compileAstNodes(candidate, flags)
    // → compileBaseUtility()에서 'bg'로 등록된 유틸리티를 찾아 compileFn 호출
    // → utilities.functional('bg', ...)의 compileFn → decl('background-color', 'rgb(59 130 246)')
    astNodes.push(rules)
  }
}
 
// ③ variant 적용 + important 처리 + 정렬
// compileAstNodes() 내부에서:
//   - candidate.important이면 모든 선언에 !important 추가
//   - candidate.variants를 순회하며 applyVariant()로 셀렉터를 감쌈
//     예: hover variant → .hover\:bg-blue-500\/50\!:hover { ... }
//   - 최종 AST 노드를 variant 순서 → 속성 순서 → 알파벳 순으로 정렬

"bg-blue-500"
  ↓ Rust 스캔 → 클래스 후보 추출
  ↓ parseCandidate() → { kind: 'functional', root: 'bg', value: { kind: 'named', value: 'blue-500' } }
  ↓ compileBaseUtility() → designSystem.utilities.get('bg') → utilities.functional('bg', ...)의 compileFn
  ↓ compileFn 내부:
    ↓ resolveThemeColor()로 테마에서 --color-blue-500 조회 → 색상값 획득
    ↓ asColor() → modifier(투명도)가 있으면 적용
    ↓ [decl('background-color', 'rgb(59 130 246)')] 반환
  ↓ compileAstNodes() → .bg-blue-500 { background-color: rgb(59 130 246) }

// index.ts의 build() 내부
utilitiesNode.nodes = newNodes   // 생성된 유틸리티 CSS를 utilitiesNode 자리에 넣음

.flex { display: flex }
.bg-blue-500 { background-color: rgb(59 130 246) }
.text-white { color: rgb(255 255 255) }
.px-4 { padding-left: 1rem; padding-right: 1rem }
.hover\:bg-blue-600:hover { background-color: rgb(37 99 235) }
/* ... 소스에서 발견된 클래스만 생성됨 */

/* 사용자가 하는 일의 전부 */
@import "tailwindcss";

<!-- 그리고 클래스를 쓰면 된다 -->
<button class="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600">

<!-- CSS 클래스: 별도 파일을 열어봐야 스타일을 알 수 있음 -->
<button class="btn-primary">
 
<!-- Tailwind: 클래스 이름만 봐도 스타일이 전부 보임 -->
<button class="bg-blue-500 text-white px-4 py-2 rounded">

사용자: "버튼 배경을 더 진한 파란색으로"
→ bg-blue-500 → bg-blue-700  (500, 700은 명도 스케일)
 
사용자: "모서리 더 둥글게"
→ rounded → rounded-xl

@import "tailwindcss"
  │
  │  Step 1. @import 해석과 치환
  │  substituteAtImports()가 @import를 발견하면
  │  loadStylesheet 콜백으로 경로 해석 + 파일 로드
  │  → enhanced-resolve가 package.json의 "style" 필드를 보고
  │  → "tailwindcss" → index.css로 해석
  │  → 파싱된 AST로 @import 노드를 교체
  ▼
  Step 2. index.css 내용 펼침
  │  @layer theme, base, components, utilities
  │  @import './theme.css'      → CSS 변수 (디자인 토큰)
  │  @import './preflight.css'  → 브라우저 기본 스타일 리셋
  │  @import './utilities.css'  → @tailwind utilities 한 줄
  │
  Step 3. @tailwind utilities → utilitiesNode로 기록 (위치 마커)
  │
  Step 4. Scan     → Rust 엔진이 소스 파일에서 클래스 후보 추출
  Step 5. Parsing  → parseCandidate()가 구조화된 Candidate 객체로 분해
  Step 6. CSS 생성 → compileCandidates()가 Candidate를 CSS AST로 변환
  │
  Step 7. 생성된 CSS를 utilitiesNode 위치에 주입
  ▼
  .bg-blue-500 { background-color: rgb(59 130 246) }
  .flex { display: flex }
  .hover\:bg-blue-600:hover { background-color: rgb(37 99 235) }