화면마다 색을 직접 적으면(여기는 #ff493b, 저기는 빨간 utility class), 브랜드를 바꾸거나 다크 테마를 더할 때 하나하나 찾아 고쳐야 합니다. Akan은 색에 용도로 이름을 붙이고, 모든 화면이 그 이름을 쓰게 해서 이 문제를 피합니다.

Akan은 Tailwind CSS와 시맨틱 디자인 토큰 계층, 그리고 akanjs/ui 프리미티브를 기본 스타일링 기반으로 사용합니다. 그래서 앱 화면은 모든 색을 하드코딩하지 않고 primary, background, warning, destructive 같은 의도로 말합니다. 두 도구는 일을 이렇게 나눕니다:

토큰은 page/styles.css에 선언하고, 이 파일이 Tailwind와 Akan UI 스타일도 함께 import합니다. 그 파일은 아래 '테마 시스템 선언 방식'에서, recipe 계층은 UI 레시피 문서에서 다룹니다.

처음부터 따로 디자인한 페이지는 조금씩 어긋납니다. 버튼은 옆 페이지보다 약간 더 둥글고, border는 약간 더 옅어집니다. 그래서 앱의 기본 컴포넌트 스타일을 먼저 정의하고, 페이지는 그 컴포넌트를 조립하기만 하게 만드세요.

이렇게 만든 블록에는 색 값이 하나도 없고, 토큰 이름과 recipe만 있습니다:

테마를 바꾸면 블록 전체가 알아서 다시 칠해집니다. 안의 모든 클래스가 색이 아니라 토큰을 가리키기 때문입니다.

컴포넌트는 bg-primary라고 한 번만 적습니다. 그것이 어떤 빨강인지는 앱 스타일 진입점이라는 파일 하나에서, 테마마다 한 번씩 정합니다. 선언은 네 단계입니다:

글자가 올라가는 색에는 그 글자를 위한 -foreground 짝이 있습니다. bg-primary에는 text-primary-foreground가 짝이므로, primary 버튼 위 글자는 어느 테마에서나 잘 읽힙니다.

테마를 따라가면 안 되는 색도 있습니다. 카카오 로그인 버튼은 라이트 테마에서도 다크 테마에서도 카카오 노랑입니다. 라이브러리의 컴포넌트에 이런 고정 색이 필요하면 라이브러리가 직접 선언합니다:

그 라이브러리에 닿는 앱은 이 파일을 자동으로, 자기 스타일시트보다 먼저 가져갑니다. 그래서 같은 변수를 둘 다 선언했다면 앱이 최종 결정권을 가집니다. 손으로 import할 것이 없고, 새 앱이 빠뜨릴 수도 없습니다.

폰트는 루트 레이아웃에서 한 번 선언하고, 그다음부터는 다른 Tailwind 클래스처럼 씁니다. rootLayout() 체인의 .fonts() 단계에 배열을 넘기며, 항목마다 세 필드를 적습니다:

이제 각 이름이 클래스가 됩니다. 클래스를 주지 않은 글자는 기본 폰트, 여기서는 Pretendard를 씁니다: