토큰

토큰 계층

전체 의존 관계:

Figma variable → Base → Semantic → State → Component → Platform → Tailwind/shadcn

계층을 여섯으로 나눈 이유

처음에는 Base → Semantic → Component → Tailwind, 네 계층이었다. 문제 세 가지가 생기기 전까지는 잘 돌아갔다.

State와 Platform 계층은 새 값을 추가하지 않는다. 대신 값이 어떻게 바뀌는지에 대한 규칙을 추가한다. 예전에 손으로 여러 번 반복해 쓰던 게 바로 이 부분이다.

계층 규칙

• 토큰은 바로 아래 계층이나 그보다 더 아래 계층만 참조할 수 있다. 위 계층은 참조할 수 없다.
• 컴포넌트는 Base 토큰을 참조하지 않는다. 컴포넌트에 원시 값이 필요하다면 예외를 둘 게 아니라 빠진 시맨틱 토큰을 만들어야 한다.
• State 계층은 새 팔레트가 아니라 변환을 정의한다. Hover 값을 시맨틱 부모에서 끌어낼 수 없다면, 시맨틱 토큰이 잘못된 것이다.
• Platform 계층은 기존 토큰을 다시 매핑만 한다. 다른 곳에 없는 토큰을 새로 정의하지 않는다.
• "Tailwind"나 "shadcn"이라는 이름을 알아도 되는 건 Bridge 계층뿐이다. 그 아래 계층은 모두 프레임워크와 무관하다.

이름 규칙

--ds-{group}-{role}-{variant}-{state}
     │       │       │         └── hover, active, selected, disabled
     │       │       └── sm / md / lg / primary / secondary
     │       └── bg, text, border, icon, shadow, radius
     └── palette group, semantic role, or component name

모든 토큰 이름은 --ds-로 시작한다. 같은 범위에서 Tailwind 자체 변수와 함께 쓰여도 이름이 겹치지 않는 건 이 접두어 덕분이다.

Figma variable → Base 토큰

Figma variable 컬렉션은 Base 계층과 1:1로 대응한다. MCP 서버가 컬렉션 경로가 그대로 담긴 variable 이름을 넘겨주므로, 기계적으로 바꾸면 된다.

Semantic 계층부터 위는 Figma가 아니라 코드에서 작성한다. 원시 값은 Figma가, 의미는 DS가 관리한다. 그래서 Figma 스타일 이름이 바뀌어도 컴포넌트는 깨지지 않는다. 영향을 받는 건 언제나 Base 토큰 하나뿐이다.

Base 토큰

의미가 없는 원시 값이다. 상위 계층에서 참조하는 용도로만 존재한다.

색

팔레트 그룹은 일곱 개이고, 그룹마다 900(가장 어두움)부터 50(가장 밝음)까지 10단계가 있다.

선언된 70단계 전체다. 한 단계 어두운 Hover, 400 단계 테두리, 700 단계 아이콘처럼 시스템 곳곳에서 끌어 쓰는 값은 ds.css를 열지 않아도 이 표에서 모두 찾을 수 있다.

