Figma → CSS 모션 토큰 자동 동기화 — Tokens Studio + Style Dictionary v4로 W3C DTCG 2025.10 transition 파이프라인 구축하기

디자이너가 Figma에서 버튼 hover 애니메이션의 easing을 수정했는데, 개발자가 그 변경을 뒤늦게 코드에 직접 반영하는 상황을 경험해본 적이 있으신가요? 이 동기화 문제는 디자인 시스템을 운영하는 팀이라면 피하기 어려운 고충입니다. 2025년 10월 28일, W3C 디자인 토큰 커뮤니티 그룹(DTCG)이 첫 번째 공식 안정화 스펙(2025.10)을 발표하면서 이 문제를 구조적으로 해결할 수 있는 표준이 마련됐습니다. 기존 드래프트 단계에서 논의되던 transition 복합 토큰 타입이 이 스펙에서 공식화됐습니다.

이 글에서는 DTCG 2025.10에 공식화된 transition 복합 토큰 타입을 중심으로, Figma Tokens Studio에서 토큰을 정의하고 Style Dictionary v4와 @tokens-studio/sd-transforms로 CSS 변수까지 자동 변환하는 전체 파이프라인을 구체적인 코드와 함께 살펴봅니다. 이 글을 통해 디자이너의 Figma 수정이 코드 빌드에 자동 반영되는 완전한 단방향 동기화 파이프라인을 직접 구성하실 수 있습니다.

이 글의 대상 독자: Figma와 Git을 사용 중이며 CSS 변수에 익숙한 프론트엔드/풀스택 개발자를 대상으로 합니다. Tokens Studio를 이미 사용 중이거나 도입을 검토 중인 팀에 특히 유용합니다. 읽는 데 약 15분이 소요됩니다.

핵심 개념

W3C DTCG transition 복합 토큰이란

DTCG 스펙에서 복합(composite) 토큰은 여러 원시(primitive) 토큰을 하나의 의미 단위로 묶은 타입입니다. transition 타입은 CSS transition 단축 속성과 정확히 대응하며, 세 가지 하위 속성으로 구성됩니다.

복합 토큰(Composite Token): 여러 원시 토큰 값을 하나의 의미 단위로 묶은 토큰 타입입니다. transition 외에도 typography, shadow, border, gradient가 DTCG 2025.10에서 복합 토큰으로 공식화됐습니다.

W3C DTCG 2025.10 스펙 기준으로 duration 토큰의 $value는 "150ms" 형태의 문자열입니다. { value: 150, unit: "ms" } 객체 형태는 Tokens Studio 레거시 포맷의 표기법이므로, 표준 JSON을 작성할 때는 아래와 같이 문자열로 표기하는 것을 권장합니다.

{
  "transition": {
    "emphasis": {
      "$type": "transition",
      "$value": {
        "duration": "200ms",
        "delay": "0ms",
        "timingFunction": [0.42, 0, 0.58, 1]
      }
    }
  }
}

$ 접두사: DTCG 2025.10 스펙에서 $type, $value처럼 $로 시작하는 키는 토큰의 메타데이터를 나타냅니다. 기존 Tokens Studio 레거시 포맷(type, value)과 구분되는 W3C 표준 표기입니다.

Style Dictionary와 sd-transforms의 역할

Style Dictionary는 JSON 형태의 디자인 토큰을 CSS, iOS(Swift), Android(XML) 등 다양한 플랫폼의 코드로 변환해주는 빌드 툴입니다. 토큰 자체는 수치와 구조만 정의하고, 플랫폼별 출력 포맷 변환은 Style Dictionary가 담당하는 것이 DTCG 스펙의 핵심 철학입니다.

@tokens-studio/sd-transforms 패키지는 Tokens Studio의 토큰 포맷을 Style Dictionary가 처리할 수 있도록 변환하는 보조 패키지입니다. registerTransforms(StyleDictionary) 한 줄로 Tokens Studio 관련 트랜스폼이 일괄 등록되며, transformGroup: 'tokens-studio'를 지정하면 등록된 트랜스폼 셋이 한 번에 적용됩니다.

토큰 참조({}) 구문으로 재사용성 높이기

transition 복합 토큰의 하위 값은 다른 토큰을 {경로} 형식으로 참조할 수 있습니다. duration이나 timingFunction을 별도 토큰으로 정의하고 여러 transition 토큰에서 참조하면, easing 곡선을 한 곳에서 수정해도 모든 전환 효과에 일관되게 반영됩니다.

실전 적용

Step 1: Figma Tokens Studio에서 motion 토큰 계층 구성하기

