Tailwind v4 마이그레이션: Dynamic spacing utilities

요즘 Tailwind CSS를 3에서 4로 올리는 작업을 진행하고 있다. 예상보다 많은 이슈가 있었는데, 그동안 EmotionCSS와 PandaCSS만 다뤄와서 Tailwind의 문법과 동작 방식이 꽤 낯설었다. 특히 버전만 올렸는데도 같은 클래스에서 기대한 값과 실제 결과가 크게 달라 레이아웃이 깨져버렸는데, 이를 해결하려면 먼저 Tailwind v4의 spacing 계산 방식을 이해할 필요가 있었다. 이번 글에서 짧게 정리해 보았다.

PandaCSS와 Tailwind v4의 차이

PandaCSS (토큰 매핑)

PandaCSS는 spacing을 design tokens에서 직접 정의한다.

예를 들어, 아래와 같이 토큰이 정의돼 있다면 항상 고정된 값이 출력되기 때문에 다른 결과가 나올 수 없다.

{ "spacing": { "1": { "value": "0.25rem" }, // 4px 
               "2": { "value": "0.5rem" }, // 8px 
               "96": { "value": "24rem" } // 384px } }

• h="96" → height: var(--spacing-96) → 항상 384px

즉, Panda는 토큰 → 값 매핑만 있으므로 예측이 항상 동일하다.

Tailwind v4 (선형 계산)

v3까지는 Panda와 비슷하게 고정값을 리턴했지만, v4부터는 spacing 유틸 전체가 --spacing이라는 단일 토큰을 기준으로 계산된다.

/* v4 */
.h-96 { height: calc(var(--spacing) * 96); }

• Tailwind 기본값: --spacing: 0.25 rem (4px 단위)
• 따라서 h-96 = 96 × 0.25rem = 24 rem = 384px

즉, v4에서는 숫자 값이 실제 길이가 아니라 스텝이고, 해당 값은 --spacing 값에 따라 달라진다.

v3 / v4

v3 / v4와 디자인 토큰 충돌

우리 팀의 디자인 토큰은 픽셀 단위를 기준으로 지정되어 있었기 때문에 테일윈드 v4로 버전이 업데이트되면서 같은 클래스인데 기대치와 실제가 달라 레이아웃이 전부 깨지게 된 것이다.

해결: --spacing을 1px 기반으로 재정의

전역에서 --spacing을 1px 단위로 덮어써서 숫자 유틸 = 픽셀로 맞춰주었다.

@layer theme {
  :root {
    --spacing: 0.0625rem; /* 1px */
  }
}

이제 모든 spacing 유틸은 픽셀 단위로 계산되면서 레이아웃 이슈가 해결되었다.

• h-96 = 96px
• p-4 = 4px
• m-8 = 8px

https://tailwindcss.com/blog/tailwindcss-v4#dynamic-utility-values-and-variants

[Tailwind CSS v4.0

We just released Tailwind CSS v4.0 — an all-new version of the framework optimized for performance and flexibility, with a reimagined configuration and customization experience, and taking full advantage of the latest advancements the web platform has to

tailwindcss.com](https://tailwindcss.com/blog/tailwindcss-v4#dynamic-utility-values-and-variants)

v3를 써본 적이 없어서, 바뀌었을 때의 장점이 궁금해 찾아보았다.

1. 대괄호 필요 없음
   • v3에서는 scale에 없는 값이면 반드시 w-[188px]처럼 사용하거나 커스텀이 필요했다.
   • v4에서는 그냥 w-47처럼 정수만 쓰면 되기 때문에 코드가 훨씬 짧고 깔끔해짐.
2. 스케일 일관성 확보
   • margin, padding, width, height 등 spacing 관련 유틸이 전부 --spacing 하나의 규칙으로 통일됐다.
   • 팀 내에서 단위 계산 방식이 제각각일 일이 줄어든다.
3. 테마 확장 용이
   • --spacing 값을 0.25rem 대신 1px 같은 커스텀 값으로 재정의하면, 모든 spacing 유틸이 한 번에 재계산된다.
   • 디자인 시스템의 단위 정책을 Tailwind에 그대로 녹일 수 있다.
4. 런타임 커스터마이징 가능
   • CSS 변수 기반이라 JS로 --spacing을 바꾸면 앱 전체 spacing이 즉시 재적용된다.

v3

w-[11.75rem] 으로 입력했을 때는 width 값이 제대로 적용된 것을 볼 수 있다. / w-47 을 입력했을 때는 width에 의도하지 않는 값이 들어간 것을 볼 수 있다.

v4

spcing 정의없이 값이 제대로 적용된 것을 확인할 수 있다.