Tailwind CSS v4 마이그레이션 및 CSS-first 설정 전환 #11

2YH02 · 2026-02-10T00:27:00Z

개요

Tailwind CSS를 v3에서 v4로 마이그레이션하고, 설정 방식을 CSS-first로 전환

주요 변경사항

Tailwind CSS 업그레이드
- tailwindcss -> ^4.1.18
- @tailwindcss/postcss 추가
PostCSS 설정 변경
- postcss.config.mjs에서 tailwindcss 플러그인을 @tailwindcss/postcss로 교체
CSS-first 설정으로 전환
- app/globals.css에 @theme, @custom-variant, @plugin 설정 이관
- tailwind.config.ts 제거
v4 유틸리티 규칙에 맞게 일부 클래스 조정
- 예: bg-50% -> bg-size-50

검증

yarn lint 실행 (기존 경고 유지)
yarn build 실행 통과

참고/영향

자동 마이그레이션 도구 적용으로 스타일 관련 파일 변경 범위가 넓습니다.
기능 로직 변경은 없고, 스타일 시스템/빌드 설정 중심 변경입니다.

fix: 드로워 드래그 영역을 핸들로만 제한하여 스크롤 충돌 해결

vercel · 2026-02-10T00:27:07Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
k-pullup	Ignored		Feb 10, 2026 0:47am

qodo-code-review · 2026-02-10T00:27:29Z

Review Summary by Qodo

Tailwind CSS v4 migration with CSS-first configuration and utility class updates

✨ Enhancement

Walkthroughs

Description

• Migrate Tailwind CSS from v3 to v4 with CSS-first configuration
• Update PostCSS config to use @tailwindcss/postcss plugin
• Refactor globals.css with @theme, @custom-variant, @utility directives
• Update utility class names for v4 compatibility (e.g., shadow-sm, outline-hidden, rounded-sm)
• Add AGENTS.md documentation for coding agent guidelines
• Add PR template for standardized pull request format

Diagram

flowchart LR
  A["Tailwind v3<br/>Config-based"] -->|Upgrade| B["Tailwind v4<br/>CSS-first"]
  C["postcss.config.mjs<br/>tailwindcss plugin"] -->|Replace| D["@tailwindcss/postcss<br/>plugin"]
  E["tailwind.config.ts<br/>JS configuration"] -->|Migrate to| F["globals.css<br/>@theme directives"]
  G["Old utility classes<br/>shadow, outline-none"] -->|Update| H["v4 utilities<br/>shadow-sm, outline-hidden"]
  B --> I["Updated components<br/>& pages"]
  D --> I
  F --> I
  H --> I

File Changes

1. app/globals.css ✨ Enhancement +256/-97

Migrate to Tailwind v4 CSS-first configuration

app/globals.css

2. postcss.config.mjs ⚙️ Configuration changes +1/-1

Replace tailwindcss with @tailwindcss/postcss plugin

postcss.config.mjs

3. package.json Dependencies +2/-1

Upgrade tailwindcss to v4 and add @tailwindcss/postcss

package.json

View more (49)

4. AGENTS.md 📝 Documentation +111/-0

Add comprehensive coding agent guidelines and rules

AGENTS.md

5. .github/pull_request_template.md 📝 Documentation +38/-0

Add standardized PR template with checklist

.github/pull_request_template.md

6. components/common/toast.tsx ✨ Enhancement +4/-4

Update Tailwind v4 utility class syntax

components/common/toast.tsx

7. components/ui/select.tsx ✨ Enhancement +4/-4

Update to v4 CSS variable and utility syntax

components/ui/select.tsx

8. components/pages/pullup/comments.tsx ✨ Enhancement +8/-8

Update stroke utility class syntax for v4

components/pages/pullup/comments.tsx

9. components/pages/home/moment-list.tsx ✨ Enhancement +4/-4

Replace break-words with wrap-break-word utility

components/pages/home/moment-list.tsx

10. components/layout/roadview.tsx ✨ Enhancement +3/-3

Update rounded and z-index utility syntax

components/layout/roadview.tsx

11. components/pages/pullup/button-list.tsx ✨ Enhancement +4/-4

Replace w-[1px] with w-px utility class

components/pages/pullup/button-list.tsx

12. app/mypage/page.tsx ✨ Enhancement +3/-3

Update dark mode modifier syntax for v4

app/mypage/page.tsx

13. components/pages/search/around-search.tsx ✨ Enhancement +2/-2

Update gradient and backdrop-blur utilities

components/pages/search/around-search.tsx

14. components/ui/dialog.tsx ✨ Enhancement +1/-1

