Token Studio JSON → Tailwind CSS 설계 토큰 가이드

IT쿠키·2026년 2월 5일

Token Studio JSON → Tailwind CSS 설계 토큰 가이드

이 문서는 Figma Tokens Studio에서 내보낸 JSON을 Tailwind CSS 및 프로젝트에 맞게 매핑하고, 원시(Primitive) 토큰과 시맨틱(Semantic) 토큰을 결합하여 TypeScript(.ts) 파일과 design-tokens.css를 생성·사용하는 방법을 설명합니다.

요약 리포트

항목	설명
입력	Token Studio에서 내보낸 `tokens.json` (TokenStudio.primitive + TokenStudio.semantic)
참조 해석	시맨틱 토큰의 `{base.black}`, `{purple.500}` 등을 전체 트리에서 검색해 실제 값(hex, px 등)으로 치환
Tailwind 매핑	색상(text/bg/border/icon), spacing, typography, borderRadius 등으로 구조화된 단일 객체로 병합
TypeScript 출력	`src/styles/design-tokens.ts` — `designTokens`, `textColors`, `tailwindColors` 등 export
CSS 출력	`src/styles/design-tokens.css` — `@theme inline` 내부에 `--color-*` 등 CSS 변수 정의
사용	`globals.css`에서 `@import '../styles/design-tokens.css'` 후 Tailwind 클래스 또는 `var(--color-*)` 사용
실행 명령	`pnpm sync:tokens` (입력: `src/token/tokens.json` → 출력: 위 .ts, .css)

1. 개요

목적

Figma Tokens Studio에서 정의한 디자인 토큰을 한 번만 내보내면, 스크립트가 자동으로:
- CSS 변수(design-tokens.css)를 생성하고
- TypeScript 객체(design-tokens.ts)를 생성하여
Tailwind CSS 및 코드베이스에서 일관되게 사용할 수 있게 합니다.

전체 흐름

Figma (Tokens Studio)
    → tokens.json 내보내기
        → sync-tokens-studio.ts 실행 (pnpm sync:tokens)
            → design-tokens.css (CSS 변수)
            → design-tokens.ts (TS 타입/객체)
                → globals.css에서 CSS import
                → Tailwind / 컴포넌트에서 사용

2. Token Studio JSON 구조

2.1 기본 형식

Tokens Studio에서 Single file + All token sets로 내보내면 대략 다음과 같은 루트 구조를 가집니다.

{
  "TokenStudio": {
    "primitive": { ... },
    "semantic": { ... }
  }
}

