시작하기

토큰 아키텍처

토큰은 Primitive → Semantic → Platform 3계층으로 구성됩니다. 테마(라이트·다크)와 플랫폼(POS·키오스크 등)은 컴포넌트 코드 수정 없이 토큰 값만 바꿔 대응합니다.

3계층 구조

Layer 1

Primitive

원시 값. 이름에 의미가 없고 컴포넌트에서 직접 쓰지 않습니다.

--purple-600: #7c3aed
--grey-900: #191f28
--radius-lg: 12px

Layer 2

Semantic

역할 기반 이름. 라이트/다크에서 값이 바뀝니다.

--brand → purple-600
--fg-strong → grey-900
--negative → red-500

Layer 3

Platform

data-platform 속성으로 밀도가 바뀝니다.

--control-h-md: 36 | 56 | 72
--control-fs-md: 13 | 17 | 22
--touch-min: 32 | 48 | 64

네이밍 규칙

카테고리	패턴	예시
배경	--bg-{level}	--bg-canvas · --bg-subtle · --bg-muted · --bg-inverse
표면	--surface[-{state}]	--surface · --surface-raised · --surface-sunken
전경(텍스트)	--fg[-{emphasis}]	--fg-strong · --fg · --fg-muted · --fg-subtle · --fg-disabled
선	--line[-{emphasis}]	--line · --line-subtle · --line-strong
브랜드	--brand[-{state}]	--brand · --brand-hover · --brand-subtle · --brand-text
상태	--{status}[-subtle\|-text]	--positive · --negative-subtle · --warning-text
시각화	--viz-{n} · --viz-seq-{n}	--viz-1 … --viz-7 · --viz-seq-0 … 6
플랫폼	--control-{prop}-{size}	--control-h-lg · --control-fs-sm · --table-row-h

플랫폼별 토큰 값

토큰	Admin · Console · Sales	App · QR	POS	KIOSK
--control-h-sm	32	38	48	60
--control-h-md	36	48	56	72
--control-h-lg	44	54	64	88
--control-h-xl	52	58	76	104
--control-fs-md	13	15	17	22
--control-radius	8	12	12	16
--table-row-h	44	56	60	80
--touch-min	32	44	48	64

단위는 px입니다. 컴포넌트는 h-[var(--control-h-md)]처럼 토큰만 참조하므로, 같은 <Button size="md">가 POS에서는 56px, 키오스크에서는 72px로 렌더링됩니다.

Figma 동기화 (tokens.json)

packages/tokens/tokens.json

{
  "semantic": {
    "fg": {
      "strong": { "$type": "color", "$value": "{grey.900}", "$extensions": { "mode": { "dark": "#f4f5f7" } } }
    },
    "brand": {
      "default": { "$type": "color", "$value": "{purple.600}", "$extensions": { "mode": { "dark": "#8b5cf6" } } }
    }
  },
  "platform": {
    "control-h-md": { "$type": "dimension", "$value": { "admin": "36px", "app": "48px", "pos": "56px", "kiosk": "72px" } }
  }
}