suspense

Tailwind @theme로 디자인 토큰 관리하기

1. 배경

프로젝트 할때 팀원이 만들어 두어서 그냥 가져다가 쓰긴 했고, 이게 스타일 통일을 위해 사용한다는 것은 알고 있었지만, 정확히 어떻게 만들고, 어떻게 사용하는지 잘 몰랐어서 정리를 해보게 되었다.

2. 핵심 개념

@theme는 색상, 폰트 등 공통 스타일을 CSS 변수 형태로 정의하고

프로젝트 전반에서 재사용할 수 있도록 하는 설정이다.

@theme {
  --color-primary-100: #2b7f59;
  --color-background-100: #f3fcf8;
}

이렇게 정의된 값은 Tailwind 클래스에서 다음과 같이 사용할 수 있다.

<div className="bg-primary-100" />

3. 기존 방식과의 차이

기존 방식

<div className="bg-[#2b7f59]" />

• 색상 값이 하드코딩됨
• 동일한 색상 반복 사용
• 유지보수 어려움

개선 방식

--color-primary-100: #2b7f59;

<div className="bg-primary-100" />

• 색상 의미 기반으로 사용 가능
• 값 변경 시 한 곳만 수정
• 디자인 일관성 유지

4. 구조 설계

1) 폰트

--font-sans: var(--font-pretendard), system-ui, ...

• 프로젝트 기본 폰트 통일

2) Primary 색상

--color-primary-100 ~ 500

• 동일 계열 색상을 단계별로 정의
• 버튼, 강조 요소 등에 사용

3) Background 색상

--color-background-100 ~ 400

• 배경 전용 색상 분리
• UI 계층 구조 표현에 활용

5. 적용 효과

• 색상/폰트 관리 일원화
• UI 일관성 확보
• 유지보수 비용 감소
• 다크모드 및 테마 확장 가능

6. 느낀 점

초기에는 단순한 CSS 변수처럼 보였지만,

프로젝트 규모가 커질수록 디자인 시스템의 중요성을 체감하게 되었다.

특히 Tailwind와 결합했을 때

스타일을 “값”이 아니라 “의미”로 사용할 수 있다는 점이 가장 큰 장점이었다.

한 줄 정리

@theme는 디자인 값을 하드코딩하지 않고, 의미 있는 토큰으로 관리하기 위한 구조다.