How to Build a Custom Theme in Nuxt UI v4

Context

Nuxt UI의 기본 테마는 모든 애플리케이션에서 동일한 시각적 정체성을 가지므로, SaaS 제품, 블로그, 클라이언트 프로젝트 등 각 서비스만의 고유한 브랜딩이 필요할 때 컴포넌트별 CSS 오버라이드와 해킹이 필요했다.

Technical Solution

• main.css의 @theme 디렉티브로 설계 토큰 정의: --font-sans, --font-mono 폰트 변수와 색상 팔레트(50~950 음영)를 한 곳에서 선언
• app.config.ts의 ui.colors에서 의미론적 매핑 실행: 원시 토큰을 primary, secondary, neutral, success 같은 의미 역할로 지정
• app.config.ts의 컴포넌트 키로 컴포넌트 수준 기본값 오버라이드: 모든 버튼의 기본 크기, 카드의 모서리 반경, 네비게이션 링크 텍스트 굵기를 글로벌하게 변경
• Tailwind CSS v4의 @theme directive 중심 아키텍처로 CSS 변수 기반 토큰 시스템 구축
• @nuxt/fonts 통합으로 선언된 폰트 자동 로드 및 최적화 (수동 link 태그나 Google Fonts 보일러플레이트 제거)

Key Takeaway

Nuxt UI v4의 3계층 테마 아키텍처(설계 토큰 → 의미론적 매핑 → 컴포넌트 오버라이드)는 테마를 한 곳에 집중시키고 CSS 오버라이드 없이 토큰 기반의 확장 가능한 설계 시스템을 구현할 수 있게 한다.