Update rounded and outline utility classes

components/ui/dialog.tsx

15. components/ui/table.tsx ✨ Enhancement +3/-3

Update pseudo-class selector syntax for v4

components/ui/table.tsx

16. components/pages/admin/image-gallery.tsx ✨ Enhancement +2/-2

Update backdrop-blur utility to backdrop-blur-xs

components/pages/admin/image-gallery.tsx

17. app/social/chat/[code]/chat-detail-client.tsx ✨ Enhancement +2/-2

Replace shadow-sm with shadow-xs utility

app/social/chat/[code]/chat-detail-client.tsx

18. components/layout/kakao-map.tsx ✨ Enhancement +2/-2

Update z-index and shadow utility syntax

components/layout/kakao-map.tsx

19. components/pages/home/slide-icons.tsx ✨ Enhancement +2/-2

Update SVG data-name attribute for v4

components/pages/home/slide-icons.tsx

20. app/pullup/[id]/chat/pullup-chat-client.tsx ✨ Enhancement +2/-2

Replace shadow-sm with shadow-xs utility

app/pullup/[id]/chat/pullup-chat-client.tsx

21. components/layout/move-map-input.tsx ✨ Enhancement +2/-2

Update z-index and dark mode modifier syntax

components/layout/move-map-input.tsx

22. app/admin/admin-client.tsx ✨ Enhancement +2/-2

Update backdrop-blur and shadow utilities

app/admin/admin-client.tsx

23. components/common/list-item.tsx ✨ Enhancement +3/-3

Replace flex-shrink-0 with shrink-0 utility

components/common/list-item.tsx

24. components/layout/map-context-menu.tsx ✨ Enhancement +2/-2

Update z-index utility syntax for v4

components/layout/map-context-menu.tsx

25. components/ui/badge.tsx ✨ Enhancement +3/-3

Update outline and shadow utility classes

components/ui/badge.tsx

26. components/pages/search/search-list.tsx ✨ Enhancement +2/-2

Update rounded utility class syntax

components/pages/search/search-list.tsx

27. components/ui/input.tsx ✨ Enhancement +1/-1

Update shadow and outline utilities

components/ui/input.tsx

28. components/pages/register/set-description.tsx ✨ Enhancement +1/-1

Update rounded and outline utility syntax

components/pages/register/set-description.tsx

29. components/pages/admin/location-comparison.tsx ✨ Enhancement +1/-1

Update grid template column syntax

components/pages/admin/location-comparison.tsx

30. components/common/toggle-button.tsx ✨ Enhancement +2/-2

Update outline and RTL modifier syntax

components/common/toggle-button.tsx

31. app/search/around/around-client.tsx ✨ Enhancement +1/-1

Update gradient utility to bg-linear-to-br

app/search/around/around-client.tsx

32. components/pages/register/upload-image.tsx ✨ Enhancement +1/-1

Replace shadow-sm with shadow-xs utility

components/pages/register/upload-image.tsx

33. components/common/text.tsx ✨ Enhancement +3/-3

Update leading utility to leading-normal

components/common/text.tsx

34. components/pages/mypage/bookmark/bookmark-list.tsx ✨ Enhancement +2/-2

Replace break-words with wrap-break-word

components/pages/mypage/bookmark/bookmark-list.tsx

35. components/common/side-main.tsx ✨ Enhancement +1/-1

Replace shadow-sm with shadow-xs utility

components/common/side-main.tsx

36. components/common/input.tsx ✨ Enhancement +1/-1

Update outline utility class syntax

components/common/input.tsx

37. components/pages/pullup/moment/add-moment-page.tsx ✨ Enhancement +1/-1

Update outline utility class syntax

components/pages/pullup/moment/add-moment-page.tsx

38. components/pages/pullup/moment/moment-item.tsx ✨ Enhancement +1/-1

Replace break-words with wrap-break-word

components/pages/pullup/moment/moment-item.tsx

39. components/pages/pullup/description.tsx ✨ Enhancement +1/-1

Update rounded and outline utilities

components/pages/pullup/description.tsx

40. app/ranking/ranking-client.tsx ✨ Enhancement +1/-1

Update background-size utility syntax

app/ranking/ranking-client.tsx

41. app/search/search-client.tsx ✨ Enhancement +1/-1

Update gradient utility to bg-linear-to-br

app/search/search-client.tsx

42. components/common/footer.tsx ✨ Enhancement +1/-1

Update max-width utility to CSS variable syntax

components/common/footer.tsx

43. components/common/event-popup.tsx ✨ Enhancement +1/-1