Tokens Studio 플러그인에서 Settings → Token Format → W3C DTCG로 전환한 후 아래와 같이 토큰을 작성합니다. 원시 토큰(cubicBezier, duration)을 먼저 정의하고 transition 토큰에서 참조하는 계층 구조가 핵심입니다.

{
  "motion": {
    "easing": {
      "standard": {
        "$type": "cubicBezier",
        "$value": [0.4, 0, 0.2, 1]
      }
    },
    "duration": {
      "short": {
        "$type": "duration",
        "$value": "150ms"
      },
      "medium": {
        "$type": "duration",
        "$value": "300ms"
      }
    },
    "transition": {
      "standard": {
        "$type": "transition",
        "$value": {
          "duration": "{motion.duration.medium}",
          "delay": "0ms",
          "timingFunction": "{motion.easing.standard}"
        }
      }
    }
  }
}

Step 2: GitHub Sync로 Figma → Git 자동 push 설정하기

Tokens Studio에서 Settings → Sync providers → Add new → GitHub로 이동해 저장소 정보를 입력하면 토큰 변경을 Git으로 직접 push할 수 있습니다.

저장소:   your-org/design-tokens
브랜치:   main
파일 경로: tokens/motion.json

설정 후 토큰을 수정하고 Push to GitHub 버튼을 누르면 PR이 자동 생성됩니다. 파일 경로에는 반드시 .json 확장자를 포함하는 것을 권장합니다. 확장자를 생략하면 무소음 실패(silent failure)가 발생할 수 있습니다.

DTCG 포맷으로 전환 시에는 플러그인이 w3c-dtcg-conversion 브랜치를 별도 생성해 변환본을 push하므로 기존 파일과 충돌 없이 마이그레이션을 검토할 수 있습니다.

Step 3: Style Dictionary v4 + sd-transforms로 CSS 변수 빌드하기

필요한 패키지를 설치합니다.

pnpm add style-dictionary @tokens-studio/sd-transforms

Style Dictionary v4는 ES Module(import/export) 문법을 사용합니다. 아래 설정 파일을 사용하려면 package.json에 "type": "module"을 추가하거나, 파일 확장자를 .mjs로 지정해야 합니다.

// package.json
{
  "type": "module",
  "scripts": {
    "build:tokens": "style-dictionary build --config style-dictionary.config.js"
  }
}

// style-dictionary.config.js
import StyleDictionary from 'style-dictionary';
import { registerTransforms } from '@tokens-studio/sd-transforms';
 
// Tokens Studio 전용 트랜스폼을 Style Dictionary에 일괄 등록
registerTransforms(StyleDictionary);
 
export default {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      // 'tokens-studio' 그룹은 registerTransforms()로 등록된 트랜스폼 셋을 포함합니다.
      // 아래 transforms 배열은 그룹에 포함되지 않은 추가 트랜스폼만 지정합니다.
      transformGroup: 'tokens-studio',
      transforms: [
        'ts/transition/css/shorthand',  // transition 복합 토큰 → CSS shorthand
        'name/kebab',
      ],
      buildPath: 'dist/tokens/',
      files: [{
        destination: 'tokens.css',
        format: 'css/variables',
      }],
    },
  },
};

빌드를 실행합니다.

pnpm build:tokens

다음과 같은 CSS 파일이 생성됩니다.

/* dist/tokens/tokens.css */
:root {
  --motion-easing-standard: cubic-bezier(0.4, 0, 0.2, 1);
  --motion-duration-short: 150ms;
  --motion-duration-medium: 300ms;
  --motion-transition-standard: 300ms cubic-bezier(0.4, 0, 0.2, 1) 0ms;
}

Step 4: React/Next.js 컴포넌트에서 transition 토큰 활용하기

빌드된 CSS 변수를 글로벌 스타일에서 import하고, CSS Modules 파일에서 참조합니다.

/* styles/globals.css */
@import '../dist/tokens/tokens.css';

/* components/Button.module.css */
.button {
  background-color: #1a73e8;
  padding: 8px 16px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  /* transition 토큰 변수를 각 속성에 적용 */
  transition:
    background-color var(--motion-transition-standard),
    transform var(--motion-transition-standard),
    box-shadow var(--motion-transition-standard);
}
 
.button:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

// components/Button.tsx
import styles from './Button.module.css';
 
export function Button({ children }: { children: React.ReactNode }) {
  return <button className={styles.button}>{children}</button>;
}

