[Build/Design] Tailwind v4 @theme가 Turbopack 빌드에서 토큰/유틸을 생성하지 않음 → 토큰 시스템 완성

[Malloc72P]

현황

#94(디자인 토큰)에서 Tailwind v4 @theme로 시맨틱 토큰을 정의했으나, 이 프로젝트의 Turbopack + v4 프로덕션 빌드에서 커스텀 @theme 토큰(--color-brand 등)이 전혀 생성되지 않음을 빌드 산출 CSS로 확인했다(기본 --color-gray-*는 나오지만 커스텀만 누락, 클린 빌드에서도 동일). 그래서 :root CSS 변수 + arbitrary value(bg-[var(--color-brand)])로 우회해 구현했다.

• 관련: [Design] 디자인 토큰 시스템 + 브랜드 액센트 컬러 #94, [Design] 디자인 토큰 시스템 + 브랜드 액센트 컬러 #94 follow-up PR

문제

• arbitrary value 클래스(bg-[var(--color-brand)], border-[var(--color-border)])가 verbose하고, 깔끔한 bg-brand/text-muted 유틸을 못 쓴다.
• 이 때문에 흩어진 muted 텍스트(text-gray-500/600 약 20+곳) 의 전면 토큰화를 보류했다(우회 방식으론 verbose + @theme 해결 시 재작업이라 throwaway).

제안

1. @theme 미동작 root cause 조사: Turbopack CSS 파이프라인 / @config 미로딩 / @tailwindcss/postcss 처리 순서.
2. 해결되면 :root + arbitrary value를 @theme 기반 깔끔한 유틸(bg-brand, text-muted)로 전환.
3. 중립 색(muted 텍스트 등) 전면 토큰화 완료 + 필요 시 brand 스케일(상태/subtle) 확장.

임팩트 / 난이도

임팩트 중(DX·일관성) / 난이도 중(원인 규명이 관건)

---

🤖 #94 후속 — 코드베이스 조사 기반 작성 (Claude Code)

[Malloc72P]

✅ 원인 규명 완료 — @theme는 정상 동작했음 (PR #122)

이 이슈의 전제("Tailwind v4 @theme가 Turbopack 빌드에서 토큰/유틸을 생성하지 않음")는 오진이었습니다.

실험으로 확인한 진짜 원인

• @theme { --color-x: #00ff00 } 빌드 결과: .bg-x{background-color:var(--color-x)} + --color-x:#0f0 모두 정상 생성.
• #94에서 "없다"고 본 건, 빌드 산출물의 minify된 값(#00ff00→#0f0)을 minify 전 문자열(00ff00)로 grep해서 생긴 false negative.
• minify되지 않는 값(#6366f1)으로 재확인 → --color-brandtest:#6366f1 정상 출력.
• tailwind.config.js 제거 실험에서도 동작 동일 → 그것도 범인 아님.

조치 (PR #122, 병합 완료)

• :root + arbitrary value(bg-[var(--color-*)]) 우회를 제거하고 @theme + 깔끔한 유틸리티(bg-ink, bg-brand-strong, border-border, ring-brand …)로 전환. 값 동일 → 시각 변화 0.

남은 것 → #90으로 이관

• "muted 텍스트 등 중립색 전면 토큰화"는 다크모드([Feature] 다크모드 도입 #90)에서 텍스트 색을 뒤집어야 하므로 그때 함께 진행하는 게 자연스러워 [Feature] 다크모드 도입 #90 작업에 포함합니다.

원인 규명 + 클린 유틸 전환이라는 본래 목적을 달성했으므로 이 이슈는 닫습니다.