Update rounded utility class syntax

components/common/event-popup.tsx

44. components/pages/home/notice-slide.tsx ✨ Enhancement +1/-1

Replace shadow with shadow-sm utility

components/pages/home/notice-slide.tsx

45. components/common/textarea.tsx ✨ Enhancement +1/-1

Update outline utility class syntax

components/common/textarea.tsx

46. components/pages/admin/location-with-address.tsx ✨ Enhancement +1/-1

Replace flex-shrink-0 with shrink-0

components/pages/admin/location-with-address.tsx

47. components/pages/pullup/address-button.tsx ✨ Enhancement +1/-1

Replace break-words with wrap-break-word

components/pages/pullup/address-button.tsx

48. components/pages/home/search-input.tsx ✨ Enhancement +1/-1

Replace shadow with shadow-sm utility

components/pages/home/search-input.tsx

49. components/common/button.tsx ✨ Enhancement +2/-2

Update rounded and outline utility syntax

components/common/button.tsx

50. .pnp.cjs Additional files +1928/-1789

...

.pnp.cjs

51. components/pages/pullup/upload-image.tsx Additional files +1/-1

...

components/pages/pullup/upload-image.tsx

52. tailwind.config.ts Additional files +0/-141

...

tailwind.config.ts

qodo-code-review · 2026-02-10T00:33:49Z

Code Review by Qodo

🐞 Bugs (3) 📘 Rule violations (0) 📎 Requirement gaps (0)

✅ 1. ~~Z-index scale regressions~~ 🐞 Bug ⛯ Reliability

Description

• Several overlays/buttons were changed from arbitrary z-index classes (e.g. z-[60]) to
  scale-based classes (z-60, z-61, z-99, z-100, z-28, mo:z-2).
• The repo does not define any z-index theme tokens in app/globals.css, so these new scale classes
  have no project-local definition; they may not produce the intended stacking and can cause
  overlays/menus/toasts to appear behind other UI.
• Impacted UX includes: map loading dimmer, map context menu layering, roadview controls, toast
  visibility, and mobile map search button stacking.

Code

components/layout/kakao-map.tsx[R286-289]

+        <div className="z-60 absolute top-0 left-0 w-dvw h-dvh bg-[#ffffffb2] flex items-center justify-center">
         <div>
           <LoadingIcon className="m-0" />
         </div>

Evidence
The code now relies on non-default-looking z-* scale classes (60/61/99/100/28/2) across key
overlay surfaces. In this repo, app/globals.css defines theme tokens for colors/shadows/animations
but does not define any z-index tokens that would make z-60, z-99, etc. reliably map to a value,
so stacking behavior is at risk.
components/layout/kakao-map.tsx[285-299]
components/layout/map-context-menu.tsx[21-34]
components/layout/roadview.tsx[189-204]
components/common/toast.tsx[16-23]
components/layout/move-map-input.tsx[99-106]
app/globals.css[8-47]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Several UI overlays were migrated from arbitrary z-index utilities (like `z-[60]`) to scale-based classes (`z-60`, `z-99`, `z-100`, `mo:z-2`, etc.). The repo’s `@theme` block does not define any z-index tokens, so these classes may not produce the intended stacking order.
### Issue Context
This impacts critical overlay surfaces (Kakao map loading mask, map context menu, roadview controls/badges, toast viewport, mobile move-map button), where incorrect z-index causes UI to render behind other layers.
### Fix Focus Areas
- components/layout/kakao-map.tsx[285-299]
- components/layout/map-context-menu.tsx[21-34]
- components/layout/roadview.tsx[189-204]
- components/common/toast.tsx[16-23]
- components/layout/move-map-input.tsx[99-106]
- app/globals.css[8-47]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

✅ 2. ~~Broken table selectors~~ 🐞 Bug ✓ Correctness

Description

• components/ui/table.tsx rewrites a Tailwind selector that targets checkbox elements into
  *:[[role=checkbox]]:translate-y-[2px], which is inconsistent with the rest of the file’s selector
  style and is unlikely to match the original intent.
• TableFooter also changes from applying border-b-0 to the last ` child to applying last:` to
  the `` itself, which likely won’t remove the last-row border.
• Result: checkbox alignment and table footer borders can regress anywhere this shared Table
  component is used.

Code

components/ui/table.tsx[R75-76]

+      "h-10 px-2 text-left align-middle font-medium text-muted-foreground [&:has([role=checkbox])]:pr-0 *:[[role=checkbox]]:translate-y-[2px]",
     className

Evidence