이제 디자이너가 Figma에서 motion.duration.medium을 300ms에서 250ms로 수정하고 GitHub에 push하면, CI에서 Style Dictionary 빌드가 자동 실행되어 --motion-transition-standard가 250ms cubic-bezier(0.4, 0, 0.2, 1) 0ms로 업데이트됩니다. 개발자가 직접 개입할 필요가 없습니다.

장단점 분석

장점

단점 및 주의사항

실무에서 가장 흔한 실수

1. Tokens Studio의 Token Format을 레거시로 유지한 채 DTCG 토큰을 작성하는 경우 — Settings → Token Format을 반드시 W3C DTCG로 전환한 후 토큰을 작성해야 $type, $value 키가 올바르게 저장됩니다. 레거시 포맷에서는 $ 접두사가 일반 키로 처리되어 변환 과정에서 의도치 않은 결과가 발생할 수 있습니다.
2. ts/transition/css/shorthand 트랜스폼을 누락하는 경우 — 이 트랜스폼 없이 빌드하면 transition 복합 토큰이 CSS shorthand가 아닌 중첩 객체 형태로 출력되어 CSS 변수로 사용할 수 없습니다.
3. GitHub Sync 파일 경로에 .json 확장자를 포함하지 않는 경우 — tokens/motion 같은 경로보다 tokens/motion.json처럼 명시적으로 확장자를 포함한 경로를 권장합니다. 경로 오류는 오류 메시지 없이 조용히 실패할 수 있습니다.

마치며

DTCG 2025.10의 transition 복합 토큰은 디자인과 코드 사이의 모션 동기화 문제를 표준화된 방식으로 해결하는 공식 도구가 됐습니다. 이제 easing 곡선 하나를 수정해도 Figma, Git, CSS가 모두 같은 값을 바라보는 워크플로를 팀에 도입할 수 있습니다.

지금 바로 시작해볼 수 있는 3단계:

1. Tokens Studio 설치 및 포맷 전환 (약 5분, Figma 접근 필요): Figma에서 Tokens Studio 플러그인을 설치하고 Settings → Token Format을 W3C DTCG로 전환한 후, motion.easing, motion.duration, motion.transition 계층을 위 예시 JSON을 참고해 작성해보시면 좋습니다.
2. Style Dictionary 빌드 환경 구성 (약 15분, 기존 프로젝트 필요): 프로젝트 루트에서 pnpm add style-dictionary @tokens-studio/sd-transforms를 실행하고, 위 style-dictionary.config.js 예시와 package.json scripts 설정을 참고해 pnpm build:tokens가 정상 동작하는지 확인해보실 수 있습니다.
3. GitHub Actions CI 연결 (약 20분, GitHub 저장소 필요): tokens/**/*.json 변경 시 Style Dictionary 빌드가 자동 실행되도록 .github/workflows/tokens.yml을 구성하면 완전한 자동화 파이프라인이 완성됩니다. 기본 워크플로 구성 방법은 다음 글에서 자세히 다룰 예정입니다.

다음 글: Style Dictionary v4의 $extends 그룹 상속과 GitHub Actions 파이프라인을 함께 활용해 라이트/다크 모드와 멀티브랜드 테마를 파일 복제 없이 자동 배포하는 토큰 아키텍처 설계 방법을 다룰 예정입니다.

참고 자료

• Design Tokens Format Module 2025.10 공식 스펙 | W3C DTCG — transition 복합 토큰 타입 정의 원문
• Design Tokens specification reaches first stable version | W3C DTCG 공식 발표 — 2025.10 안정화 스펙 발표 배경
• Design Tokens Technical Reports 2025.10 | W3C DTCG — 스펙 전문 목록
• DTCG GitHub 공식 저장소 — 스펙 이슈 및 변경 히스토리 추적
• Style Dictionary DTCG 지원 가이드 | styledictionary.com — v4의 DTCG 지원 범위 및 마이그레이션 가이드
• Style Dictionary Built-in Transforms | styledictionary.com — 내장 트랜스폼 레퍼런스
• Style Dictionary + SD Transforms 연동 가이드 | Tokens Studio Docs — sd-transforms 설정 실전 가이드
• sd-transforms GitHub 저장소 | tokens-studio — 패키지 소스 및 릴리스 노트
• Token Format — W3C DTCG vs Legacy | Tokens Studio Docs — $ 접두사 포맷 전환 방법
• Tokens Studio GitHub Sync 가이드 | Tokens Studio Docs — GitHub Sync 상세 설정
• What's new in the Design Tokens spec | zeroheight 블로그 — 2025.10 주요 변경 사항 요약
• Understanding W3C Design Token Types | Francesco Improta — 복합/원시 토큰 타입 개념 심화