Design Tokens Transformer

design-tokens-transformer — 3계층 토큰 양방향 변환

개요

브랜드 토큰은 소비처마다 다른 형태를 요구합니다. 이 스킬은 **동일한 브랜드 진실(색·타이포·spacing·radius·shadow·motion)**을 3계층으로 인코딩·변환합니다. L1(DTCG)이 SSOT이고, L2/L3은 파생물이며, 역방향 추출과 라운드트립 검사로 계층 간 정합을 보장합니다.

이 SKILL.md는 3계층 스키마·양방향 변환 규칙·라운드트립 검사·사용 예시를 모두 포함합니다. 색·폰트 값은 브랜드 무관 플레이스홀더(#RRGGBB, <BrandFont>)로 표기하며, 실제 브랜드 값은 변환 입력(DTCG 소스)에서 주입됩니다.

트리거 키워드

DTCG 토큰 변환, 3계층 토큰 매핑, CSS custom properties 생성, shadcn semantic 롤, Tailwind v4 @theme, 토큰 라운드트립, design tokens transformer

3계층 모델

L1 — DTCG SSOT 스키마

• W3C 포맷: 각 토큰은 $value / $type / $description 보유
• 계층적 그룹: color.{brand,neutral,semantic,dark,gradient} · typography.{family,weight,size,lineHeight,letterSpacing} · spacing · radius · shadow · motion.{duration,easing} · container · logo
• $description은 출처·의미를 기록 → 브랜드 진실 원천

DTCG 그룹별 최소 토큰 세트

$type 허용값

예시 JSON (브랜드 무관 — 플레이스홀더)

{
  "$schema": "https://design-tokens.github.io/community-group/format/",
  "$description": "<브랜드> Design Tokens — <출처 가이드라인> 흡수",
  "$version": "1.0.0",
  "$updatedAt": "YYYY-MM-DD",
  "color": {
    "brand": {
      "primary": { "$value": "#RRGGBB", "$type": "color",
        "$description": "<출처> 명시 — 브랜드 주색. 타이틀/CTA/아이콘" },
      "ink":     { "$value": "#RRGGBB", "$type": "color",
        "$description": "본문 텍스트 — #000 대체" }
    },
    "neutral": { "500": { "$value": "#RRGGBB", "$type": "color" } }
  },
  "typography": {
    "letterSpacing": {
      "display-tight": { "$value": "-0.075em", "$type": "dimension",
        "$description": "히어로 강조" },
      "body":          { "$value": "-0.025em", "$type": "dimension" }
    }
  }
}

$description은 **출처·의미(provenance)**를 각인하는 자리다 — 값이 어느 가이드라인/시스템에서 왔는지 토큰에 기록해 L1을 진실 원천으로 만든다.

L2 — 원시 CSS 변수 스키마

• --color-primary / --color-ink / --color-bg / --color-surface
• --neutral-50 … --neutral-950 (휘도 스케일)
• --tracking-display-tight 등 자간 변수(한국어 자간 규칙 인코딩)
• self-host @font-face (브랜드 폰트) + CDN 보조 폰트

CSS 변수 네이밍 규칙

• 다크모드: L2는 [data-theme="dark"] 스코프에서 값만 재정의(변수명 동일).
• 별칭(bg←background, fw←weight, tracking←letterSpacing, space←spacing, lh←lineHeight)은 표에 등록된 것만 사용 — 임의 축약 금지.

@font-face 블록 템플릿 (self-host)

/* 굵기 1개당 @font-face 1개 반복 */
@font-face {
  font-family: "<BrandFont>";
  font-weight: 400;                 /* 각 굵기별로 반복 (100~900) */
  font-style: normal;
  font-display: swap;               /* FOIT 방지 */
  src: url("./fonts/<BrandFont>-Regular.otf") format("opentype");
}
/* 보조 라틴/모노 폰트는 CDN @import */
@import url("https://fonts.googleapis.com/css2?family=<Latin>:wght@400;600;700&display=swap");

자간 변수 매핑표 (한국어 타이포 인코딩)

패턴(값은 브랜드마다 조정): 텍스트가 클수록 음의 자간을 강하게 준다 — 한국어 대형 타이포는 글자 사이 공백이 과해 보이므로 조이고, 캡션·소형 텍스트는 0으로 둔다. −25/−50/−75 명명은 -0.025/-0.05/-0.075em의 축약이다.

L3 — semantic/shadcn 롤 스키마

• --base-* 의미 롤: background/foreground/card/popover/surface/muted/primary/secondary/accent/destructive/border/input/ring/border-strong/chart-1..5/sidebar-*
• Tailwind v4 @theme + @layer base/utilities
• .dark 클래스 → CSS 변수 전환으로만 다크모드 ([HARD] dark: Tailwind 유틸리티 직접 사용 금지)

--base-* → shadcn 컴포넌트 롤 매핑표

@theme 블록 템플릿 (Tailwind v4)

@import 'tailwindcss';

@theme {
  --font-sans: "<BrandFont>", system-ui, sans-serif;
  --font-mono: "<Mono>", ui-monospace, monospace;

  --color-primary-50:  #RRGGBB;   /* … 950까지 11단계 */
  --color-primary-600: #RRGGBB;   /* 라이트 주색 */
  --color-primary-500: #RRGGBB;   /* 다크 주색 */
  --color-success: #RRGGBB; --color-warning: #RRGGBB;
  --color-danger:  #RRGGBB; --color-info:    #RRGGBB;

  --radius-sm: 0.5rem; --radius-lg: 1rem; --radius-full: 9999px;
  --duration-fast: 150ms; --ease-out: cubic-bezier(0.4, 0, 0.2, 1);
}

:root { /* --base-* 라이트 롤 바인딩 */ }
.dark { /* --base-* 다크 오버라이드 */ }

.dark override 규칙

• 다크모드는 오직 .dark 클래스 → CSS 변수 재정의로만. dark: Tailwind 유틸리티 직접 사용 금지([HARD]).
• primary: 명도 상향(어두운 배경 대비 확보) — 라이트 hover 톤에 해당하는 밝은 값으로.
• border/input: 불투명 그레이 → 반투명 화이트 rgba(255,255,255,0.06~0.16).
• chart-1..5: 전반 명도 상향.
• gradient: 밝은 스톱으로 교체.
• 오버라이드 대상만 재선언, 나머지는 :root 상속.

변환 절차 (스켈레톤)

정방향 — L1 → L2 → L3

1. L1 로드·검증 — DTCG JSON 파싱, $type별 유효성 확인, 그룹 완결성 검사
2. L1 → L2 파생 — brand/neutral/semantic 토큰을 --color-*/--neutral-*/--tracking-* CSS 변수로 평탄화, @font-face·CDN 폰트 블록 생성
   • 규칙: 그룹 카테고리를 접두 토큰으로, 마지막 1–2 세그먼트를 접미사로 매핑.
   • color.brand.<x>→--color-<x> (brand 제거) · color.brand.background→--color-bg (별칭)
   • color.neutral.<n>→--neutral-<n> · color.semantic.<x>→--color-<x> · color.gradient.<x>→--gradient-<x>
   • typography.family.<x>→--font-<x> · weight.<x>→--fw-<x> · size.<x>→--text-<x> · lineHeight.<x>→--lh-<x> · letterSpacing.<x>→--tracking-<x>
   • spacing.<n>→--space-<n> · radius.<x>→--radius-<x> · shadow.<x>→--shadow-<x> · motion.duration.<x>→--duration-<x> · motion.easing.<x>→--easing-<x>
   • 별칭(bg·fw·tracking·space·lh)은 표에 등록된 것만 — 유추 금지.
3. L2 → L3 파생 — 원시 변수를 --base-* semantic 롤에 바인딩, @theme 등록, .dark override 세트 생성
   • brand.primary → primary·ring·sidebar-primary·sidebar-ring·chart-1
   • brand.ink → foreground·card-foreground·popover-foreground · brand.background → background · brand.surface → card·popover·surface·sidebar
   • neutral.100 → muted·secondary·sidebar-accent · neutral.200 → border·input · neutral.600 → muted-foreground
   • semantic: success→success+chart-3 · warning→warning+accent+chart-2 · info→info+chart-4 · danger→destructive+error+chart-5
   • chart 파생: chart-1=primary · 2=warning|accent · 3=success · 4=info · 5=danger (상태색을 데이터 시리즈로 재사용해 팔레트 일관성 확보)
   • sidebar 파생: surface/ink/primary/muted를 미러 복제 → 사이드바가 본문과 같은 팔레트를 쓰되 독립 토글이 가능하도록 별도 롤로 둔다
4. FROZEN 규칙 검증 — 소스가 선언한 금지값(예: #000000 금지 → ink 대체), 단일 시그니처 그라디언트, 자간 규칙 등을 각 계층 코멘트로 인코딩
   • 메커니즘: 소스 시스템이 선언한 금지 규칙을 각 계층의 네이티브 주석 문법으로 인코딩해 산출물에 주입한다. 변환기는 금지값을 스스로 만들지 않음 — 소스에 선언이 없으면 주입도 없다.
   • 주입 위치: L1 = 토큰 $description + 파일 최상위 $description / L2 = CSS 헤더 주석(All tokens FROZEN per <출처>) + 대체값 인라인 주석(/* #000 대체 */, /* 변경 금지 */) / L3 = 헤더 주석 + [HARD] 인라인([HARD] 다크모드는 .dark 클래스로만).
   • 검증: 소스가 선언한 금지값(예: #000000)이 산출물에 유입됐는지만 대조.
   • worked example (특정 브랜드가 선언한 목록 — 보편 법칙 아님): #000 금지→ink 대체 · 임의 그라디언트 신설 금지 · 자간 규칙 준수 · dark: 유틸리티 금지. 다른 브랜드엔 다른 금지 목록이 온다.

역방향 — L3/L2 → L1

1. 소스 계층 식별 — 입력이 CSS(L2) / globals.css(L3) 중 어느 것인지 판별
2. 토큰 추출 — CSS 변수·@theme 선언에서 값·의미 역추출
3. DTCG 재구성 — 추출값을 계층적 그룹으로 재조립, $description은 best-effort 유도(원 출처 불명 시 명시)
   • 역매핑(정방향 표를 뒤집되 별칭 해소): --color-primary→color.brand.primary · --color-bg→color.brand.background · --neutral-<n>→color.neutral.<n> · --color-success류→color.semantic.<x> · --gradient-<x>→color.gradient.<x>
   • --fw-<x>→typography.weight.<x> · --text-<x>→size.<x> · --tracking-<x>→letterSpacing.<x> · --space-<n>→spacing.<n> · --duration-<x>→motion.duration.<x>
   • --base-<role>(L3)은 L2→L3 바인딩이라 L1 그룹에 직접 대응하지 않음 → 바인딩표(정방향 3단계) 역참조로 원천 토큰 복원.
   • $description 유도 정책: ① 선언 인접 인라인 주석을 승격 → ② 파일 헤더에서 출처(가이드라인/시스템명) 추출해 접두 → ③ 표준 토큰이면 카테고리 표준 설명 → ④ 모두 실패 시 창작 금지, "출처 미상" 명시.

라운드트립 무결성 검사

• L1 → L2 → L3 → (역) → L1' 왕복 후 L1 ≟ L1' 비교
• 색: hex 정규화 후 동등성, 타이포: family/weight/size 보존, 자간: 값 손실 없음
• 불일치 발견 시 계층·토큰 단위로 diff 리포트 정규화 규칙 (비교 전 양쪽 값에 동일 적용)

diff 리포트 포맷

## 라운드트립 diff (L1 vs L1')
| 왕복 | 토큰 경로 | 원본 | 왕복 후 | 판정 |
|---|---|---|---|---|
| L1→L2→L3→L1' | color.brand.primary | #RRGGBB | #RRGGBB | PASS |
| L1→L2→L3→L1' | typography.letterSpacing.body | -0.025em | -0.025em | PASS |
| L1→L2→L3→L1' | color.gradient.signature | linear-gradient(…) | (스톱 순서 상이) | FAIL |
정합: N PASS / M 불일치

출력 형식

## 토큰 변환 완료 (L{src} → L{dst})

### 변환 요약
- 입력 계층: L{n} ([파일])
- 출력 계층: L{m}
- 변환 토큰: 색 N · 타이포 N · spacing N · radius N · shadow N · motion N

### 생성 파일
- [출력 경로]

### 라운드트립 검사
- 왕복 정합: PASS / N개 불일치
- (불일치 시) 계층·토큰 단위 diff

### FROZEN 규칙 검증
- [위반 없음 / 위반 목록]

사용 예시

예시 1 — DTCG → shadcn 정방향 (L1 → L3)

입력: 02-tokens.json (L1 DTCG)
동작:
  1) color.brand.primary(#RRGGBB) → --color-primary → --base-primary/--base-ring/--base-chart-1
  2) @theme에 --color-primary-50..950 등록, :root에 --base-* 롤 바인딩
  3) .dark 오버라이드 세트 생성(primary 명도 상향, border 반투명 화이트)
출력: globals.css (@import tailwindcss + @theme + :root + .dark + @layer)
요약: 색 N · 자간 6 · radius 7 · shadow 6 / FROZEN 위반 0

예시 2 — globals.css → DTCG 역추출 (L3 → L1)

입력: globals.css (L3)
동작:
  1) @theme·:root·.dark 변수 선언 스캔
  2) --base-* 롤은 바인딩표 역참조로 원천 토큰 복원, --color-*/--neutral-*는 직접 역매핑
  3) 인접 주석에서 $description 유도, 불명은 "출처 미상"
출력: 02-tokens.json' (재구성 DTCG)
요약: 복원 토큰 N · $description 유도 N / 출처 미상 M

예시 3 — 라운드트립 검사 (L1 → L2 → L3 → L1')

입력: 02-tokens.json (L1)
동작: 정규화(hex 소문자·shorthand 확장·rgb→hex) 후 L1 ≟ L1'
출력: diff 리포트
결과: 12/13 PASS, 1 불일치(gradient 스톱 순서) → 계층·토큰 단위 표기

주의사항

Do

• L1(DTCG)을 항상 SSOT로 취급 — L2/L3은 파생물, 수동 편집 시 L1부터 갱신 후 재파생
• 다크모드는 .dark 클래스 CSS 변수 전환으로만 — Tailwind dark: 유틸리티 직접 사용 금지
• 자간(letter-spacing) 값을 손실 없이 전 계층 보존 — 한국어 타이포 품질의 핵심

Don't

• L2/L3만 수정하고 L1을 방치 금지 — 다음 재파생에서 덮어써짐
• #000000 등 FROZEN 금지값을 변환 산출물에 통과 금지
• 역추출 시 불명확한 $description을 임의 창작 금지 — 유도 불가 시 "출처 미상" 명시

관련 스킬