The Table component uses Tailwind arbitrary selectors elsewhere (e.g.
"[&_tr:last-child]:border-0"). The new *:[[role=checkbox]]:... syntax stands out as a
malformed/incorrect conversion and the last:[&>tr] change alters selector semantics for footer row
borders.

components/ui/table.tsx[42-46]
components/ui/table.tsx[72-76]
components/ui/table.tsx[87-91]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Table component contains selector conversions that likely break Tailwind selector parsing and/or change semantics:
- `*:[[role=checkbox]]:translate-y-[2px]` is likely malformed and may not apply.
- `last:[&amp;amp;&amp;gt;tr]:border-b-0` changes which element `last:` applies to.
### Issue Context
This is a shared primitive (`components/ui/table.tsx`). Any regressions will propagate across admin and any table usage.
### Fix Focus Areas
- components/ui/table.tsx[42-46]
- components/ui/table.tsx[72-76]
- components/ui/table.tsx[87-91]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

3. Conflicting primary token 🐞 Bug ✓ Correctness

Description

• app/globals.css defines --color-primary as #f9b4ab inside @theme, but later overrides
  --color-primary to #fab4ab in a :root block.
• This makes the theme token definition misleading and can cause inconsistent results depending on
  which layer wins in the cascade.
• It’s easy for future changes to accidentally rely on the wrong value, especially during a Tailwind
  v4 migration where CSS variables drive many utilities.

Code

app/globals.css[R210-214]

+  :root {
+    --background: white;
+    --color: #232323;
+    --color-primary: #fab4ab;
+  }

Evidence

The same CSS variable is assigned two different values in the same stylesheet: once in @theme and
again in @layer utilities :root. This is a concrete conflict and will override one of the intended
definitions.

app/globals.css[8-12]
app/globals.css[209-214]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`--color-primary` is defined twice with different values (`#f9b4ab` in `@theme`, `#fab4ab` in `@layer utilities :root`). This creates a real cascade conflict and makes the Tailwind theme misleading.
### Issue Context
Tailwind v4 relies heavily on CSS variables for theme tokens; conflicting definitions can lead to inconsistent colors and hard-to-debug styling.
### Fix Focus Areas
- app/globals.css[8-12]
- app/globals.css[209-214]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

ⓘ The new review experience is currently in Beta. Learn more

components/layout/kakao-map.tsx

components/ui/table.tsx

2YH02 and others added 6 commits December 13, 2025 22:33

Merge pull request #10 from 2YH02/develop

01919fc

fix: 드로워 드래그 영역을 핸들로만 제한하여 스크롤 충돌 해결

Merge branch 'develop'

beca64e

chore: add agents guide and update pnp

86a9b74

chore: Tailwind CSS v4 CSS-first 설정으로 마이그레이션

4213fec

docs: AGENTS 커밋 및 로그 확인 규칙 추가

6792bf0

docs: PR 템플릿 및 PR 작성 규칙 추가

bc64b9c

qodo-code-review bot reviewed Feb 10, 2026

View reviewed changes

components/layout/kakao-map.tsx Show resolved Hide resolved

components/ui/table.tsx Outdated Show resolved Hide resolved

2YH02 added 3 commits February 10, 2026 09:41

refactor: 미사용 Table UI 컴포넌트 제거

94b33ca

fix: z-index 토큰 추가로 오버레이 레이어링 안정화

528bd7e

fix: color-primary 토큰 중복 정의 제거

86186c8

2YH02 merged commit 81f51f3 into develop Feb 10, 2026
4 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tailwind CSS v4 마이그레이션 및 CSS-first 설정 전환 #11

Tailwind CSS v4 마이그레이션 및 CSS-first 설정 전환 #11

Uh oh!

2YH02 commented Feb 10, 2026

Uh oh!

vercel bot commented Feb 10, 2026 •

edited

Loading

Uh oh!

qodo-code-review bot commented Feb 10, 2026

Uh oh!

qodo-code-review bot commented Feb 10, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Tailwind CSS v4 마이그레이션 및 CSS-first 설정 전환 #11

Tailwind CSS v4 마이그레이션 및 CSS-first 설정 전환 #11

Uh oh!

Conversation

2YH02 commented Feb 10, 2026

개요

주요 변경사항

검증

참고/영향

Uh oh!

vercel bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qodo-code-review bot commented Feb 10, 2026

Review Summary by Qodo

Walkthroughs

File Changes

Uh oh!

qodo-code-review bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

vercel bot commented Feb 10, 2026 •

edited

Loading

qodo-code-review bot commented Feb 10, 2026 •

edited

Loading