02 · Design Style / 디자인 토큰

디자인 토큰Design Token

주님의교회 PCL 디자인 시스템의 모든 시각 값은 토큰으로 표현됩니다. Primitive → Semantic → Component 3단계 구조로, 위로 갈수록 구체적이고 아래로 갈수록 의미적입니다. 이 구조 덕분에 브랜드 교체가 시맨틱 한 줄로 끝납니다.

3단계 구조

토큰을 한 덩어리로 관리하면 수백 개가 뒤섞여 금방 관리 불능이 됩니다. 주님의교회 PCL 디자인 시스템은 계층을 나눠 각 층의 역할을 명확히 합니다 — 원시값(Primitive), 의미값(Semantic), 컴포넌트값(Component).

Tier 01

Primitive

원시 팔레트

가공되지 않은 색·크기·그림자 값. 브론즈 팔레트 스케일(bronze-50 ~ bronze-900), 크기 스케일(xs~2xl), 그림자 4단계 등. 의미는 없고 숫자만 있습니다.

--color-navy-700 = #5e3a19 /* Deep Bronze */

--radius-md = 8px

--shadow-sm = ...

Tier 02

Semantic

의미 토큰

UI 역할 기반 이름. brand · accent · surface · text · border 등. 컴포넌트는 이 계층만 참조합니다. 브랜드를 바꿀 때 덮어쓰는 곳도 여기.

--color-brand = #5e3a19 /* Deep Bronze */

--color-accent = #955e29 /* 로고 Bronze */

--color-text = #100e08 /* Ink */

Tier 03

Component

컴포넌트 토큰

특정 컴포넌트에만 쓰이는 지역 토큰. button-bg · card-border · modal-shadow 등. 기본값은 semantic을 참조하되, 필요하면 컴포넌트 단위로 덮어쓸 수 있습니다.

--button-primary-bg = var(--color-accent)

--card-border = var(--color-border)

--modal-shadow = var(--shadow-lg)

토큰 흐름 예시

버튼의 배경색이 화면에 그려지기까지 세 층을 지납니다. 이 흐름을 따라가면 왜 시맨틱 한 줄만 바꿔도 브랜드가 전체 재매핑되는지 보입니다.

/* 01. Primitive — 원시값 (주님의교회 PCL 로고 Bronze) */
--color-blue-500: #955e29;

/* 02. Semantic — UI 역할 */
--color-accent: var(--color-blue-500);

/* 03. Component — 특정 컴포넌트 */
--button-primary-bg: var(--color-accent);

/* 실제 컴포넌트 */
.btn-primary {
  background: var(--button-primary-bg);
}

네이밍 규칙

토큰 이름은 영역 → 역할 → 상태 순으로 짓습니다. Tailwind v4의 @theme 블록 내 CSS 변수 규약을 따릅니다.

이름 짓기 체크리스트

시작은 영역 — color / radius / shadow / space / duration / ease 중 하나.
다음은 역할 — brand · accent · surface · text · border (semantic) 또는 내부 팔레트 스케일(primitive). ※ 주님의교회 PCL의 내부 팔레트 이름은 Foundry 업스트림 동기화를 위해 navy-*·blue-*·gray-*를 유지하되 값은 모두 bronze·stone 톤으로 재매핑되어 있습니다.
끝은 상태 — hover · active · disabled · inverse · muted · subtle. 필요할 때만.
컴포넌트 토큰은 prefix — --button-*, --card-*. 글로벌 공간을 오염시키지 않도록.

다른 브랜드로 포크하기

다른 브랜드로 이 시스템을 포크할 때, 건드릴 곳은 딱 두 군데입니다 — 로고 컴포넌트와 globals.css의 시맨틱 블록. 프리미티브와 컴포넌트 토큰은 그대로 둡니다. (주님의교회 PCL 자체도 Foundry 포크 이며 동일한 절차로 bronze 팔레트를 주입했습니다.)

/* app/globals.css — @theme 블록에서 ONLY semantic만 덮어씀 */

/* 프리미티브 팔레트를 확장 (새 브랜드 색 주입) */
--color-wine-500: #6b2d44;
--color-wine-700: #4a1e30;
--color-gold-500: #c79650;

/* 시맨틱만 재매핑 — 이게 핵심 */
--color-brand: var(--color-wine-700);
--color-accent: var(--color-gold-500);

/* 나머지(surface · border · text)는 Foundry 기본 유지 */
/* 컴포넌트 코드는 한 줄도 안 건드림 */

토큰 원칙

1. 컴포넌트는 Semantic만 참조 — Primitive를 직접 쓰지 않습니다. Semantic이 없으면 먼저 Semantic을 만들고 씁니다.

2. Hex·숫자를 인라인으로 쓰지 않기 — 색이든 크기든 토큰을 경유합니다. 인라인 값이 하나라도 있으면 브랜드 교체가 깨집니다.

3. 새 토큰 추가 전, 재활용 가능성 확인 — 비슷한 토큰이 이미 있으면 쓰세요. 토큰 개수가 늘면 의사 결정 비용이 기하급수적으로 증가합니다.