공시한입 Docs

Appearance

Tailwind v4 함정 ​

frontend/ (Next.js 16 + Tailwind 4) 작업 시 반복 발생한 이슈.

1. @theme 커스텀 네임스페이스의 utility 자동 생성 한계 ​

증상: globals.css @theme 에 --spacing-md: 12px, --text-md: 14px, --radius-md: 12px 같이 커스텀 이름으로 토큰을 정의해도 p-md, text-md, rounded-md 같은 utility 가 안 만들어짐 (또는 부분만 됨). 빌드는 통과하지만 페이지 padding/font/radius 가 모두 0/기본값으로 보임.

원인: TW v4 의 @theme 토큰 → utility 자동 생성은 color 네임스페이스만 안정적으로 동작. spacing/text/radius/font 등 다른 카테고리는 카테고리별 규칙이 다르고 커스텀 명을 utility 로 끌어올리는 것이 보장되지 않는다 (현재 v4 기준).

해결: color 외에는 토큰 정의 자체를 하지 말고, TW 기본 스케일 + arbitrary 값 사용:

css
/* ❌ 안 됨 */
@theme {
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --text-md: 14px;
  --radius-md: 12px;
}
tsx
// ❌ p-xs 가 4px 로 안 만들어짐
<div className="p-xs text-md rounded-md" />
css
/* ✅ color 만 */
@theme {
  --color-primary: #2d9d92;
  --color-background: #f0f7f6;
}
tsx
// ✅ TW 기본 스케일 (p-1=4px, p-2=8px ...) + arbitrary
<div className="p-1 text-sm rounded-xl" />
<div className="text-[11px] rounded-[20px]" /> // 비표준 픽셀

Flutter 토큰 매핑 시: AppSpacing (4/8/12/16/20/24/32 px) 가 TW 기본 (p-1~p-8) 와 자연 정렬돼서 일치. AppRadius (8/12/16/20) → rounded-lg/rounded-xl/rounded-2xl/rounded-[20px]. AppTypography 는 일부만 일치 (sm=14→text-sm, lg=16→text-base, xl=18→text-lg), 나머지 text-[11px] 등 arbitrary.

2. 디버깅: utility 가 적용 안 되는지 빠른 확인 ​

CSS 가 깨졌을 때 색상은 적용되는데 spacing/radius 만 안 적용되면 1번 함정 의심.

js
// 브라우저 콘솔
getComputedStyle(document.querySelector('main > div')).padding  // "0px" 이면 utility 매칭 실패

DOM inspector 에서 클래스가 붙어있는데도 padding: 0 이면 generated CSS 에 .p-xs 자체가 없다는 뜻 — 클래스 이름은 valid 하지만 TW 가 utility 를 만들지 않음.

3. 커스텀 토큰을 정말 utility 로 만들고 싶을 때 ​

@utility directive 사용. 다만 단순히 픽셀이 안 맞아서라면 arbitrary 값이 더 가볍다.

css
@utility p-xs {
  padding: 4px;
}

판단 기준: 같은 픽셀이 5+곳에서 쓰이고, arbitrary 표기 (p-[4px]) 가 가독성을 해친다면 @utility. 아니면 TW 기본 + arbitrary.