refactor(blog): @theme로 디자인 토큰 전환 + arbitrary value 제거 (#120)

[Malloc72P]

원인 규명 (핵심)

#94에서 "Tailwind v4 @theme가 Turbopack 빌드에서 토큰/유틸을 생성하지 않는다"고 판단해 :root + arbitrary value(bg-[var(--color-*)])로 우회했었습니다.

이는 오진이었습니다. 실험으로 확인:

• @theme { --color-x: #00ff00 } → .bg-x{background-color:var(--color-x)} + --color-x:#0f0 모두 정상 생성.
• #94에서 "없다"고 본 건, 빌드 산출물의 minify된 값(#00ff00→#0f0)을 minify 전 문자열로 grep해서 생긴 false negative였습니다. (#6366f1처럼 minify 안 되는 값으로 재확인 → 정상 출력)

변경

• global.css: :root → @theme (브랜드 스케일·ink·surface·border 토큰 6종)
• 컴포넌트 17곳: arbitrary value 제거 → 깔끔한 유틸리티
  • bg-[var(--color-ink)] → bg-ink, bg-[var(--color-brand-strong)] → bg-brand-strong
  • bg-[var(--color-surface-muted)] → bg-surface-muted, border-[var(--color-border)] → border-border
  • ring-[var(--color-brand)] → ring-brand, bg-[var(--color-ink)]/50 → bg-ink/50 등
• 값은 동일 → 시각 변화 0 (회귀 없음)

검증

• 빌드 CSS: --color-* 6종 :root 출력 + .bg-ink/.bg-brand-strong/.border-border 유틸 생성 + bg-ink/50 color-mix 확인
• 스크린샷 육안 확인(랜딩: 다크 헤더 + 인디고 활성 칩, 동일)
• 단위 81 / E2E 7(프로덕션 빌드) / lint 0 / tsc clean

범위 결정 — 텍스트 그레이 "전면 토큰화"는 보류

#120에 적힌 "muted 텍스트 등 전면 토큰화"는 의도적으로 제외했습니다. 이유:

• 값을 유지하며 전면 토큰화하면 text-gray-{400,500,600,700,800,900} 6개 음영마다 토큰이 필요 → 과도한 토큰화(역할 없는 fg-700 등).
• 소수 역할로 통합(예: muted=한 값)하려면 시각 변화 + 주관적 디자인 결정이 됨.
  → 이건 별도 디자인 결정으로 다루는 게 맞다고 판단. 이 PR은 @theme 부채 해소 + 클린 유틸 전환에 집중.

🤖 Generated with Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
blog	Ignored		Jun 30, 2026 12:09am

[Malloc72P]

🔍 코드 리뷰 (self-review)

기계적 전환(arbitrary→@theme 유틸)이라 시각 변화 0이고 검증이 끝나, 고칠 미흡점은 없습니다. 핵심만 기록합니다.

가장 중요한 결론

• @theme는 원래부터 정상 동작했음. #94의 "미동작"은 minify된 값을 grep으로 놓친 제 진단 오류였습니다. 이 PR로 불필요했던 arbitrary value 우회를 전부 제거했습니다. (앞으로 빌드 CSS 검증 시 minify를 감안해 grep하겠습니다.)

의도적 결정

• 텍스트 그레이 전면 토큰화 보류: 값 유지 시 음영마다 토큰이 생겨 과도, 역할 통합 시 시각 변화+주관적 결정이 됨 → 별도 디자인 결정으로 분리. 이 PR은 부채 해소 + 클린 유틸에 집중.
• border-border/border-border-subtle 네이밍은 shadcn 관례를 따름(약간 중복돼 보이나 인지도 높음).

검증

• 빌드 CSS 토큰/유틸 생성 확인 · 스크린샷 동일 · 단위 81 · E2E 7(프로덕션) · lint 0 · tsc clean