TokenStudio: 이 프로젝트에서 사용하는 토큰 세트의 루트 이름입니다.
primitive: 색상/크기/타이포그래피의 원시 값 (예: #604fed, 8, 16px).
semantic: 용도별 시맨틱 토큰 (예: 텍스트 색상, 배경 색상, 간격). 많은 경우 primitive를 참조합니다.

소스 참조: 실제 구조는 src/token/tokens.json 1~70라인 근처 (TokenStudio → primitive.color.base, primitive.color.neutral 등)에서 확인할 수 있습니다.

2.2 토큰 값 형식 (W3C Design Tokens)

각 토큰은 다음 중 하나의 형태를 가집니다.

표준 (W3C)
$value, $type (및 선택적으로 $description)

"primary": {
  "$value": "#604fed",
  "$type": "color"
}

대체 형식
value, type (스크립트는 둘 다 지원)

"primary": {
  "value": "#604fed",
  "type": "color"
}

지원하는 $type 예: color, dimension, number, fontWeight, typography, border, shadow 등.

소스 참조: 타입 정의는 src/token/sync-tokens-studio.ts 35~56라인 (TokenValue, TokenType), 58~65라인 (RawTokenNode, RawTokenGroup, RawTokensRoot)에 있습니다.

2.3 참조(Reference) 문법

시맨틱 토큰이 원시 토큰을 참조할 때는 중괄호 경로를 사용합니다.

"text": {
  "primary": {
    "$value": "{base.black}",
    "$type": "color"
  },
  "info": {
    "$value": "{blue.500}",
    "$type": "color"
  }
}

{base.black} → primitive color의 base.black 값으로 해석됩니다.
{blue.500}, {neutral.700} 등도 같은 방식으로 전체 토큰 트리에서 경로 검색 후 해석됩니다.

스크립트는 이 참조를 실제 값(예: #18181b, #387adf)으로 치환한 뒤 CSS 변수와 TS 객체에 반영합니다.

소스 참조: 참조 해석 로직은 src/token/sync-tokens-studio.ts의 resolveReference() (168~196라인), findValueByPath() (200~275라인)에 있습니다. 실제 시맨틱 참조 예는 src/token/tokens.json 707~780라인 근처 (semantic.color.text.primary → {base.black} 등)에서 확인할 수 있습니다.

3. 원시 토큰 vs 시맨틱 토큰

3.1 원시 토큰 (Primitive)

정의: 색상 팔레트, 숫자 스케일, 단위 있는 크기 등 의미에 무관한 값.
위치: TokenStudio.primitive (예: primitive.color, primitive.size-unit, primitive.typography).
예시
- 색상: base.white, base.black, neutral.100 ~ neutral.900, purple.500, red.500 등.
- 크기: size-unit.4, size-unit.8, space.16.
- 타이포: font size.10, line height.14, font weight.regular.

역할: 시맨틱 토큰과 다른 원시 토큰이 참조하는 재료입니다. 디자인 시스템의 “원자” 값입니다.

3.2 시맨틱 토큰 (Semantic)

정의: 용도에 맞게 이름 지어진 토큰 (예: “본문 텍스트”, “브랜드 배경”, “위험 버튼”).
위치: TokenStudio.semantic (예: semantic.color.text, semantic.color.bg, semantic.size.space, semantic.typography.Heading).
예시
- text.primary → {base.black}
- text.info → {blue.500}
- bg.brand → {purple.500}
- border.danger → {red.500}

역할: 컴포넌트와 스타일에서는 시맨틱 이름만 사용하고, 실제 색/크기는 primitive 참조를 통해 한 곳에서 바꿀 수 있게 합니다.

3.3 결합 방식 (스크립트 동작)

sync-tokens-studio.ts의 transformTokens()는 대략 다음 순서로 동작합니다.

Primitive 색상 추출 → result.colors.primitive
Semantic 색상 추출 (이때 {base.black} 등 참조 해석) → result.colors.text, .bg, .border, .icon
Primitive + Semantic 크기 (spacing, container, border-radius, border-width 등) 추출 후 deepMerge
Typography
- primitive: font size, line height, letter spacing, font weight
- semantic: Heading / Body 프리셋 (조합된 타이포그래피)

즉, 원시와 시맨틱을 읽은 뒤 참조를 해석하고, 하나의 Tailwind 친화 구조로 합칩니다.

소스 참조: 결합 흐름은 src/token/sync-tokens-studio.ts의 transformTokens() (586~786라인)에서 처리됩니다. primitive/semantic 분리는 609~651라인(색상), 653~702라인(크기), 704~784라인(타이포그래피)에 있고, deepMerge()는 557~584라인에 정의되어 있습니다.

4. Tailwind CSS 매핑

4.1 목표 구조 (TailwindTokens)

스크립트가 만드는 내부 구조는 Tailwind의 테마 확장과 맞춰져 있습니다.

카테고리	용도	예시 키
`colors.primitive`	원시 색상 팔레트	`neutral.100`, `purple.500`
`colors.text`	텍스트 색상	`primary`, `secondary`, `danger`
`colors.bg`	배경 색상	`primary`, `brand`, `danger-bold`
`colors.border`	테두리 색상	`primary`, `danger`
`colors.icon`	아이콘 색상	`primary`, `brand`
`spacing`	margin/padding 등	`0`, `4`, `8`, `16`
`container`	컨테이너 너비	`240`, `960`
`fontSize`	폰트 크기	`10`, `12`, `14`
`lineHeight`	줄 높이	`14`, `20`
`fontWeight`	폰트 굵기	`regular`, `bold`
`letterSpacing`	자간	`normal`, `tight`
`borderRadius`	모서리 둥글기	`4`, `8`
`borderWidth`	테두리 두께	`1`, `2`
`typography.heading`	헤딩 프리셋	`5xl`, `4xl`, `lg`
`typography.body`	본문 프리셋	`lg`, `md`, `sm`

소스 참조: 위 구조의 TypeScript 타입은 src/token/sync-tokens-studio.ts 84~104라인 TailwindTokens 인터페이스에 정의되어 있습니다. 색상 추출은 extractColors() (278~318라인)에서 처리합니다.

4.2 키 이름 규칙

케이스: kebab-case (공백/슬래시/콜론은 하이픈으로 정규화).
색상: 시맨틱 이름 사용 권장 (예: text-primary, bg-brand).
사이즈: 숫자 스케일 (예: space-16, font-size-12).

이렇게 하면 Tailwind 유틸리티 클래스와 1:1로 대응하기 쉽습니다 (예: text-color-text-primary, bg-color-bg-brand).

5. TypeScript(.ts) 컴파일

5.1 생성되는 파일

경로: src/styles/design-tokens.ts
트리거: pnpm sync:tokens 실행 시 sync-tokens-studio.ts가 자동 생성합니다. (실제 실행 스크립트는 package.json 46라인: "sync:tokens": "node --import tsx src/token/sync-tokens-studio.ts")

소스 참조: TS 파일 생성 로직은 src/token/sync-tokens-studio.ts의 generateOutput() (979~1069라인)이며, main() (1072~1216라인)에서 design-tokens.ts를 쓰는 부분은 1184~1186라인입니다.

5.2 파일 내용 요약

designTokens
- 위의 TailwindTokens 구조를 그대로 가진 const 객체 (as const).
- JSON에서 참조가 해석된 최종 값만 들어 있습니다.
네임드 export (개발 편의용)
- textColors, bgColors, borderColors, iconColors
- primitiveColors
- spacing, container, fontSize, lineHeight, fontWeight, letterSpacing
- borderRadius, borderWidth
- headingTypography, bodyTypography
tailwindColors
- Tailwind theme.extend.colors 등에 넣기 위한 형태:
  - text, bg, border, icon (시맨틱)
  - ...primitiveColors (원시 색상 스프레드)

5.3 사용 예시 (코드)

import {
  designTokens,
  textColors,
  tailwindColors,
} from '@/styles/design-tokens';

// 특정 시맨틱 색상
const primaryText = textColors.primary; // "#18181b"
const brandBg = designTokens.colors.bg.brand; // "#604fed"

// Tailwind config에 전달
// theme: { extend: { colors: tailwindColors } }

주의: design-tokens.ts는 자동 생성 파일이므로 직접 수정하지 말고, Figma/Tokens Studio에서 수정한 뒤 pnpm sync:tokens로 다시 생성합니다.

소스 참조: 생성된 TS 예시는 src/styles/design-tokens.ts 1~80라인(헤더 + designTokens.colors.primitive), 646~712라인(네임드 export 및 tailwindColors)에서 확인할 수 있습니다.

6. design-tokens.css 생성 및 사용

6.1 생성 방식

경로: src/styles/design-tokens.css
생성 시점: pnpm sync:tokens 실행 시, generateCSSVariables()가 같은 TailwindTokens를 사용해 CSS 변수를 씁니다.

소스 참조: CSS 생성은 src/token/sync-tokens-studio.ts의 generateCSSVariables() (788~977라인)에서 이루어지며, main()에서 파일로 쓰는 부분은 1189~1193라인입니다.

6.2 CSS 변수 규칙

블록: @theme inline { ... } (Tailwind v4 호환).
이름 규칙:
- 원시 색상: --color-{팔레트}-{단계} (예: --color-neutral-100, --color-purple-500).
- 시맨틱 색상: --color-{역할}-{이름} (예: --color-text-primary, --color-bg-brand).
값: 참조가 이미 해석된 실제 색상/크기 값 (hex, px 등).

예시:

@theme inline {
  /* Primitive Colors */
  --color-base-white: #ffffff;
  --color-neutral-100: #f8f8f8;
  --color-purple-500: #604fed;

  /* Text Colors (semantic) */
  --color-text-primary: #18181b;
  --color-text-info: #387adf;

  /* Background Colors (semantic) */
  --color-bg-primary: #ffffff;
  --color-bg-brand: #604fed;

  /* Spacing, fontSize, borderRadius 등도 동일 방식 */
}

6.3 프로젝트에서 사용

globals.css에서 design-tokens.css를 가장 먼저 import합니다.

@import 'tailwindcss';
@import '../styles/design-tokens.css';
@source "./src/**/*.{ts,tsx,js,jsx,mdx}";

소스 참조: src/app/globals.css 1~4라인에 위와 같이 import가 정의되어 있습니다. 생성된 CSS 변수 예시는 src/styles/design-tokens.css 1~25라인(헤더 + @theme inline 및 primitive/text 색상)에서 확인할 수 있습니다.

이후:

Tailwind 유틸리티: @theme 덕분에 --color-* 등이 Tailwind 테마로 인식되어 text-color-text-primary, bg-color-bg-brand 같은 클래스로 사용할 수 있습니다.
순수 CSS: color: var(--color-text-primary);, background: var(--color-bg-brand); 처럼 직접 변수 참조 가능.

주의: design-tokens.css도 자동 생성 파일이므로 직접 수정하지 말고, 토큰은 Figma/Tokens Studio에서만 수정한 뒤 pnpm sync:tokens로 다시 생성합니다.

7. 워크플로우 요약

단계	작업	결과물
1	Figma Tokens Studio에서 토큰 정의 (primitive + semantic, 참조 사용)	-
2	Single file + All token sets로 Export → `src/token/tokens.json` 저장	`tokens.json`
3	터미널에서 `pnpm sync:tokens` 실행	`design-tokens.css`, `design-tokens.ts` 갱신
4	`globals.css`에 `@import '../styles/design-tokens.css';` 유지	앱/스타일에서 CSS 변수 사용
5	필요 시 `tailwindColors` 등을 Tailwind 설정에 연결	Tailwind 클래스로 토큰 사용

자주 쓰는 명령어

pnpm sync:tokens

입력: src/token/tokens.json (또는 스크립트가 찾는 다른 후보 경로). 후보 경로는 src/token/sync-tokens-studio.ts 20~31라인 TOKENS_INPUT_CANDIDATES, OUTPUT_DIR에서 확인할 수 있습니다.
출력: src/styles/design-tokens.css, src/styles/design-tokens.ts

8. 참고: 프로젝트 파일 구조

src/
├── token/
│   ├── tokens.json          # Tokens Studio에서 내보낸 JSON (수동 배치)
│   └── sync-tokens-studio.ts # 변환 스크립트 (실행: pnpm sync:tokens)
├── styles/
│   ├── design-tokens.css    # 자동 생성 — CSS 변수
│   └── design-tokens.ts    # 자동 생성 — TS 객체 및 export
└── app/
    └── globals.css          # design-tokens.css import

직접 편집: tokens.json (내보낸 뒤 필요 시 경로만 맞추면 됨), sync-tokens-studio.ts (로직/매핑 변경 시).
자동 생성이라 수정 금지: design-tokens.css, design-tokens.ts.

9. 소스 코드 참조

아래는 이 가이드에서 설명한 동작과 대응하는 실제 소스 파일·라인 요약입니다. 코드 읽기나 수정 시 함께 참고하면 됩니다.

구분	파일 경로	설명·주요 라인
입력 JSON	`src/token/tokens.json`	Token Studio 내보내기 결과. 루트 `TokenStudio` → `primitive` / `semantic` (1~70, 707~780 등).
변환 스크립트	`src/token/sync-tokens-studio.ts`	진입점·경로: 19~32. 타입: 35~65, 84~104. 참조 해석: `resolveReference` 168~196, `findValueByPath` 200~275. 색상 추출: `extractColors` 278~318. 병합: `deepMerge` 557~584. 메인 변환: `transformTokens` 586~786. CSS 생성: `generateCSSVariables` 788~977. TS 생성: `generateOutput` 979~1069. 실행: `main` 1072~1216, 출력 경로 1184~1193.
실행 명령	`package.json`	46라인: `"sync:tokens": "node --import tsx src/token/sync-tokens-studio.ts"`
CSS import	`src/app/globals.css`	1~4: `@import 'tailwindcss'`, `@import '../styles/design-tokens.css'`
생성 CSS	`src/styles/design-tokens.css`	자동 생성. 1~25: 헤더 + `@theme inline` 및 primitive/text 색상 변수 예시.
생성 TS	`src/styles/design-tokens.ts`	자동 생성. 1~80: 헤더 + `designTokens.colors.primitive`. 646~712: `textColors`, `bgColors`, `tailwindColors` 등 export.

함수·역할 매핑 (sync-tokens-studio.ts)

함수명	라인	역할
`resolveReference`	168~196	`{base.black}` 같은 문자열 참조를 실제 값으로 치환 (순환 참조 방지 포함).
`findValueByPath`	200~275	경로 문자열로 전체 토큰 트리에서 값 검색.
`extractColors`	278~318	raw 토큰 트리에서 color 타입만 재귀 추출.
`extractDimensions`	364~402	dimension/number 토큰 추출 (spacing, fontSize 등).
`deepMerge`	557~584	primitive + semantic 결과 병합.
`transformTokens`	586~786	`TokenStudio.primitive` / `.semantic` 읽어 TailwindTokens 한 덩어리로 변환.
`generateCSSVariables`	788~977	TailwindTokens → `@theme inline` + `--color-*` 등 CSS 변수 문자열 생성.
`generateOutput`	979~1069	TailwindTokens → `design-tokens.ts` 내용 문자열 생성.
`main`	1072~1216	JSON 읽기, 변환, 통계 출력, `.ts`/`.css` 파일 쓰기.

이 가이드로 Token Studio JSON → 원시/시맨틱 결합 → Tailwind 매핑 → TypeScript 컴파일 → design-tokens.css 생성·사용까지의 흐름을 한 번에 참고할 수 있습니다. 토큰 구조나 스크립트 경로가 바뀌면 이 문서를 함께 업데이트하는 것을 권장합니다.

IT쿠키

IT 삶을 사는 쿠키

이전 포스트

Tokens Studio(Figma) → Tailwind 동기화로 디자인 토큰을 Next.js에 붙이기

다음 포스트

Token Studio JSON → Tailwind CSS 설계 토큰 가이드

Token Studio JSON → Tailwind CSS 설계 토큰 가이드

요약 리포트

목차

1. 개요

목적

전체 흐름

2. Token Studio JSON 구조

2.1 기본 형식

2.2 토큰 값 형식 (W3C Design Tokens)

2.3 참조(Reference) 문법

3. 원시 토큰 vs 시맨틱 토큰

3.1 원시 토큰 (Primitive)

3.2 시맨틱 토큰 (Semantic)

3.3 결합 방식 (스크립트 동작)

4. Tailwind CSS 매핑

4.1 목표 구조 (TailwindTokens)

4.2 키 이름 규칙

5. TypeScript(.ts) 컴파일

5.1 생성되는 파일

5.2 파일 내용 요약

5.3 사용 예시 (코드)

6. design-tokens.css 생성 및 사용

6.1 생성 방식

6.2 CSS 변수 규칙

6.3 프로젝트에서 사용

7. 워크플로우 요약

자주 쓰는 명령어

8. 참고: 프로젝트 파일 구조

9. 소스 코드 참조

함수·역할 매핑 (sync-tokens-studio.ts)

Tokens Studio(Figma) → Tailwind 동기화로 디자인 토큰을 Next.js에 붙이기

Next.js + TanStack Table + Tailwind로 만드는 반응형 Data Table 컴포넌트

0개의 댓글