여기에 --ds-white(#FFFFFF)와 --ds-hero-gradient(linear-gradient(180deg, #0A4ABF, #0F62FE))가 추가된다. 후자는 시스템에서 유일한 그라디언트이고, 마케팅 화면에만 쓴다.

회색 두 단계는 일부러 Tailwind 기본값과 다르게 잡았다. gray-500(#636971, 보통은 #6B7280)과 gray-400(#727780, 보통은 #9CA3AF)이다. 흐린 텍스트와 placeholder가 흰 배경에서 4.5:1을 넘을 때까지 둘 다 어둡게 했다. 전체 대비 표는 Color 참고.

간격

4px 기본 단위에 10단계다. 모든 단계가 4의 배수이고, 중간 단계나 임의의 값은 없다.

타이포그래피

Minor third 스케일(1.200)을 4px 그리드에 맞췄다.

패밀리와 굵기:

시스템 폰트는 임시방편이 아니라 일부러 택한 제약이다. Senco 사용자는 데이터 요금이 나가고 불안정한 연결을 쓴다. 웹폰트는 렌더링을 막는 요청이면서 시스템에 필요한 건 아무것도 주지 않는다. 커스텀 서체가 Figma MCP 파이프라인을 거치면 사라지는 문제도 함께 피할 수 있다.

모양과 높이

그림자 불투명도는 최대 8%다. Senco에서 높이는 화려한 효과가 아니라 층위를 보여 주는 수단이다. 모달은 다른 재질이 아니라 페이지 위에 떠 있는 것으로 보여야 한다.

모션

크기

Z-index

6단계로 고정된 스케일이다. 어떤 컴포넌트도 이 밖의 z-index를 새로 만들 수 없다.

Toast를 모달보다 위에 둔 건 의도한 것이다. 확인 다이얼로그가 열려 있어도 송금 실패 메시지는 보여야 한다.

Semantic 토큰

의도를 담은 별칭이다. 컴포넌트는 Base 계층이 아니라 이 계층을 참조한다. 이렇게 한 단계를 거치기 때문에 테마를 바꿀 수 있다.

색

On 색

채워진 표면 위에 올리는 텍스트와 아이콘 색이다. 흰 글자가 읽힐지 말지를 컴포넌트마다 짐작하지 않게 하려고 둔다.

피드백

피드백 상태마다 배경, 테두리, 텍스트, 아이콘 토큰 네 개가 한 세트라서, 알림마다 색을 따로 조합할 필요가 없다.

Tip은 info가 아니라 accent를 기반으로 한다. Info는 시스템이 보내는 메시지이고, tip은 Senco가 건네는 말이다. 색조를 다르게 두어야 복잡한 송금 화면에서 둘이 섞여 보이지 않는다.

간격과 타이포그래피 별칭

시맨틱 간격은 크기가 아니라 관계에 이름을 붙인다. 이 이름들은 변수로 선언된 게 아니라 관례로 쓰고 있는 것이다. 일관성을 지키려고 관계를 문서화해 두었고, 토큰으로 정식화하는 건 남은 작업이다.

State 토큰

State 계층은 시맨틱 토큰이 상호작용에 따라 어떻게 바뀌는지 정의한다. 따로 팔레트를 두지 않는다. 모든 상태 값은 문서화된 규칙에 따라 시맨틱 부모에서 끌어낸다.

변환 규칙

어느 포커스 형태를 쓸지는 질문 하나로 정한다. 평소에 테두리가 보이는 컨트롤인가? 입력, 셀렉트, 입력 그룹, 테두리 있는 카드는 테두리 형태를 쓴다. 버튼, 링크, 토글 항목, 탭, 스위치, 목록 행, 스크롤 영역은 외곽선을 쓴다. 3:1을 넘어야 하는 건 테두리나 외곽선이다. 20% 후광은 장식이고, 흰 배경 대비 1.33:1 정도다.

규칙마다 한 번만 정의하기 때문에, 버튼, 연락처 카드, 사이드바 항목의 Hover 동작은 비슷해 보이는 구현 세 개가 아니라 확실히 같은 동작이 된다.

구현된 State 토큰

포커스 링은 고정 rgba 값 대신 color-mix()로 만든다. 그래서 다크 모드에서 --ds-focus를 다시 매핑하면 링도 따로 손대지 않고 맞는 색이 된다. 변환 자체가 토큰이라서 테마가 바뀌어도 변환은 그대로 유지된다.

컴포넌트 토큰의 상태 짝

상태가 있는 컴포넌트 토큰은 상태를 이름에 명시하고, 짝을 맞춰 정의한다.

--ds-actionbtn-primary-bg:          var(--ds-primary);
--ds-actionbtn-primary-bg-hover:    var(--ds-primary-hover);
--ds-actionbtn-primary-shadow:      var(--ds-shadow-sm);
--ds-actionbtn-primary-shadow-hover: var(--ds-shadow-md);

-hover 변형만 있고 기본 변형이 없는 컴포넌트 토큰은 버그다. 리뷰에서 짝이 없는 상태로 걸러 낸다.

유틸리티 접두어

마크업에서는 Tailwind 접두어 문법으로 상태를 적용하고, Bridge 계층을 거쳐 값이 정해진다.

포커스에는 focus:가 아니라 focus-visible:을 쓴다. 버튼을 마우스로 클릭했을 때는 링이 남지 않아야 하고, Tab을 눌렀을 때는 남아야 한다.

Component 토큰

컴포넌트 하나에만 쓰는 토큰이다. 시맨틱 토큰과 상태 토큰을 조합하며, 특정 컴포넌트만의 결정은 여기에만 둘 수 있다.

버튼: 컴포넌트 셋, 토큰 세트 셋

--ds-actionbtn-*은 일반 버튼용이 아니다. 대시보드의 액션 타일용이다. 라벨 위에 40px 원형 아이콘이 있는, 높이 72px짜리 카드다. 이걸 일반 버튼 토큰으로 오해하는 바람에 파일 세 곳에서 radius가 6px이냐 9999px이냐로 서로 어긋났다. 그래서 어느 컴포넌트 토큰인지 여기에 분명히 적어 둔다.

Action tile

Pill button

**Button (default)**에는 컴포넌트 블록이 없다. --ds-primary / --ds-primary-hover / --ds-on-accent / --ds-border를 --ds-radius-md와 직접 조합한다. Danger variant에도 컴포넌트 토큰이 없어서, 지금은 --ds-red-600을 바로 참조한다. 이 계층 규칙에서 금지하는 Base 참조다. 아래 알려진 drift에 적어 두었다.

Input

Notice / Feedback

피드백 컴포넌트는 시맨틱 피드백 세트를 그대로 쓰고, 자체 컴포넌트 토큰을 두지 않는다. 일부러 그렇게 했다. 알림에 별도 색이 필요하다면 시맨틱 세트가 덜 갖춰졌다는 뜻이다.

Senco 컴포넌트

제품 고유 컴포넌트의 컴포넌트 토큰 블록이 가장 크다. 일반 라이브러리에는 없을 도메인 결정이 담겨 있기 때문이다.

카메라와 QR 표면은 테마 재매핑에서 유일하게 문서화한 예외다. 라이트 모드에서 뷰파인더가 뒤집히면 얻는 건 없고 사용자가 익숙한 기준만 잃는다. 그래서 이 토큰들은 일부러 고정 값으로 둔다. CSS를 뒤지다 발견하게 두지 않고 여기에 적어 둔다.

Platform 토큰

Platform 계층은 실행 환경에 맞춰 값을 정한다. 새 값을 만들지 않고 이미 있는 토큰만 다시 매핑하므로, 테마를 추가해도 컴포넌트가 깨질 일이 없다.

테마에 따른 값

다크 모드는 .ds-layout.ds-dark에서 시맨틱 계층을 다시 매핑해 적용한다.

다크 모드에서는 브랜드 파랑이 밝아진다. #0F172A 위의 #0F62FE는 3.57:1로, 텍스트 기준인 4.5:1에 못 미친다. #458DFF는 5.53:1로 통과한다. 기본 팔레트는 그대로 두고 시맨틱 별칭만 바꾼다.

Primary 채움을 밝게 하면서 생긴 문제도 같은 계층에서 처리한다. #458DFF 위의 흰 라벨은 3.23:1이라서, --ds-on-accent를 #0F172A로 다시 매핑한다. 버튼 컴포넌트는 바뀌지 않고 그대로 --ds-on-accent를 읽는다. Themes 참고.

동작 줄이기

Platform 블록 하나로 시스템 전체의 애니메이션을 끈다. 컴포넌트마다 따로 처리하지 않는다.

@media (prefers-reduced-motion: reduce) {
  .ds-layout *,
  .ds-layout *::before,
  .ds-layout *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

뷰포트에 따른 값

브레이크포인트는 컴포넌트가 정하는 게 아니라 Platform 계층의 입력값이다. 컴포넌트는 컨테이너 토큰을 읽기만 하고, 어떤 컨테이너를 적용할지는 Platform 계층이 정한다. 아래 반응형 브레이크포인트 토큰 참고.

범위별 플랫폼 대상

프로토타입 범위는 임시 우회책이 아니라 정식 플랫폼 대상이다. 프로토타입 프레임은 Senco 앱을 나타내고, 앱은 자신을 담은 페이지와 별개로 자체 테마 상태를 갖는다.

밀도: 정의만 하고 구현하지 않음

이 계층에는 --ds-space-*와 컨트롤 높이를 다시 매핑하는 compact, cozy 밀도 변형 자리를 마련해 두었다. 지금 ds.css에는 둘 다 구현돼 있지 않다. Senco 화면은 한 번에 한 가지 일만 하는 모바일 우선 화면이라, 밀도 변형을 만들 만큼 필요했던 적이 없다. 나중에 데스크톱 거래 테이블에서 필요해지면 컴포넌트별 덮어쓰기가 아니라 Platform 계층에 넣을 수 있도록 자리만 문서로 남겨 둔다.

컴포넌트 라이브러리 통합

여섯 번째이자 가장 바깥 계층인 Bridge다. Senco는 shadcn(base-nova 스타일)을 기반으로 한다. CSS 변수 브리지가 .ds-layout 범위 안에서 shadcn과 Tailwind 변수를 Senco 시맨틱 토큰에 연결한다.

사이드바와 차트 브리지도 같은 방식이다(--sidebar-*, --chart-1 … --chart-5).

이 브리지는 ds.css에 있어서, shadcn 컴포넌트를 하나하나 덮어쓰지 않아도 Senco 브랜딩이 적용된다.

브리지는 상속에 의존한다

브리지는 범위 루트에 한 번만 선언하고, 모든 컴포넌트가 상속으로 값을 읽는다. 그런데 호스트 애플리케이션의 테마가 .theme이 아니라 .theme *로 작성돼 있는 식으로, 자손 요소에서 같은 프레임워크 변수를 다시 선언하면 Senco 값이 호스트 값으로 소리 없이 바뀐다. 색 말고는 깨진 데가 없어 보여서 알아채기 어렵다. 이런 규칙이 있는 호스트에 시스템을 넣을 때는, 브리지가 정의하는 변수에 한해 범위에서 상속을 다시 지정한다.

.ds-scope.host-theme *:not(.prototype-scope) {
  --primary: inherit;
  --primary-foreground: inherit;
  /* …every variable the bridge declares */
}

확인은 한 번이면 된다. 범위 안의 Primary 버튼이 라이트 모드에서 --ds-primary 색으로, 테마를 바꾼 뒤에는 다크 값으로 보여야 한다. 두 테마에서 색이 같다면 브리지가 거기까지 닿지 않는 것이다.

브리지를 세부 구현이 아니라 계층으로 둔 이유

6계층 아래는 모두 특정 기술과 무관하다. Senco를 Tailwind에서 CSS-in-JS나 네이티브 플랫폼으로 옮기려면 브리지 파일 하나만 다시 쓰면 된다. DS는 무엇이 자신을 렌더링하는지 모르고, 이 계층은 그 성질을 지키려고 존재한다.

타이밍과 임계값

애니메이션이 아닌 시간 값이다. 스펙에 "debounce한다", "throttle한다", "타임아웃이 있다"고만 쓰면, 요구사항은 적었지만 개발자가 스스로 알아낼 수 없는 단 하나, 숫자를 빼먹은 셈이다. 개발자 둘이 서로 다른 숫자를 고르면, 환율 견적의 경우 화면에 가격이 두 가지로 뜬다.

아래는 시스템 기본값이다. 제품의 특정 화면에서 값을 바꿀 수는 있지만, 값을 적지 않고 넘어갈 수는 없다.

환율 만료는 미리 보여 준다

견적은 0초가 되는 순간 말없이 만료되지 않는다. 유효 시간이 절반 남았을 때부터 남은 시간을 보여 주고, 만료되면 오래된 숫자 대신 새로 고침 액션을 보여 준다. Amount input과 Transfer flow 참고.

숫자 표시 정밀도

예전에는 환율 행에 "전체 정밀도"라고만 적혀 있었다. 유효숫자를 6자리로 맞춰야 송금 경로가 달라도 환율을 비교할 수 있다. 소수점 자릿수를 고정하면 0.923145가 잘리거나 1,650.00에 쓸데없는 0이 붙는다.

통화의 최소 단위

금액 정밀도는 통화의 최소 단위가 정한다. 위의 예시 세 개가 규칙의 전부는 아니다. 시스템은 Intl.NumberFormat을 통해 ISO 4217에서 최소 단위를 가져오고, 직접 처리해야 하는 예외가 두 가지 있다.

알려진 공백: 아직 토큰화하지 않음

위 값은 하나도 ds.css에 --ds-*로 선언돼 있지 않다. 여기 적은 계약을 컴포넌트 로직에서 구현하고 있다. 토큰(--ds-timing-settle, --ds-timing-quote-fiat)으로 만드는 건 남은 작업이다. 그 전까지는 이 표가 유일한 기준이고, 자기 마음대로 숫자를 고른 컴포넌트는 결함이다.

반응형 브레이크포인트 토큰

브레이크포인트별로 적용되는 컨테이너 폭:

규칙

• 컴포넌트 스타일에 원시 값을 하드코딩하지 않는다.
• 항상 바로 아래 계층을 참조한다. 위 계층을 참조하지 않는다.
• Base 토큰은 상위 계층에서 참조하는 용도로만 존재한다.
• 컴포넌트는 Base 토큰을 참조하지 않는다. 그럴 일이 생겼다면 진짜 문제는 시맨틱 토큰이 빠져 있다는 것이다.
• State 토큰은 문서화된 변환 규칙으로 시맨틱 부모에서 끌어낼 수 있어야 한다.
• -hover가 붙은 컴포넌트 토큰에는 반드시 -hover가 붙지 않은 기본 짝이 있어야 한다.
• Platform 덮어쓰기는 다시 매핑만 한다. 테마 블록 안에서 새로 생긴 토큰은 버그다.
• 모든 상호작용 요소는 Hover, Focus-visible, Disabled 상태를 정의한다.
• shadcn 컴포넌트는 브리지를 통해 Senco 토큰을 물려받는다. 개별로 덮어쓰지 않는다.

토큰 추가하기

1. 기존 시맨틱 토큰으로 해결되는가? 그렇다면 여기서 멈춘다.
2. 원시 값이고 여러 곳에서 쓸 값이라면 Base에 추가하고 Semantic에 별칭을 만든다.
3. 상호작용에 따라서만 달라진다면 State에 변환 규칙으로 둔다.
4. 딱 한 컴포넌트에만 해당한다면 그 컴포넌트 블록에 추가한다. 단, 1–3이 모두 해당하지 않을 때만.
5. 결정을 기록한다. 이유를 적어 두지 않은 토큰은 석 달 안에 중복된다.

토큰 폐기하기

토큰 제거는 한 번에 하지 않고 반드시 두 단계로 나눈다. 먼저 ds.css에서 폐기 표시를 하고 대체할 토큰 이름을 옆에 적은 뒤, 한 릴리스 동안 별칭으로 남겨 두었다가 삭제한다. 바로 지우면 스펙 파일 29개와 모든 프로토타입을 뒤지는 일이 된다.

알려진 drift

drift는 숨기지 않고 목록으로 남긴다. 이 문서를 읽는 에이전트는 어떤 문장이 지켜야 할 계약이고 어떤 문장이 앞으로의 의도인지 알아야 한다. 문서에 없는 공백이 있으면, 틀린 코드를 자신 있게 만들어 낸다.